felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1421893 [19/24] - in /felix/site/trunk/content: ./ documentation/ documentation/community/ documentation/development/ documentation/faqs/ documentation/subprojects/ documentation/subprojects/apache-felix-commons/ documentation/subprojects/...
Date Fri, 14 Dec 2012 14:30:22 GMT
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/web-console-restful-api.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/web-console-restful-api.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/web-console-restful-api.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/web-console-restful-api.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,283 @@
+Title: Web Console RESTful API
+
+# Web Console RESTful API
+
+[TOC]
+
+<div class="warning" markdown="1">
+Please note that the APIs described on this page have not been standardized or stabilized yet. As such they cannot be relied upon. They are merely a description of the current code. In future releases these APIs will be fixed to be properly RESTful.
+</div>
+
+## URL Space
+
+The Web Console URL space is by default rooted at `/system/console` inside the Servlet Context used by the OSGi Http Service. This default can be reconfigured, though this is not really recommended.
+
+It is expected that the Web Console owns the complete URL space below the root path.
+
+The next level in the URL Space of the Web Console is defined by the labels defined by the registered Web Console plugins. For example the Bundles plugins registers itself with the `bundles` label.
+
+
+## Request Methods
+
+ALthough the HTTP RFC defines a number of request methods and the REST architectural style mandates to use these methods as intended by the specification, Web Browsers in general only support the GET and POST methods. Moreover, firewall administrators more often than not block all HTTP methods except GET and POST. For this reason the Web Console limits the used methods to just these two.
+
+
+## Bundles Plugin
+
+### URLs
+
+`.../bundles` -- addresses all bundles in the framework
+`.../bundles/*id*` -- addresses a single bundle in the framework. The `*id*` can in this case be the bundle's ID (as per `Bundle.getBundleId()`), the bundle's symbolic name (which actually may cause multiple bundles to be addressed), or the bundle's symbolic name and version separated by a colon. Examples are `.../bundles/0`, `.../bundles/org.apache.felix.webconsole`, and `.../bundles/org.apache.felix.webconsole:3.1.4`.
+
+### GET Requests
+
+GET requests are used to retrieve information on the bundles (or bundle) available in the framework. To response formats are currently supported: regular HTML and JSON if requests are sent with the `.json` extension; e.g. `.../bundles/0.json`. The HTML response is destined at browsers and is not further described here.
+
+#### GET .../bundles.json
+
+<div class="note" markdown="1">
+Due to a bug ([FELIX-3132](https://issues.apache.org/jira/browse/FELIX-3132)) the form `.../bundles.json` only works in builds after SVN Revision 1175527. As a workaround request `.../bundles/.json`
+</div>
+
+Request to this URL sends back an overview of all bundles along with an overview of all bundles (bundles existing, active, fragment, resolved, installed)
+
+    {
+       "status": "Bundle information: 84 bundles in total - all 84 bundles active.",
+       "s": [ 84, 81, 3, 0, 0 ],
+       "data": [
+          {
+             "id": 0,
+             "name": "System Bundle",
+             "fragment": false,
+             "stateRaw": 32,
+             "state": "Active",
+             "version": "3.0.8",
+             "symbolicName": "org.apache.felix.framework",
+             "category": ""
+          },
+          ....
+       ]
+    }
+
+
+
+#### GET .../bundles/id.json
+
+This URL returns detailed information of a bundle like the bundle headers, imported packages, exported packages, importing bundles, registered services.
+
+
+    {
+        "status": "Bundle information: 84 bundles in total - all 84 bundles active.",
+        "s": [
+            84,
+            81,
+            3,
+            0,
+            0
+        ],
+        "data": [
+            {
+                "id": 23,
+                "name": "Apache Felix Web Management Console",
+                "fragment": false,
+                "stateRaw": 32,
+                "state": "Active",
+                "version": "3.1.9.SNAPSHOT",
+                "symbolicName": "org.apache.felix.webconsole",
+                "category": "",
+                "props": [
+                    {
+                        "key": "Symbolic Name",
+                        "value": "org.apache.felix.webconsole"
+                    },
+                    {
+                        "key": "Version",
+                        "value": "3.1.9.SNAPSHOT"
+                    },
+                    {
+                        "key": "Bundle Location",
+                        "value": "slinginstall:org.apache.felix.webconsole-3.1.6.jar"
+                    },
+                    {
+                        "key": "Last Modification",
+                        "value": "Sun Sep 25 20:59:46 CEST 2011"
+                    },
+                    {
+                        "key": "Bundle Documentation",
+                        "value": "http://felix.apache.org/site/apache-felix-web-console.html"
+                    },
+                    {
+                        "key": "Vendor",
+                        "value": "The Apache Software Foundation"
+                    },
+                    {
+                        "key": "Description",
+                        "value": "Web Based Management Console for OSGi Frameworks. See http://felix.apache.org/site/apache-felix-web-console.html for more information on this bundle."
+                    },
+                    {
+                        "key": "Start Level",
+                        "value": 5
+                    },
+                    {
+                        "key": "Exported Packages",
+                        "value": [
+                            "org.apache.felix.webconsole,version=3.1.2"
+                        ]
+                    },
+                    {
+                        "key": "Imported Packages",
+                        "value": [
+                            "javax.servlet,version=2.5.0 from <a href='/system/console/bundles/15'>org.apache.felix.http.jetty (15)</a>",
+                            "javax.servlet.http,version=2.5.0 from <a href='/system/console/bundles/15'>org.apache.felix.http.jetty (15)</a>",
+                            "org.apache.felix.scr,version=1.6.0 from <a href='/system/console/bundles/11'>org.apache.felix.scr (11)</a>",
+                            "org.osgi.framework,version=1.5.0 from <a href='/system/console/bundles/0'>org.apache.felix.framework (0)</a>",
+                            "org.osgi.service.cm,version=1.3.0 from <a href='/system/console/bundles/9'>org.apache.felix.configadmin (9)</a>",
+                            "org.osgi.service.http,version=1.2.0 from <a href='/system/console/bundles/15'>org.apache.felix.http.jetty (15)</a>",
+                            "org.osgi.service.log,version=1.3.0 from <a href='/system/console/bundles/6'>org.apache.sling.commons.logservice (6)</a>",
+                            "org.osgi.service.metatype,version=1.1.0 from <a href='/system/console/bundles/12'>org.apache.felix.metatype (12)</a>",
+                            "org.osgi.service.packageadmin,version=1.2.0 from <a href='/system/console/bundles/0'>org.apache.felix.framework (0)</a>",
+                            "org.osgi.service.startlevel,version=1.1.0 from <a href='/system/console/bundles/0'>org.apache.felix.framework (0)</a>"
+                        ]
+                    },
+                    {
+                        "key": "Importing Bundles",
+                        "value": [
+                            "<a href='/system/console/bundles/19'>org.apache.felix.webconsole.plugins.memoryusage (19)</a>",
+                            "<a href='/system/console/bundles/62'>org.apache.sling.commons.mime (62)</a>",
+                            "<a href='/system/console/bundles/14'>org.apache.sling.extensions.threaddump (14)</a>",
+                            "<a href='/system/console/bundles/20'>org.apache.sling.extensions.webconsolesecurityprovider (20)</a>",
+                            "<a href='/system/console/bundles/18'>org.apache.sling.jcr.webconsole (18)</a>"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/369'>369</a>",
+                        "value": [
+                            "Types: org.apache.felix.webconsole.ConfigurationPrinter"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/370'>370</a>",
+                        "value": [
+                            "Types: org.apache.felix.webconsole.ConfigurationPrinter"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/371'>371</a>",
+                        "value": [
+                            "Types: org.apache.felix.webconsole.ConfigurationPrinter"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/372'>372</a>",
+                        "value": [
+                            "Types: org.apache.felix.webconsole.ConfigurationPrinter"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/373'>373</a>",
+                        "value": [
+                            "Types: org.apache.felix.webconsole.ConfigurationPrinter"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/374'>374</a>",
+                        "value": [
+                            "Types: org.apache.felix.webconsole.ConfigurationPrinter"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/375'>375</a>",
+                        "value": [
+                            "Types: org.apache.felix.webconsole.ConfigurationPrinter"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/376'>376</a>",
+                        "value": [
+                            "Types: org.osgi.service.cm.ManagedService, org.osgi.service.metatype.MetaTypeProvider",
+                            "Service PID: org.apache.felix.webconsole.internal.servlet.OsgiManager",
+                            "Description: OSGi Management Console Configuration Receiver",
+                            "Vendor: The Apache Software Foundation"
+                        ]
+                    },
+                    {
+                        "key": "Service ID <a href='/system/console/services/453'>453</a>",
+                        "value": [
+                            "Types: org.apache.felix.webconsole.ConfigurationPrinter"
+                        ]
+                    },
+                    {
+                        "key": "Manifest Headers",
+                        "value": [
+                            "Bnd-LastModified: 1316977184980",
+                            "Build-Jdk: 1.6.0_13",
+                            "Built-By: fmeschbe",
+                            "Bundle-Activator: org.apache.felix.webconsole.internal.OsgiManagerActivator",
+                            "Bundle-Description: Web Based Management Console for OSGi Frameworks. See http://felix.apache.org/site/apache-felix-web-console.html for more information on this bundle.",
+                            "Bundle-DocURL: http://felix.apache.org/site/apache-felix-web-console.html",
+                            "Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt",
+                            "Bundle-ManifestVersion: 2",
+                            "Bundle-Name: Apache Felix Web Management Console",
+                            "Bundle-SymbolicName: org.apache.felix.webconsole",
+                            "Bundle-Vendor: The Apache Software Foundation",
+                            "Bundle-Version: 3.1.9.SNAPSHOT",
+                            "Created-By: Apache Maven Bundle Plugin",
+                            "DynamicImport-Package: org.apache.felix.bundlerepository, org.osgi.service.obr",
+                            "Export-Package: org.apache.felix.webconsole; uses:=\"javax.servlet, org.osgi.framework, javax.servlet.http\"; version=\"3.1.2\"",
+                            "Import-Package: javax.servlet; version=\"2.4\", javax.servlet.http; version=\"2.4\", org.apache.felix.scr; resolution:=optional; version=\"1.0\", org.apache.felix.shell; resolution:=optional, org.apache.felix.webconsole; version=\"3.1.2\", org.osgi.framework, org.osgi.service.cm; resolution:=optional, org.osgi.service.condpermadmin; resolution:=optional, org.osgi.service.deploymentadmin; resolution:=optional, org.osgi.service.http, org.osgi.service.log; resolution:=optional, org.osgi.service.metatype; resolution:=optional, org.osgi.service.packageadmin; resolution:=optional, org.osgi.service.permissionadmin; resolution:=optional, org.osgi.service.prefs; resolution:=optional, org.osgi.service.startlevel; resolution:=optional, org.osgi.service.wireadmin; resolution:=optional",
+                            "Manifest-Version: 1.0",
+                            "Tool: Bnd-0.0.255"
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+
+
+
+### POST Requests
+
+To update the bundles the `action` request method is used to indicate the action:
+
+| Action | Requires a Bundle | Description |
+|--|--|--|
+| `refreshPackages` | no | Calls `PackageAdmin.refreshPackages(Bundle[]({{ refs..path }}))` with a `null` argument -- refreshing all pending bundles |
+| `install` | no | Installs (or updates) and optionally starts one or more bundles. Parameters:
+* `bundlestart` -- whether to start newly installed bundles or not. Has no influence on updated bundles.
+* `bundlestartlevel` -- the start level to set on newly installed bundles. Has no influence on updated bundles.
+* `bundlefile` -- one or more uploaded files being the bundles to install or update. The manifests in the bundles are inspected to see whether any bundle is an update or new install.
+* `refreshPackages` -- whether to call `PackageAdmin.refreshPackages(Bundle[]({{ refs..path }}))` with the installed/updated bundles after installation/update. |
+| `start` | yes | Starts the bundle |
+| `stop` | yes | Stops the bundle |
+| `refresh` | yes | Calls `PackageAdmin.refreshPackages(Bundle[]({{ refs..path }}))` with the bundle as its sole argument thus forcing the bundle to be rewired. |
+| `update` | yes | Calls `Bundle.update()` on the bundle or tries to update the bundle through the OBR. |
+| `uninstall` | yes | Calls `Bundle.uninstall()` on the bundle. |
+
+
+The response on those actions requiring a bundle is a simple JSON response:
+
+
+    {
+        "fragment": -- whether the bundle is a fragement
+        "stateRaw": -- the state code of the bundle after executing the action
+    }
+
+
+Since some bundle operations take place asynchronously a short delay of 800ms is inserted before preparing and sending the response.
+
+The response on those actions not taking a bundle is the bundle overview of the bundles in the framework as if requesting `.../bundles.json`. Again a delay of 800ms is inserted since some operations are executed asynchronously.
+
+
+## Services Plugin
+
+
+TBD
+
+
+## Configuration Admin Plugin
+
+
+TBD
+
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/web-console-security-provider.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/web-console-security-provider.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/web-console-security-provider.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/web-console-security-provider.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,92 @@
+Title: Web Console Security Provider
+
+# Web Console Security Provider
+
+[TOC]
+
+As of Apache Felix Web Console 3.1.0 security of the Web Console can be extended by providing a `WebConsoleSecurityProvicer` service. An extension to this service has been introduced with the `WebConsoleSecurityProvider2` service in Apache Felix Web Console 3.1.4.
+
+## WebConsoleSecurityProvider
+
+The `WebConsoleSecurityProvider` service provides two methods:
+
+{code:java}
+/**
+ * Authenticates the user with the given user name and password.
+ *
+ * @param username The name of the user presented by the client
+ * @param password The password presented by the client
+ * @return Some object representing the authenticated user indicating general
+ *         access to be granted to the web console. If the user cannot be
+ *         authenticated (e.g. unknown user name or wrong password) or the
+ *         user must not be allowed access to the web console at all
+ *         <code>null</code> must be returned from this method.
+ */
+public Object authenticate( String username, String password );
+
+
+/**
+ * Checks whether bthe authenticated user has the given role permission.
+ *
+ * @param user The object referring to the authenticated user. This is the
+ *      object returned from the {@link #authenticate(String, String)}
+ *      method and will never be <code>null</code>.
+ * @param role The requested role
+ * @return <code>true</code> if the user is given permission for the given
+ *      role.
+ */
+public boolean authorize( Object user, String role );
+
+    
+    {note}
+    Use of the {{authorize}} method is not currently implemented, though. Mainly this is because it is not readily clear, what exactly the {{role}} means. One possible interpretation could be that this is the label of the plugin whose access is checked. Or it might be a combination of the plugin called and the request method used.
+    {note}
+    
+    The drawback of the {{WebConsoleSecurityProvider}} interface is that it just provides a mechanism to check for a user name and password using HTTP BASIC authentication. If other authenication mechanisms should be used the {{WebConsoleSecurityProvider2}} interface introduced in Apache Felix Web Console 3.1.4 can be used.
+    
+    
+    h2. WebConsoleSecurityProvider2
+    
+    The {{WebConsoleSecurityProvider2}} interface extends the {{WebConsoleSecurityProvider}} by a single method:
+    
+    {code:java}
+    /**
+     * The name of the request attribute providing the object representing the
+     * authenticated user. This object is used to call the
+     * {@link WebConsoleSecurityProvider#authorize(Object, String)} to
+     * authorize access for certain roles.
+     */
+    String USER_ATTRIBUTE = "org.apache.felix.webconsole.user";
+    
+    
+    /**
+     * Authenticates the given request or asks the client for credentials.
+     * <p>
+     * Implementations of this method are expected to respect and implement
+     * the semantics of the <code>HttpContext.handleSecurity</code> method
+     * as specified in the OSGi HTTP Service specification.
+     * <p>
+     * If this method returns <code>true</code> it is assumed the request
+     * provided valid credentials identifying the user as accepted to access
+     * the web console. In addition, the {@link #USER_ATTRIBUTE} request
+     * attribute must be set to a non-<code>null</code> object reference
+     * identifying the authenticated user.
+     * <p>
+     * If this method returns <code>false</code> the request to the web console
+     * is terminated without any more response sent back to the client. That is
+     * the implementation is expected to have informed the client in case of
+     * non-granted access.
+     *
+     * @param request The request object
+     * @param response The response object
+     * @return <code>true</code> If the request provided valid credentials.
+     */
+    public boolean authenticate( HttpServletRequest request, HttpServletResponse response );
+
+
+This method is in full control of authentication and thus has to extract the user credentials from the request and can also fail the request.
+
+
+## Sample
+
+A sample of a `WebConsoleSecurityProvider` service is the Apache Sling implementation [`SlingWebConsoleSecurityProvider`](http://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/webconsolesecurityprovider/src/main/java/org/apache/sling/extensions/webconsolesecurityprovider/internal/SlingWebConsoleSecurityProvider.java). This implementation uses a JCR implementation to login to the repository and thus validate the credentials.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/mosgi-managed-osgi-framework.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/mosgi-managed-osgi-framework.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/mosgi-managed-osgi-framework.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/mosgi-managed-osgi-framework.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,83 @@
+Title: MOSGi Managed OSGi framework
+
+MOSGi enables the remote management of OSGi-compatible service gateways, using JMX. The framework is a reference architecture for end-to-end gateway management. It provides the following features:
+* relies on JMX management infrastructure (IP-based 	management),
+* provides two JMX agents: the standard Java 1.5 agent and a 	specific Java 1.4 lightweight embedded agent (MX4J agent deviation),
+* provides a way to deploy various probes on remote gateways,
+* provides a management console,
+* the graphical part of a probe (management console part) can 	be dynamically plugged in the management console and is dynamically 	downloaded.
+
+# Very fast QuickStart Guide
+
+Go into $FELIX_HOME/trunk/mosgi.doc and read Readme.txt.
+
+# General architecture
+
+The overall architecture is presented in the following picture :
+
+!MOSGiArchitecture.png!
+
+# How it works
+
+Managed OSGi gateways can install JMX probes from various repositories. A JMX probe is a standard OSGi bundle that registers an [#MBean]({{ refs.-mbean.path }}) component in the managed gateway's JMX agent.
+
+The management console (running in a standard OSGi framework) is connected to each gateway through the JMX remoting protocol. When it connects for the first time to a managed gateway, it asks for probes that are installed (i.e. all MBeans registered in the TabUI JMX domain). Then, for each MBean found, the management console asks for its graphical representation through a call to our standard API (component getUI() call). This call redirects to a bundle in the GUI probe repository that is installed by the management console. So the management console discovers at run-time the user interface it should use to
+supervise a specific remote gateway.
+
+Here is a description of different bundles that should be installed on both parts of the infrastructure (managed OSGi gateway and Management console).
+
+A managed OSGi gateway must host the following bundles :
+* JMX-MX4J Agent Service: provides a JMX agent. Either through a wrapper to jdk1.5 standard agent or through using a specific lightweight inner agent1 (originate from mx4j project). This agent service also declares a standard MBeanServer service interface..
+
+* JMX rmiregistry: wraps RMI registry life cycle. It's used by the JMX remoting infrastructure to register
+
+* JMX RMI connector: wraps a standard JMX remoting RMI connector
+
+* Remote Logger: notifies log informations
+
+A JMX Console is an OSGi framework also (for simplicity) which should host two bundles :
+* JMX Console: the graphical framework that will host graphical 	plugins
+* jmxconsole common tabs: tabs that are common to all gateways. 	For the moment it only concerns a tab that shows remote notification 	(it works whith remote logger)
+
+# OSGi/JMX MBean registration
+
+MOSGi installs JMX-MX4J agent at the gateways level. Any one can register an MBean to the JMX agent. The registration can be made in two ways. The direct code and the white board pattern.
+* In the direct code, one can register an MBean to the agent through the standard service interface : *javax.management.MBeanServer*
+
+Example:
+
+    org.osgi.framework.ServiceReference sr = context.getServiceReference(javax.management.MBeanServer.class.getName());
+    javax.management.MBeanServer mbs=(javax.management.MBeanServer)context.getService(sr);
+    mbs.registerMBean(new MBeanImpl(), new ObjectName("Foo:FooName");
+
+Exemple of such code is uses in *mosgi.managedelements.bundlesprobes* code in felix repository
+* In the whiteboard pattern, one can register an MBean through registering its interface to the framework as a service. If the interface name ends with MBean or if the interface is *javax.management.DynamicMBean*, the agent will automatically register the implementation as a standard MBean. The objectName of the MBean can either be defined at registration time with the *org.apache.felix.mosgi.jmx.agent.Constants.OBJECTNAME* property name or automatically build through introspection.
+
+Example:
+
+    java.util.Properties prop=new java.util.Properties();
+    prop.add( org.apache.felix.mosgi.jmx.agent.Constants.OBJECTNAME, "Foo:FooName");
+    context.registerService(test.FooMBean.class.getName(), new test.Foo(), prop);
+
+
+# Management Console
+
+The management console is a ad-hoc jmx compatible console. Its aim is not to be a concurrent to general purpose consoles like MX4J or JConsole but provides an ad-hoc user interface depending on the managed gateway. The console is based on a plugin framework. Each time the consol connects to a gateway it gets the list of available MBean. Then for each registered MBean it asks for specific local bundles for managing it. Each graphical bundle is integrated as a graphical tab in the management console.
+
+
+
+In the next screenshot, the gateway user has deployed 4 probes on the remote gateway : Remote Obr, Remote Bundle List, GNU/Linux and OSGi Plateform.!jmxconsoleGUI.png!
+
+In order to get these tabs, the gateway manager deploys the 4 probe bundles on the remote gateway and GUI tabs are automatically made available to the remote console. These bundles are :
+* ObrProbe : a probe that enables interaction with obr for 	bundle deployment
+* BundleProbe : a probe that enables the bundle life-cycle 	management
+* GNU-Linux : a probe that gets status from running host 	operating system
+* OSGi Platform : a probe that gets information from current 	running gateway
+
+These plugin are developed as simple examples and are available in felix repository. A [ProbeGuide]({{ refs.probeguide.path }}) that  describes plugin integration is available. Plugin are dynamically removed and reinstalled each time you change your selected gateway.
+
+
+
+### MBean Definition
+
+An MBean is a Management Component for the JMX framework. It is made of an MBean interface and an implementation of it. The MBean interface is used to make remote management with the implementation.&nbsp;
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/mosgi-managed-osgi-framework/probeguide.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/mosgi-managed-osgi-framework/probeguide.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/mosgi-managed-osgi-framework/probeguide.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/mosgi-managed-osgi-framework/probeguide.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,149 @@
+Title: ProbeGuide
+
+# Developping probes for MOSGi framework
+
+{quote}
+
+{quote}
+MOSGi is a management infrastructure for OSGi gateways remote management. The architecture relies on JMX management infrastructure and is classically build on a three layered system:
+
+!ManagementLayers.png!
+* The probe layer: are low layer 	elements that drive the gateway. They can either get information 	from the gateway (gateway status) or set information on it (install 	a bundle),
+* The Agent layer: there is one 	agent per gateway and is responsible for maintaining access to a 	list of available probes,
+* The Manager layer is the remote 	environment that can communicate with the agent to get information 	from the gateway through the probes
+
+There are various way to implements this architecture (CIM/Wbem, Snmp, JMX). We have choose to use the JMX proposal because it is standardized in the java virtual machine since jdk1.5.
+
+# JMX management infrastructure synthesis
+
+Sun JMX proposal defines the following elements :
+
+!JMXLayers.png!
+* The agent is the registry for 	probes called MBeans and is accessed through connectors.
+* MBeans are java objects that 	register themselves to the agent under some name
+* Connectors are end points were 	external managers can communicate with. There are currently two 	available connectors : an xml/http connector and a rmi based 	connector. We are using the rmi connector (JSR160).
+
+In the JMX world probes are represented as MBeans. They are java singleton object that declare a single interface to the agent. This interface is registered under a unique name within the agent namespace. The JMX namespace is structured as a domainname:mbeanname unique name. The following html page represents an example of this kind of namespace (we use the httpconnector connector with the agent to get this information).
+
+!jmxmx4jhtml.png!
+
+These are various mbeans deployed on a specific gateway. We can identify 4 columns : the mbean registered name (and domain), its implementation, a comment and a function to unregister it.
+
+Mbeans are component that declare a management interface that should have a syntactic name similar to the class they instrument. For instance the class foo.Test should implement a management interface whose name is foo.TestMBean. The registration mechanism associates a implementation (conform to the management interface) with an objectName (a unique identifier). The corresponding call is something like :aMbeanServer.register(aMBeanImplementation, anObjectName);. There are many kinds of MBeans (standard, dynamic, model and simple) but their description is out of the scope of this document.
+
+# MOSGi probe developpement
+
+Our management infrastructure proposes a framework for deploying standard mbean within OSGi gateways. It also embeds a reference to a graphical part (manager view) directly in the Mbean itself. Thus the management console is automatically populated with client part of the management system.
+
+## Gateway probes
+
+These probes are developed in conformance to the following elements.
+* A probe must be registered under the domain TabUI. It means 	that they will have a corresponding tab in our management console.
+* A probe must implement a management interface conform to the 	JMX specification (ie : foo.LinuxProbe \--> foo.LinuxProbeMBean)
+* The management interface must extend TabIfc (which declares a 	single method : getBundleName()). This methods returns an url were 	the management console should find a tab that can establish a 	management dialog with the probe.
+* The probe is made available as a standard OSGi Mbean that 	will make its registration during the bundleActivator start method.
+
+The following picture illustrates relations between these elements.
+
+!MOSGiProbeClasses.png!
+
+For instance a Probe that declares a single management function *int getValue()*;should provide the following interface:
+
+    package foo;
+    import insa.jmxconsole.gui.service.TabIfc;
+    public interface ProbeMBean extends TabIfc {
+      public int getValue();
+    }
+
+And the following class:
+
+    package foo;
+    import org.osgi.framework.BundleActivator;
+    import org.osgi.framework.BundleContext;
+    import org.osgi.framework.ServiceReference;
+    import insa.jmxconsole.gui.service.TabIfc;
+    import javax.management.MBeanServer;
+    public class Probe implements BundleActivator,ProbeMBean{
+      //////////////////////////////////////////
+      //   BundleActivator Interface          //
+      //////////////////////////////////////////
+      /* The probe lifecycle is linked to the bundle lifecycle */
+      public void start(BundleContext bc){
+        /* Here we register the Mbean within the agent */
+        ServiceReference sr = context.getServiceReference(MBeanServer.class.getName());
+        if (sr!=null){
+          MBeanServer server = (MbeanServer)this.bc.getService(sr);
+          server.registerMBean(this,  new ObjectName("TabUI:name=Probe");
+        }
+      }
+      public void stop(BundleContext bc){...}
+      ///////////////////////////
+      // Management interface  //
+      ///////////////////////////
+      public int getValue(){return 10;}
+    
+      /* A getIfc function comes from RemoteIfc interface that enable the manager (remote console) to
+      a bundle that can communicate whith this probe from a remote URL */
+      public String getBundleName(){
+       return "http://somewhere/agraphicaltab.jar"
+      }
+    }
+
+Once the probe is made as a bundle it can be deployed on the remote gateway. Then a manager (management console) can ask communicate with the gateway agent to manage the probe.
+
+## MOSGi JmxConsole architecture
+
+When a probe is deployed on a remote gateway it is manageable by standard management consoles like JConsole, MC4J... We have developed our own management console that is able to manage probe in a more dedicated approach.
+
+The management console is based on a plugin mechanism. Each plugin is represented as a tab and each tab manages a probe. The console is launched with two bundles. Remotegui.jar is the execution framework and remotecomponent.jar contains a sole remote logger service that gets remote notification from gateways. The screen represented the gateway status after it has been launched.!EmptyConsole.png!
+The left panel identifies connected gateways,
+The upper center panel is an container for tabs from managed gateways,
+
+The lower center panel contains the remote logger display that shows notifications from remote gateways.
+When the user selects a gateway (green flag) the console will do the following actions :
+1. Ask all MBeans in the TabUI domain.
+1. For each of these MBean, get the URL of bundle that provides 	the tab. This is done through the call to getBundleName( ) method in 	RemoteIfc interface.
+1. Install the bundle on the gateway
+
+For instance if the user selects the green point he gets the following tabs.
+
+!TabbedConsole.png!
+
+4 probes have been deployed on the remote gateway and 4 graphical tabs have been installed.
+
+## Graphical tab integration
+
+When developing a probe one shall provide a corresponding MOSGi tab. It should follow these guidelines.
+* It should be a bundle in order to be remotely installed on 	the console
+* It should implement Plugin interface with is the jmxconsole 	container interface specification.
+
+The plugin is mainly conform to the java beans specification development. The jmxconsole acts as a bean container and each tab is a bean in this infrastructure. This is the general architecture of a Tab class.!MOSGiConsoleTabClasses.png!
+
+The plugin interface has the following structure:
+
+    package insa.jmxconsole.gui.service;
+    import java.awt.Component;
+    import java.beans.PropertyChangeListener;
+    public interface Plugin extends PropertyChangeListener{
+      public String getName(); /* The name of the tab */
+      public Component getGUI(); /* This is called by the container to get the graphical component */
+      public void registerServicePlugin(); /* This is called by the framework when a new gateway is selected */
+      public void unregisterServicePlugin();
+      /* see before */
+      public String pluginLocation(); /* This a unique identifier of the plugin */
+        /* These are constants that enable communication between container and plugins. They are treated in the
+      propertyChange function brought by the javabean API */
+      public static final String NEW_NODE_SELECTED="newNodeSelected";
+      public static final String NEW_NODE_READY="newNodeReady";
+      public static final String NEW_NODE_CONNECTION="newNodeConnection";
+      public static final String EMPTY_NODE="emptyNode";
+      public static final String PLUGIN_ADDED="pluggin_added";
+      public static final String PLUGIN_REMOVED="pluggin_removed";
+    }
+
+Implementation tabs are provided as open-source code. You can find various implementation of this interface in felix repository in the *mosgi.managedelements.xxx.tab* elements.
+
+
+## Function call sequence
+
+The next figure presents a function call sequence when using MOSGi framework.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/tutorials-examples-and-presentations.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/tutorials-examples-and-presentations.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/tutorials-examples-and-presentations.mdtext (added)
+++ felix/site/trunk/content/documentation/tutorials-examples-and-presentations.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,5 @@
+Title: Tutorials, Examples, and Presentations
+
+# Tutorials, Examples, and Presentations
+
+{children}
\ No newline at end of file

Added: felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-application-demonstration.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-application-demonstration.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-application-demonstration.mdtext (added)
+++ felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-application-demonstration.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,151 @@
+Title: Apache Felix Application Demonstration
+
+# Apache Felix Application Demonstration
+
+*(This document is a work in progress.)*
+
+Apache Felix provides a foundation for creating modular and dynamically extensible applications. This page presents an example application to demonstrate the various approaches to consider when creating a OSGi/Felix-based application. It is recommended that you have a look at the more [basic examples]({{ refs.felix-getting-started.path }}) such as [FELIX:Apache Felix Framework Usage Documentation] before you start with this one.
+
+In order to follow this example you need three things:
+
+1. A [Subversion](http://subversion.apache.org/) client to check out the source code,
+1. The IDE of your choice to view the source code, and
+1. [Maven](http://maven.apache.org) to build the source code.
+
+The source code of the examples is available in the Felix SVN repository at [http://svn.apache.org/repos/asf/felix/trunk/examples](http://svn.apache.org/repos/asf/felix/trunk/examples). If you feel more familiar with git, you can use the git mirror at: [git://git.apache.org/felix.git] or browse the source code at github: [https://github.com/apache/felix]
+
+## Potential Approaches
+
+When creating an OSGi-based application there are two main orthogonal issues to consider:
+
+1. Service model vs. extender model
+1. Bundled application vs. hosted framework
+
+The first issue is actually a general issue when creating OSGi-based applications. There are two general approaches that can be used when creating an extensible OSGi application. The service model approach uses the OSGi service concept and the service registry as the extensibility mechanism. The extender model approach uses the OSGi installed bundle set as the extensibility mechanism. Both approaches have their advantages and disadvantages and they can be used independently or together.
+
+The second issue is related to whether your application is run completely on top of the OSGi framework as a set of bundles or whether your application hosts an embedded OSGi framework instance. Creating applications completely as a set of bundles is the preferred approach since it allows the application to run on any OSGi framework, but this it not always possible. In such cases where it is not possible or desired, then you may host a framework instance inside your application, which will likely tie your application to that framework implementation (although less so with the framework launching API introduced in the OSGi R4.2 specification).
+
+The remainder of this document will present variations of an example application that demonstrates these different approaches.
+
+## Example Application Overview
+
+The example application is a very simple paint program that effectively functions identically whether using services/extensions or running embedded/hosted. The application, called the host, defines a `SimpleShape` service/extension that it uses to draw shapes. Different implementations of the `SimpleShape` can be created to allow the application to draw different shapes. Each shape service/extension has name and icon properties that the application uses for manipulating the services/extensions. Available shapes are displayed in the application's tool bar. To draw a shape, click on its button in the tool bar and then click in the drawing canvas. Shapes can be dragged, but not resized. When new shape services/extensions appear they are automatically added to the tool bar and they are automatically removed when the shape services/extensions disappear. Closing the application window causes the framework and the JVM to shut down. The following is a screen shot of the application.
+
+!example-application.png|align=center!
+
+## Getting the source code
+
+Currently, the example application is only available in our source control repositories. We have created two applications, one for the service-based and one for the extender-based approach. Both examples can be run as a bundled application on top of any OSGi implementation or by hosting an embedded framework. Assuming you are using svn to get the source code, you can find the source at the following locations:
+
+
+    http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.host
+    http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.circle
+    http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.square
+    http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.triangle
+    
+    http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.host
+    http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.circle
+    http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.square
+    http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.triangle
+
+
+Check out each project using an appropriate SVN command, such as:
+
+
+    svn co http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.host
+
+
+## Building and running the examples
+
+Once you have checked out the projects you can go into each sub-directory and build it using Maven; this assumes you have Maven properly installed. To build, simply perform the following in each project directory:
+
+
+    mvn clean install
+
+
+After you have built the projects, start the Felix framework and install/start the resulting bundle in the `target/` directory of each sub-project for either the service-based or extender-based example.
+
+To start the examples using an embedded framework, copy the JAR files you just build to a folder in your file system. Then execute the host.jar, passing it the names of all services/extensions as parameters; for example:
+
+
+    java -jar servicebased.host-1.0.0.jar file:/servicebased.circle-1.0.0.jar file:/servicebased.square-1.0.0.jar file:/servicebased.triangle-1.0.0.jar
+
+
+If you are using an IDE like Eclipse, you can run an embedded framework using a custom run configuration. In Eclipse click *Run* -> *Run Configurations...* and create a new *Java Application* run configuration. Select the host project you want to start (servicebased.host or extenderbased.host) and chose the `Application` class as *Main class* from the org.apache.felix.example.servicebased/extenderbased.host.launch package. Switch to the *Arguments* tab and fill in the following *Program arguments* (assuming you want to run the extender-based example):
+
+
+    file:../extenderbased.circle/target/extenderbased.circle-1.0.0.jar file:../extenderbased.square/target/extenderbased.square-1.0.0.jar file:../extenderbased.triangle/target/extenderbased.triangle-1.0.0.jar
+
+
+For more details on running an application with an embedded framework scroll down to the bottom of the page.
+
+## Service-Based Application
+
+The service-based application uses the OSGi service concept and the service registry as the extensibility mechanism. Therefore the host bundle contains a service interface located at `org.apache.felix.example.servicebased.host.service.SimpleShape`. The SimpleShape service has two properties: a name and an icon. Besides that it defines one operation: `draw(Graphics2D g2, Point p)`.
+
+### Defining shapes as services
+
+Bundles that want to contribute a shape service have to implement the `SimpleShape` interface. Take a look at the circle bundle for example. The circle bundle only contains one class, the `Activator`. A `[BundleActivator](http://www.osgi.org/javadoc/r4v43/org/osgi/framework/BundleActivator.html)` is responsible for starting up a bundle. Therefore it gets passed in a `[BundleContext|http://www.osgi.org/javadoc/r4v43/org/osgi/framework/BundleContext.html]`, that can be used to perform registration of services within the framework. The `Activator` also contains an inner class that implements the `SimpleShape` interface and therefore represents the `SimpleShape` implementation of a circle. The `start(BundleContext context` method is used to register the circle implementation as a service:
+
+
+    Dictionary<String, Object> dict = new Hashtable<String, Object>();
+    dict.put(SimpleShape.NAME_PROPERTY, "Circle");
+    dict.put(SimpleShape.ICON_PROPERTY, new ImageIcon(this.getClass().getResource("circle.png")));
+    m_context.registerService(SimpleShape.class.getName(), new Circle(), dict);
+
+
+First a `[Dictionary](http://docs.oracle.com/javase/6/docs/api/java/util/Dictionary.html)` is created to hold the service's properties. The two service properties are added to the dictionary. The icon of the circle service is located under src/main/resources/org/apache/example/servicebased/circle/circle.png. It gets loaded as an `[ImageIcon|http://docs.oracle.com/javase/6/docs/api/javax/swing/ImageIcon.html]` and added as icon property. The service then gets registered in the service registry by passing the name of the service interface, a service object and the service's properties.
+
+### Detecting shape services
+
+The host's `Activator` creates a `DrawingFrame` for displaying the different shapes. It then delegates adding and removing of `SimpleShape` services to a `[ServiceTracker](http://www.osgi.org/javadoc/r4v43/org/osgi/util/tracker/ServiceTracker.html)` implementation. The `ShapeTracker` gets notified, when a new `SimpleShape` service is added to, modified or removed from the service registry.
+
+## Extender-Based Application
+
+In contrast to the service-based example, the extender-based example uses bundles as it's primary extensibility mechanism. The host bundle contains a `SimpleShape` interface that is much like the one from the service based example. It also contains a `draw(Graphics2D g2, Point p)` method and defines a set of properties. This time the properties are not used as properties for registering a service, but for defining bundle header properties in the bundle's `MANIFEST.MF` file.
+
+### Defining shapes as extensions
+
+Bundles that want to contribute a `SimpleShape` extension have to implement the `SimpleShape` interface. Have a look at the extender-based circle implementation, for example. It only contains one class, `Circle`, that implements `SimpleShape`. Note, that in contrast to the service-based example there is no need to define a `[BundleActivator](http://www.osgi.org/javadoc/r4v43/org/osgi/framework/BundleActivator.html)`. This is because, there is no need to register a service within the framework. Information about the provided shape implementation is located in the bundle headers instead. Have a look at the circle's `MANIFEST.MF` file:
+
+
+    Manifest-Version: 1.0
+    Private-Package: org.apache.felix.example.extenderbased.circle
+    Tool: Bnd-0.0.238
+    Bundle-Name: Apache Felix Circle Extension
+    Created-By: Apache Maven Bundle Plugin
+    Bundle-Vendor: The Apache Software Foundation
+    Build-Jdk: 1.7.0_01
+    Bundle-Version: 1.0.0
+    Extension-Class: org.apache.felix.example.extenderbased.circle.Circle
+    Bnd-LastModified: 1331062969798
+    Extension-Icon: org/apache/felix/example/extenderbased/circle/circle.p
+     ng
+    Bundle-ManifestVersion: 2
+    Bundle-Description: A simple extension for drawing circles.
+    Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
+    Bundle-DocURL: http://www.apache.org/
+    Bundle-SymbolicName: org.apache.felix.example.extenderbased.circle
+    Import-Package: org.apache.felix.example.extenderbased.host.extension
+    Extension-Name: Circle
+
+
+As you can see, the three bundle properties, defined in the `SimpleShape` interface are set as bundle headers.
+
+Note: The manifest file is generated by the Maven build, so you will only find it in the compiled jar. If you are interested in automatically creating manifest files for your bundles, have a look at the configuration of the [org.apache.felix.maven-bundle-plugin](http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html) in the pom.xml.
+
+### Detecting shape bundles
+
+Like the `[ServiceTracker](http://www.osgi.org/javadoc/r4v43/org/osgi/util/tracker/ServiceTracker.html)` for tracking services, there is a `[BundleTracker|http://www.osgi.org/javadoc/r4v42/org/osgi/util/tracker/BundleTracker.html]` for tracking bundles. A `BundleTracker` get's notified, when the state of tracked bundles change. Have a look at `org.apache.felix.example.extenderbased.host.ShapeBundleTracker`. The constructor defines that only active bundles should be tracked. The `addingBundle(Bundle bundle, BundleEvent event)` method gets called by the framework, when a bundle enters the activated state. The tracker then checks if the bundle's headers contain the extension name property and, if so, adds the icon to the application.
+
+## Embedding the Framework
+
+The OSGi R4.2 specification defines APIs to allow an application to host it's own embedded framework instance. Therefore an implementation of the `[FrameworkFactory](http://www.osgi.org/javadoc/r4v42/org/osgi/framework/launch/FrameworkFactory.html)` interface has to be used. OSGi implementers specify their `FrameworkFactory` implementation in the `META-INF/services/org.osgi.framework.launch.FrameworkFactory` file. Prior to Java 6, one had to parse the class name in that file by oneself. Luckily Java 6 has the `[ServiceLoader<S>|http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html]` class, that lets you easily instantiate a `FrameworkFactoy`. Have a look at the contents of the `org.apache.felix.example.extenderbased.host.launch` package in the extender-based host bundle (the implementation is the same for the service-based example).
+
+The `Application` class is responsible for creating the framework and installing and starting the bundles. It uses a `ConfigUtil` for creating the framework configuration that is needed to create a framework using the `FrameworkFactory`. The `ConfigUtil` also creates a temporary cache directory for the framework. If the creation of the framework is successful, `installAndStartBundles(String... bundleLocations)` will be called to start the actual application. Therefore the `Activator` of the host bundle is instantiated. Note, that the host bundle can not register itself within the framework it just created. Only the extension bundles will be registered within the framework.
+
+As you can see no Felix-specific code is involved in any of the examples. That's one of the advantages of OSGi specification. Bundles that run on Felix will run on every other implementation of the same OSGi release.
+
+## Feedback
+
+Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [users@felix.apache.org|mailto:users@felix.apache.org].
\ No newline at end of file

Added: felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-faq.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-faq.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-faq.mdtext (added)
+++ felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-faq.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,61 @@
+Title: Apache Felix OSGi FAQ
+
+# Apache Felix OSGi Frequently Asked Questions
+
+[TOC]
+
+
+## If I use bundles from Felix, will my application be tied to the Felix framework?
+
+No. The Felix community is very serious about creating technology that is "pure" OSGi. This means that we will always strive to make sure our subprojects work on all OSGi framework implementations. The Felix framework provides very few "containerisms", so there are generally no "special" Felix features available on which subprojects may depend. Even though it is common to use the name "Felix" to refer to the Felix framework, in reality the framework is just one subproject in the Apache Felix project. All subprojects are intended to be used either together or separately.
+
+Note that not all subprojects are tested on all available OSGi framework implementations, but it is the goal for them to run on them. Any difficulties in doing so should be filed as bugs in [JIRA](http://issues.apache.org/jira/browse/FELIX). Additionally, due to specification ambiguity, it is possible the Felix framework may exhibit different behavior than other implementations, but this is normal; if in doubt, file a bug. In the future, it is also possible some subprojects may require Felix, but they will explicitly state this fact.
+
+
+## When I update my bundle, why are my bundle's old classes still being used?
+
+Updating a bundle does not necessarily cause the new classes to be used immediately, it depends on two factors:
+
+1. If the classes are from a private package or an exported package.
+1. If the classes are from an exported package, whether or not they are being used by another bundle.
+
+Regarding (1), if the classes come from a private package (i.e., it is **not** exported), then the new classes will become available immediately. However, if they are from an exported package, then their visibility depends on whether any other bundles are using the exported packages.
+
+If no other bundles are using the exported packages, then the new classes will become available immediately since the old version of the classes are no longer needed. On the other hand, if any other bundles are using the exported packages, then the new classes will **not** become available immediately since the old version is still required by any dependent bundles. In this case, the new classes will not be made available until `PackageAdmin.refreshPackages()` is called (this can be invoked in the Felix shell using the `refresh` command). 
+
+There is one partial exception to this latter case, it occurs when the exporting bundle does **not** also import its own exported packages (see "[Should a bundle import its own exported packages?]({{ refs.-import-and-export.path }})" below for more information on this topic). In this case, the new classes become immediately accessible to the updated exporting bundle, but not to the dependent bundles; the dependent bundles continue to see the old version of the classes. This situation generally requires `PackageAdmin.refreshPackages()` to be invoked to bring the bundles back to a useful state.
+
+This is the normal update process as defined by the OSGi specification. Updating a bundle is a two-step process, where older versions of exported packages are kept around until explicitly refreshed. This is done to reduce disruption when performing several updates.
+
+## Should a service provider/consumer bundle be packaged with its service API packages?
+
+There is no easy answer to this question and it largely depends on the specific usage scenario. The OSGi specification had originally suggested that it was good practice to embed service API packages in the service provider bundle. In this case in OSGi R4, the service provider should both [export and import]({{ refs.-import-and-export.path }}) the service API packages, which was the default for previous versions of the OSGi specification.
+
+The OSGi specification never had an explicit stance on whether or not a consumer bundle should embed its dependent service API packages; although, it would not appear to be a best practice. Logically, there is some sense to this approach, since it potentially allows the consumer bundle to gracefully handle broken service dependencies. Of course, this depends on whether there is anything the bundle can do in the face of broken dependencies. If service API packages are embedded in the consumer bundle, then it should [export and import]({{ refs.-import-and-export.path }}) the packages. An alternative approach in this case is to dynamically import the service API (or even use optional imports if the dependency should only be considered once).
+
+The main advantages of embedding service API packages in bundles are that the dependencies can always be resolved and it does not require installing a lot of other bundles to resolve the dependencies. There are disadvantages, however. One disadvantage is resource consumption caused by potential code duplication. Probably a more serious disadvantage is that it makes it harder to dynamically swap out providers.
+
+For example, assume a provider bundle is used to export service API packages and all consumers are wired to that bundle. If the provider bundle is updated or uninstalled and then refreshed, then all consumer bundles will be stopped and refreshed as well. Even without a refresh, such a configuration would potentially inhibit garbage collection of the class loader of the service provider, since consumers would be using it for the API package.
+
+This situation would be different if the service API were package in a separate bundle. In this situation, all consumer bundles would be wired to the API bundle, not to the provider bundle. Thus, if the provider were updated or uninstalled and then refreshed, the consumer bundles would only be minimally impacted (i.e., they would either switch to the new version of the provider or to a different provider).
+
+
+## Should a bundle import its own exported packages?
+
+In OSGi R3 this was always the case, since Export-Package implied Import-Package. It was a good idea then and is generally a good idea now.
+
+The whole point is substitutability of providers.
+
+If you import the packages you export, then the framework is free to choose a different provider of those packages for your bundle at resolve time, which means that your exports may go unused. However, this is a good thing, because the framework tries to minimize the number of active versions of a given package. The reason why this is a good thing is because it allows for higher levels of bundle interoperability. The more versions of a given package that are in use at any given time can lead to conflicts when trying to resolve bundle package dependencies and this also leads to partitioning of the service registry, since bundles can only see a single version of a given service package.
+
+If your bundle only exports its packages, then it is forcing the framework to wire itself to its own version, which will result in more active versions of the given package and thus less interoperability.
+
+The main time you want to export only, is if your bundle is purely a library bundle, then its packages will only be used if they are needed. Another case might be if you have tightly coupled bundles sharing implementation packages. However, if your bundle will be started and especially if the exported packages define service interfaces or are referenced from service interfaces, then you will generally want to export and import them.
+
+## Why is my bundle not able to see annotations at run time?
+
+This is typically a class loading issue. At runtime the JVM will only return annotations that are visible to the current class loader, so if your bundle doesn't import the appropriate package(s) then you won't see them.
+
+This is not a bug, as such, it is simply how OSGi class loading works - your bundle cannot see classes that its hasn't imported (or acquired via `Require-Bundle`). It is also part of the design of annotations, since annotated classes are supposed to continue to load and resolve even if their annotation types aren't available on the class path. This lets you annotate a class with EJB3 annotations, for example, but also use it in a non-EJB container where you won't then see the EJB3 annotations.
+
+Try importing the annotation package inside your bundle to resolve the visibility issue.

Added: felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial.mdtext (added)
+++ felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,20 @@
+Title: Apache Felix OSGi Tutorial
+
+# Apache Felix OSGi Tutorial
+
+This tutorial creates successively more complex OSGi bundles to illustrate most of the features and functionality offered by the OSGi framework.
+
+Trails:
+
+* [Apache Felix Tutorial Example 1]({{ refs.apache-felix-tutorial-example-1.path }}): A bundle that listens for OSGi service events.
+* [Apache Felix Tutorial Example 2]({{ refs.apache-felix-tutorial-example-2.path }}): A bundle that implements a dictionary service.
+* [Apache Felix Tutorial Example 2b]({{ refs.apache-felix-tutorial-example-2b.path }}): A bundle that implements another dictionary service.
+* [Apache Felix Tutorial Example 3]({{ refs.apache-felix-tutorial-example-3.path }}): A bundle that implements a simple dictionary service client.
+* [Apache Felix Tutorial Example 4]({{ refs.apache-felix-tutorial-example-4.path }}): A bundle that implements a more robust dictionary service client.
+* [Apache Felix Tutorial Example 5]({{ refs.apache-felix-tutorial-example-5.path }}): A bundle that implements a dictionary service client using the Service Tracker.
+* [Apache Felix Tutorial Example 6]({{ refs.apache-felix-tutorial-example-6.path }}): A bundle that implements a spell checker service using dictionary services.
+* [Apache Felix Tutorial Example 7]({{ refs.apache-felix-tutorial-example-7.path }}): A bundle that implements a spell checker service client.
+* [Apache Felix Tutorial Example 8]({{ refs.apache-felix-tutorial-example-8.path }}): A bundle that implements a spell checker service using Service Binder.
+* [Apache Felix Tutorial Example 9]({{ refs.apache-felix-tutorial-example-9.path }}): A bundle that implements a spell checker service using Dependency Manager. Coming soon...
+* [Apache Felix Tutorial Example 10]({{ refs.apache-felix-tutorial-example-10.path }}): A bundle that implements a spell checker service using Declarative Services. Coming soon...
+* [Apache Felix Tutorial Example 11]({{ refs.apache-felix-tutorial-example-11.path }}): A bundle that implements a spell checker service using iPOJO. Coming soon...

Added: felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-1.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-1.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-1.mdtext (added)
+++ felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-1.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,117 @@
+Title: Apache Felix Tutorial Example 1
+
+# Apache Felix Tutorial Example 1 - Service Event Listener Bundle
+
+This example creates a simple bundle that listens for OSGi service events. This example does not do much at first, because it only prints out the details of registering and unregistering services. In the next example we will create a bundle that implements a service, which will cause this bundle to actually do something. For now, we will just use this example to help us understand the basics of creating a bundle.
+
+A bundle gains access to the OSGi framework using a unique instance of `BundleContext`. In order for a bundle to get its unique bundle context, it must implement the `BundleActivator` interface; this interface has two methods, `start()` and `stop()`, that both receive the bundle's context and are called when the bundle is started and stopped, respectively. In the following source code, our bundle implements the `BundleActivator` interface and uses the context to add itself as a listener for service events (the file for our bundle is called `Activator.java`):
+
+
+    /*
+     * Apache Felix OSGi tutorial.
+    **/
+    
+    package tutorial.example1;
+    
+    import org.osgi.framework.BundleActivator;
+    import org.osgi.framework.BundleContext;
+    import org.osgi.framework.ServiceListener;
+    import org.osgi.framework.ServiceEvent;
+    
+    /**
+     * This class implements a simple bundle that utilizes the OSGi
+     * framework's event mechanism to listen for service events. Upon
+     * receiving a service event, it prints out the event's details.
+    **/
+    public class Activator implements BundleActivator, ServiceListener
+    {
+        /**
+         * Implements BundleActivator.start(). Prints
+         * a message and adds itself to the bundle context as a service
+         * listener.
+         * @param context the framework context for the bundle.
+        **/
+        public void start(BundleContext context)
+        {
+            System.out.println("Starting to listen for service events.");
+            context.addServiceListener(this);
+        }
+    
+        /**
+         * Implements BundleActivator.stop(). Prints
+         * a message and removes itself from the bundle context as a
+         * service listener.
+         * @param context the framework context for the bundle.
+        **/
+        public void stop(BundleContext context)
+        {
+            context.removeServiceListener(this);
+            System.out.println("Stopped listening for service events.");
+    
+            // Note: It is not required that we remove the listener here,
+            // since the framework will do it automatically anyway.
+        }
+    
+        /**
+         * Implements ServiceListener.serviceChanged().
+         * Prints the details of any service event from the framework.
+         * @param event the fired service event.
+        **/
+        public void serviceChanged(ServiceEvent event)
+        {
+            String[] objectClass = (String[])
+                event.getServiceReference().getProperty("objectClass");
+    
+            if (event.getType() == ServiceEvent.REGISTERED)
+            {
+                System.out.println(
+                    "Ex1: Service of type " + objectClass[0] + " registered.");
+            }
+            else if (event.getType() == ServiceEvent.UNREGISTERING)
+            {
+                System.out.println(
+                    "Ex1: Service of type " + objectClass[0] + " unregistered.");
+            }
+            else if (event.getType() == ServiceEvent.MODIFIED)
+            {
+                System.out.println(
+                    "Ex1: Service of type " + objectClass[0] + " modified.");
+            }
+        }
+    }
+
+
+After implementing the Java source code for the bundle, we must also define a manifest file that contains meta-data needed by the OSGi framework for manipulating the bundle. The manifest is packaged into a JAR file along with the Java class file associated with our bundle; the whole JAR package is actually referred to as a bundle. We create a file called `manifest.mf` that contains the following:
+
+
+    Bundle-Name: Service listener example
+    Bundle-Description: A bundle that displays messages at startup and when service events occur
+    Bundle-Vendor: Apache Felix
+    Bundle-Version: 1.0.0
+    Bundle-Activator: tutorial.example1.Activator
+    Import-Package: org.osgi.framework
+
+
+Most of the above meta-data is for human consumption and does not affect the OSGi framework. Only the `Bundle-Activator` and `Import-Package` meta-data is used by the framework. The `Bundle-Activator` attribute tells the framework which class implements the `BundleActivator` interface. With this information, when the OSGi framework starts the bundle, an instance of the specified class is created and its `start()` method is invoked. The created instance will also have its `stop()` method called when the framework stops the bundle. The `Import-Package` attribute informs the framework of the bundle's dependencies on external packages; all bundles with an activator must import `org.osgi.framework` since it contains the core OSGi class definitions. Any packages dependencies will be verified and resolved by the OSGi framework. (Note: Make sure your manifest file ends in a trailing carriage return or else the last line will be ignored.)
+
+Now we need to compile the source code. To compile we must have the `felix.jar` file (found in Felix' `bin` directory) in our class path. We compile the source file using a command like:
+
+
+    javac -d c:\classes *.java
+
+
+This command compiles all source files and outputs the generated classes into a subdirectory of the `c:\classes` directory; this subdirectory is `tutorial\example1`, named after the package we specified in the source file. For the above command to work, the `c:\classes` directory must exist. After compiling, we need to create a JAR file containing the generated package directories. We will also add our manifest file that contains the bundle's meta-data to the JAR file. To create the JAR file, we issue the command:
+
+
+    jar cfm example1.jar manifest.mf -C c:\classes tutorial\example1
+
+
+This command creates a JAR file using the manifest file we created and includes all of the classes in the `tutorial\example1` directory inside of the `c:\classes` directory. Once the JAR file is created, we are ready to install and start the bundle.
+
+To run Felix, we follow the instructions described in usage.html. When we start Felix, it asks for a profile name, we will put all of our bundles in a profile named `tutorial`. Now we will install and start our bundle. Assuming that we created our bundle in the directory `c:\tutorial`, we can install and start it in Felix' shell using the following command:
+
+
+    start file:/c:/tutorial/example1.jar
+
+
+The above command installs and starts the bundle in a single step; it is also possible to install and start the bundle in two steps by using the Felix `install` and `start` shell commands. To stop the bundle, use the Felix `stop` shell command. Keep in mind, that this bundle will not do much at this point since it only listens for service events and we are not registering any services. In the next example we will register a service that will generate an event for this bundle to receive. To exit Felix, we use the `shutdown` command.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-2.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-2.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-2.mdtext (added)
+++ felix/site/trunk/content/documentation/tutorials-examples-and-presentations/apache-felix-osgi-tutorial/apache-felix-tutorial-example-2.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,153 @@
+Title: Apache Felix Tutorial Example 2
+
+## Example 2 - Dictionary Service Bundle
+
+This example creates a bundle that implements an OSGi service. Implementing an OSGi service is a two-step process, first we must define the interface of the service and then we must define an implementation of the service interface. In this particular example, we will create a dictionary service that we can use to check if a word exists, which indicates if the word is spelled correctly or not. First, we will start by defining a simple dictionary service interface in a file called `DictionaryService.java`:
+
+
+    /*
+     * Apache Felix OSGi tutorial.
+    **/
+    
+    package tutorial.example2.service;
+    
+    /**
+     * A simple service interface that defines a dictionary service.
+     * A dictionary service simply verifies the existence of a word.
+    **/
+    public interface DictionaryService
+    {
+        /**
+         * Check for the existence of a word.
+         * @param word the word to be checked.
+         * @return true if the word is in the dictionary,
+         *         false otherwise.
+        **/
+        public boolean checkWord(String word);
+    }
+
+
+The service interface is quite simple, with only one method that needs to be implemented. Notice that we put the service interface in the package `tutorial.example2.service`, instead of just putting it in `tutorial.example2`. We did this because we need to share the interface definition with other bundles, therefore it is better to separate service interfaces that need to be shared from code that does not need to be shared. Such an approach ensures a strong separation between interface and implementation.
+
+In the following source code, the bundle uses its bundle context to register the dictionary service. We implement the dictionary service as an inner class of the bundle activator class, but we could have also put it in a separate file. The source code for our bundle is as follows in a file called `Activator.java`:
+
+
+    /*
+     * Apache Felix OSGi tutorial.
+    **/
+    
+    package tutorial.example2;
+    
+    import java.util.Hashtable;
+    
+    import org.osgi.framework.BundleActivator;
+    import org.osgi.framework.BundleContext;
+    import org.osgi.framework.ServiceListener;
+    import org.osgi.framework.ServiceEvent;
+    
+    import tutorial.example2.service.DictionaryService;
+    
+    /**
+     * This class implements a simple bundle that uses the bundle
+     * context to register an English language dictionary service
+     * with the OSGi framework. The dictionary service interface is
+     * defined in a separate class file and is implemented by an
+     * inner class.
+    **/
+    public class Activator implements BundleActivator
+    {
+        /**
+         * Implements BundleActivator.start(). Registers an
+         * instance of a dictionary service using the bundle context;
+         * attaches properties to the service that can be queried
+         * when performing a service look-up.
+         * @param context the framework context for the bundle.
+        **/
+        public void start(BundleContext context)
+        {
+            Hashtable<String, String> props = new Hashtable<String, String>();
+            props.put("Language", "English");
+            context.registerService(
+                DictionaryService.class.getName(), new DictionaryImpl(), props);
+        }
+    
+        /**
+         * Implements BundleActivator.stop(). Does nothing since
+         * the framework will automatically unregister any registered services.
+         * @param context the framework context for the bundle.
+        **/
+        public void stop(BundleContext context)
+        {
+            // NOTE: The service is automatically unregistered.
+        }
+    
+        /**
+         * A private inner class that implements a dictionary service;
+         * see DictionaryService for details of the service.
+        **/
+        private static class DictionaryImpl implements DictionaryService
+        {
+            // The set of words contained in the dictionary.
+            String[] m_dictionary =
+                { "welcome", "to", "the", "osgi", "tutorial" };
+    
+            /**
+             * Implements DictionaryService.checkWord(). Determines
+             * if the passed in word is contained in the dictionary.
+             * @param word the word to be checked.
+             * @return true if the word is in the dictionary,
+             *         false otherwise.
+            **/
+            public boolean checkWord(String word)
+            {
+                word = word.toLowerCase();
+    
+                // This is very inefficient
+                for (int i = 0; i < m_dictionary.length; i++)
+                {
+                    if (m_dictionary[i].equals(word))
+                    {
+                        return true;
+                    }
+                }
+                return false;
+            }
+        }
+    }
+
+
+Note that we do not need to unregister the service in the `stop()` method, because the OSGi framework will automatically do so for us. The dictionary service that we have implemented is very simple; its dictionary is a static array of only five words, so this solution is not optimal and is only intended for educational purposes. We must create a `manifest.mf` file that contains the meta-data for our bundle; the manifest file contains the following:
+
+
+    Bundle-Name: English dictionary
+    Bundle-Description: A bundle that registers an English dictionary service
+    Bundle-Vendor: Apache Felix
+    Bundle-Version: 1.0.0
+    Bundle-Activator: tutorial.example2.Activator
+    Export-Package: tutorial.example2.service
+    Import-Package: org.osgi.framework
+
+
+We specify which class is used to activate our bundle via the `Bundle-Activator` attribute and also specify that our bundle exports a shared package using the `Export-Package` attribute. The `Export-Package` attribute makes it possible for other bundles to import our dictionary service interface. The `Import-Package` attribute informs the framework of the bundle's dependencies on external packages; all bundles with an activator must import `org.osgi.framework` since it contains the core OSGi class definitions. Any packages dependencies will be verified and resolved by the OSGi framework. (Note: Make sure your manifest file ends in a trailing carriage return or else the last line will be ignored.)
+
+To compile our source code, we need the `felix.jar` file (found in Felix' `bin` directory) in our class path. We compile the source file using a command like:
+
+
+    javac -d c:\classes *.java
+
+
+This command compiles all source files and outputs the generated classes into a subdirectory of the `c:\classes` directory; this subdirectory is `tutorial\example2`, named after the package we specified in the source file. For the above command to work, the `c:\classes` directory must exist. After compiling, we need to create a JAR file containing the generated package directories. We will also add our manifest file that contains the bundle's meta-data to the JAR file. To create the JAR file, we issue the command:
+
+
+    jar cfm example2.jar manifest.mf -C c:\classes tutorial\example2
+
+
+This command creates a JAR file using the manifest file we created and includes all of the classes in the `tutorial\example2` directory inside of the c:\classes directory. Once the JAR file is created, we are ready to install and start the bundle.
+
+To run Felix, we follow the instructions described in usage.html. When we start Felix, it asks for a profile name, we will put all of our bundles in a profile named `tutorial`. After running Felix, we should make sure that the bundle from Example 1 is active. We can use the Felix `lb` shell command to get a list of all bundles, their state, and their bundle identifier number. If the Example 1 bundle is not active, we should start the bundle using the `start` command and the bundle's identifier number that is displayed by the `lb` command. Now we can install and start our dictionary service bundle. Assuming that we created our bundle in the directory c:\tutorial, we can install and start it in Felix' shell using the following command:
+
+
+    start file:/c:/tutorial/example2.jar
+
+
+The above command installs and starts the bundle in a single step; it is also possible to install and start the bundle in two steps by using the Felix `install` and `start` shell commands. To stop the bundle, use the Felix `stop` shell command. If the bundle from Example 1 is still active, then we should see it print out the details of the service event it receives when our new bundle registers its dictionary service. Using the Felix shell `lb` command to get the bundle identifier number for our dictionary service bundle and we can stop and restart it at will using the `stop` and `start` commands, respectively. Each time we start and stop our dictionary service bundle, we should see the details of the associated service event printed from the bundle from Example 1. In Example 3, we will create a client for our dictionary service. To exit Felix, we use the `shutdown` command.
\ No newline at end of file



Mime
View raw message