Merge pull request #146 from chrisrueger/documentation-7-1

Documentation additions for next 7.1

_includes/sidebar.htm

@@ -18,6 +18,7 @@
       <li><a href="/manual/resolution-view.html">Resolution View</a></li>
       <li><a href="/manual/bndeditor.html">The bnd Editor</a></li>
       <li><a href="/manual/jareditor.html">The JAR Viewer</a></li>
+      <li><a href="/manual/templates.html">Project Templates</a></li>
     </ul>
   </li>
 

_layouts/default.html

@@ -21,11 +21,13 @@
             </aside>
 
             <!-- main content goes here -->
+            {% if page.since %}<span class="secondary round label right" style="margin-bottom:5px;" title="The content below assumes bndtools version {{ page.since }}."><a href="https://github.com/bndtools/bnd/wiki/Changes-in-{{ page.since }}" target="_blank">Since {{ page.since }}</a></span></span>{% endif %}
             <div class="hero">
               <h1>{{ page.title }}</h1>
             </div>
+
             {{content}}
-
+            
           <!-- close the off-canvas menu -->
           <a class="exit-off-canvas"></a>
 

_manual/resolution-view.md

@@ -1,10 +1,36 @@
 ---
 title: Resolution View
 description: Provides insight into the requirements and capabilities of the selected bundle
+since: 7.1.0
 ---
 
-<img src="/images/resolution-view.png" style="width:750px" class="view">
+![](/images/resolution-view.png)
 
-To see the requirements and capabilities of a bundle Bndtools has a special Resolution view. This shows the requirements and capabilities of a selected JAR file or a `bnd.bnd` file.
+The Resolution View is a powerful tool to analyse the requirements and capabilities of bundles and their dependencies. This shows the **requirements and capabilities** side by side of one or multiple selected resources such as JAR file(s), a `bnd.bnd` file or entries in the Repository Browser (bundles in a repository or repositories).
 
-More information can be found in the manual at [Resolving Dependencies](https://bnd.bndtools.org/chapters/250-resolving.html).
+Especially when it comes to resolution issues (e.g. required package cannot be satisfied by another bundle) this is the tool to **make resolution issues visible**.
+
+## Example
+
+By selecting a bundle **A** and a repository **R** in the [Repository View](/manual/repositories-view.html), it allows you to see the aggregated **Requirements and Capabilities** of both. In other words it shows you:
+
+* all **requirements** (most commonly packages) the bundle **A** and all bundles in the repository **R** require
+* and all **capabilities** the bundle **A** and all bundles in the repository **R** provide
+
+If there is a _requirement_ for which _no other_ bundle provides a _capability_, then the Resolve would fail - and you can **make that visible** in the resolution view.
+
+This makes it a valueable tool used after a failed resolution (see the *Resolve* button in the [.bnd / .bndrun editor](/manual/bndeditor.html#run)) and its (sometimes cryptic) error message.
+
+
+## Features
+
+* Search filter for Requirements and Capabilities allowing wildcards and multiple search terms
+* Filter toggle to hide optional requirements
+* Filter toggle to detect (problematic) capabilities which are exported by multiple bundles but with different package content (split package problem)
+* Copy to clipboard via `Ctrl / Cmd + C` for Requirements and Capabilities which copies their tooltip contents. This helps during debugging and communicating with others about it.
+* Double Clicking on an entry of the ResolutionsView (Requirements and Capabilities) opens the _Advanced Search_ of _Repository Browser_ in the "Other" tab and prefills the fields for namespace and filter
+* Drag&Drop of selected Requirements in other panels e.g. to drag&drop selected entries to the _Customize imports_ panel of the .bnd-editor
+
+## More information
+
+Background information can also be found in the manual at [Resolving Dependencies](https://bnd.bndtools.org/chapters/250-resolving.html).

_manual/templates-osgi-service.md

@@ -0,0 +1,63 @@
+---
+title: Java OSGi Service
+description: Bndtools Template to create an OSGi service consisting of bundles for api, impl, consumer
+since: 7.1.0
+---
+
+## Java OSGi Service (api, impl, consumer)
+
+This template is based on the idea of [this tutorial](../tutorial.html) and will create three bundles for a typical OSGi service scenario:
+- api bundle - contains the interface of a service
+- impl bundle - contains the implementation class (`@Component`) of the service interface
+- consumer bundle - contains an example of a class which consumes the service without relying on the implementation directly but letting the OSGi Framework inject it by `@Reference`
+
+
+**Requirements**: 
+- bndtools Eclipse-Plugin has been installed
+- a new [Bnd Workspace](../workspace.html) has been created (e.g. using the bndtools.workspace.min template)
+
+### 1. Open the wizard, select File->New->Other...
+
+![](/images/templates/template-osgi-service1.png)
+
+### 2. Then select OSGi Services -> Java OSGi Service (api, impl, consumer) and Next>
+
+![](/images/templates/template-osgi-service2.png)
+
+### 3. Fill in desired values for the Project Name and the Service Name fields, and make any other desired changes to the execution environment or project set usage on the wizard page.
+
+![](/images/templates/template-osgi-service3.png)
+
+### 4. Click Finish
+
+![](/images/templates/template-osgi-service4.png)
+
+There are three projects created org.myorg.test.hello (api), org.myorg.test.hello.impl, and org.myorg.test.hello.consumer.
+
+The three Java classes created (in each of the projects) are shown in the edit window (HelloService, HelloServiceImpl, HelloServiceConsumer).
+
+If desired, the user can use Eclipse refactoring to rename the default service method (named methodName) to (e.g.) hello, resulting in:
+
+### 5. Run/Debug the project
+
+Included in the generated `org.myorg.test.hello` project is a `Hello.bndrun` file that can be used to launch a framework, register the HelloServiceImpl, inject (via SCR) into the HelloServiceConsumer and have the HelloServiceConsumer call the service.
+
+![](/images/templates/template-osgi-service5.png)
+
+### 6. Resolving dependencies
+
+Click `Resolve` and the `Update` to let bndtools figure out the bundles to run (-runbundles).
+
+![](/images/templates/template-osgi-service6.png)
+
+### 7. Run the project
+
+![](/images/templates/template-osgi-service7.png)
+
+Then clicking on Run OSGi (or Debug OSGi). Results in the service method being called and the console output.
+
+
+### Next steps
+
+Now you have a good starting point to develop your service. 
+In an existing project you probably do not need the generated consumer bundle if you already have other bundles consuming the service. Feel free to remove this generated bundle then (you may need to remove this bundle from the `.bndrun` `-runbundles` section).

_manual/templates.md

@@ -0,0 +1,9 @@
+---
+title: Project Templates
+description: Get started faster with Bnd Project templates.
+---
+
+The Bndtools supports wizard-based creation of various elements required for OSGi development. There are templates for Bnd-Workspaces, Projects , Components, .bnd and .bndrun files and even for creating services consisting of multiple bundles.
+
+- [Java OSGi Service](templates-osgi-service.html) - Create a service consisting of three bundles for api, impl, consumer
+

development.md

@@ -54,7 +54,7 @@ You should now have all the bndtools projects in your workspace, ready to begin
 To launch bndtools from Eclipse (e.g. to try out a change to debug), use one of the `.bndrun` files from the `bndtools.core` project. There are three launchers, one per architecture, i.e.:
 
 * `bndtools.cocoa.macosx.x86_64.bndrun` for running on MacOS (64-bit Intel x86)
-* `bndtools.cocoa.macosx.aarch64.bndrun` for running on MacOS (64-bit Apple Silicon M1/M2 AArch64)
+* `bndtools.cocoa.macosx.aarch64.bndrun` for running on MacOS (64-bit Apple Silicon / AArch64)
 * `bndtools.gtk.linux.x86_64.bndrun` for running on Linux (64-bit Intel x86).
 * `bndtools.gtk.linux.x86.bndrun` for running on Linux (32-bit Intel x86).
 * `bndtools.win32.x86.bndrun` for running on Win32 (XP, Vista etc).