[jboss-cvs] JBossAS SVN: r89724 - in projects/jboss-osgi/trunk: docbook/en/modules and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Jun 3 08:09:49 EDT 2009
Author: thomas.diesler at jboss.com
Date: 2009-06-03 08:09:49 -0400 (Wed, 03 Jun 2009)
New Revision: 89724
Added:
projects/jboss-osgi/trunk/docbook/en/modules/ch010-introduction.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch020-getting-started.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch030-runtime.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch040-framework-integration.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch050-developer-guide.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch060-husky-testing.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch070-provided-bundles.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch080-provided-examples.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch090-references.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch100-getting-support.xml
Removed:
projects/jboss-osgi/trunk/docbook/en/modules/ch00-introduction.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch10-getting-started.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch30-framework-integration.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch40-developer-guide.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch50-husky-testing.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch60-provided-bundles.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch70-provided-examples.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch80-references.xml
projects/jboss-osgi/trunk/docbook/en/modules/ch90-getting-support.xml
Modified:
projects/jboss-osgi/trunk/docbook/en/master.xml
projects/jboss-osgi/trunk/testsuite/example/src/test/java/org/jboss/test/osgi/example/simple/SimpleHuskyTestCase.java
projects/jboss-osgi/trunk/testsuite/example/src/test/java/org/jboss/test/osgi/example/simple/SimpleTestCase.java
Log:
Fix installed vs. resolved assertion
Modified: projects/jboss-osgi/trunk/docbook/en/master.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/master.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/master.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -10,15 +10,15 @@
<toc/>
- <xi:include href="modules/ch00-introduction.xml"/>
- <xi:include href="modules/ch10-getting-started.xml"/>
- <xi:include href="modules/ch20-runtime.xml"/>
- <xi:include href="modules/ch30-framework-integration.xml"/>
- <xi:include href="modules/ch40-developer-guide.xml"/>
- <xi:include href="modules/ch50-husky-testing.xml"/>
- <xi:include href="modules/ch60-provided-bundles.xml"/>
- <xi:include href="modules/ch70-provided-examples.xml"/>
- <xi:include href="modules/ch80-references.xml"/>
- <xi:include href="modules/ch90-getting-support.xml"/>
+ <xi:include href="modules/ch010-introduction.xml"/>
+ <xi:include href="modules/ch020-getting-started.xml"/>
+ <xi:include href="modules/ch030-runtime.xml"/>
+ <xi:include href="modules/ch040-framework-integration.xml"/>
+ <xi:include href="modules/ch050-developer-guide.xml"/>
+ <xi:include href="modules/ch060-husky-testing.xml"/>
+ <xi:include href="modules/ch070-provided-bundles.xml"/>
+ <xi:include href="modules/ch080-provided-examples.xml"/>
+ <xi:include href="modules/ch090-references.xml"/>
+ <xi:include href="modules/ch100-getting-support.xml"/>
</book>
\ No newline at end of file
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch00-introduction.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch00-introduction.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch00-introduction.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,299 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapIntroduction">
-
- <title>Introduction</title>
-
- <sect1 xml:id="SecWhatIsOsgi">
- <title>What is OSGi</title>
-
- <para>The <ulink url="http://www2.osgi.org/Release4/HomePage">Open Services Gateway Initiative (OSGi)</ulink>,
- specifications define a standardized, component-oriented, computing environment for networked services that is the foundation
- of an enhanced service-oriented architecture.</para>
-
- <para>The OSGi specification defines two things:</para>
-
- <itemizedlist>
- <listitem>A set of services that an OSGi container must implement</listitem>
- <listitem>A contract between the container and your application</listitem>
- </itemizedlist>
-
- <para>Developing on the OSGi platform means first building your application using OSGi APIs, then deploying it in an OSGi container.</para>
-
- <para>The <ulink url="http://www.jboss.org/community/docs/DOC-13273">JBoss OSGi Project</ulink> project has two distinct goals</para>
-
- <orderedlist>
- <listitem>Provide an integration platform for 3rd party OSGi Frameworks</listitem>
- <listitem>Provide an OSGi compliant framework implementation based on the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink></listitem>
- </orderedlist>
-
-
- <emphasis role="bold">What does OSGi offer to Java developers?</emphasis>
-
- <para>OSGi modules provide classloader semantics to partially expose code that can then be consumed by other modules.
- The implementation details of a module, although scoped public by the Java programming language, remain private to the module.
- On top of that you can install multiple versions of the same code and resolve dependencies by version and other criteria.
- OSGi also offers advanced security and lifecycle, which I'll explain in more detail further down.</para>
-
- <emphasis role="bold">What kind of applications benefit from OSGi?</emphasis>
-
- <para>Any application that is designed in a modular fashion where it is necessary to start, stop, update individual modules with minimal impact
- on other modules. Modules can define their own transitive dependencies without the need to resolve these dependencies at the container level.
- The OSGi platform builds an exellent foundation for the next generation JBoss ESB for example.</para>
-
- <emphasis role="bold">Should Java EE developers adopt the OSGi programming model?</emphasis>
-
- <para>Probably not. The OSGi runtime may be used internally by Java EE container providers to achieve the desired isolation and configuration
- flexibility that the container wishes to provide. At the application programming level, the Java EE model will continue to exist in its own right,
- whereas the OSGi model may provide the more suitable runtime environment for applications that require the modular isolation, security and lifecycle
- management that OSGi offers.</para>
-
- </sect1>
-
- <sect1 xml:id="SecFramworkOverview">
- <title>OSGi Framework Overview</title>
-
- <para>The functionality of the Framework is divided in the following layers:</para>
-
- <itemizedlist>
- <listitem>Security Layer</listitem>
- <listitem>Module Layer</listitem>
- <listitem>Life Cycle Layer</listitem>
- <listitem>Service Layer</listitem>
- <listitem>Actual Services</listitem>
- </itemizedlist>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/osgi-layers.png"/>
- </imageobject>
- </mediaobject>
-
-
- <emphasis role="bold">OSGi Security Layer</emphasis>
-
- <para>The OSGi Security Layer is an optional layer that underlies the OSGi Service Platform.
- The layer is based on the Java 2 security architecture. It provides the infrastructure to deploy and manage
- applications that must run in fine grained controlled environments.</para>
-
- <para>The OSGi Service Platform can authenticate code in the following ways:</para>
-
- <itemizedlist>
- <listitem>By location</listitem>
- <listitem>By signer</listitem>
- </itemizedlist>
-
- <para>For example, an Operator can grant the ACME company the right to use networking on their devices.
- The ACME company can then use networking in every bundle they digitally sign and deploy on the Operator’s device.
- Also, a specific bundle can be granted permission to only manage the life cycle of bundles that are signed by the ACME company.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/osgi-delegation.png"/>
- </imageobject>
- </mediaobject>
-
- <emphasis role="bold">OSGi Module Layer</emphasis>
-
- <para>The OSGi Module Layer provides a generic and standardized solution for Java modularization.
- The Framework defines a unit of modularization, called a bundle. A bundle is comprised of Java classes and other resources,
- which together can provide functions to end users. Bundles can share Java packages among an exporter bundle and an importer bundle
- in a well-defined way.</para>
-
- <para>Once a <emphasis role="bold">Bundle</emphasis> is started, its functionality is provided and services are exposed to other bundles installed in the OSGi Service Platform.
- A bundle can carry descriptive information about itself in the manifest file that is contained in its JAR file.
- Here are a few important <emphasis role="bold">Manifest Headers</emphasis> defined by the OSGi Framework:</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">Bundle-Activator</emphasis> - class used to start, stop the bundle</listitem>
- <listitem><emphasis role="bold">Bundle-SymbolicName</emphasis> - identifies the bundle</listitem>
- <listitem><emphasis role="bold">Bundle-Version</emphasis> - specifies the version of the bundle</listitem>
- <listitem><emphasis role="bold">Export-Package</emphasis> - declaration of exported packages</listitem>
- <listitem><emphasis role="bold">Import-Package</emphasis> - declaration of imported packages</listitem>
- </itemizedlist>
-
- <para>The notion of OSGi Version Range describes a range of versions using a mathematical interval notation. For example</para>
-
- <programlisting>
- Import-Package: com.acme.foo;version="[1.23, 2)", com.acme.bar;version="[4.0, 5.0)"
- </programlisting>
-
- <para>With the OSGi Class Loading Architecture many bundles can share a single virtual machine (VM).
- Within this VM, bundles can hide packages and classes from other bundles, as well as share packages with other bundles.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/osgi-classloader.png"/>
- </imageobject>
- </mediaobject>
-
- <para>For example, the following import and export definition resolve correctly because the version range in the import definition
- matches the version in the export definition:</para>
-
- <programlisting>
- A: Import-Package: p; version="[1,2)"
- B: Export-Package: p; version=1.5.1
- </programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/osgi-version-constraint.png"/>
- </imageobject>
- </mediaobject>
-
- <para>Apart from bundle versions, OSGi Attribute Matching is a generic mechanism to allow the importer and exporter to influence the
- matching process in a declarative way. For example, the following statements will match.</para>
-
- <programlisting>
- A: Import-Package: com.acme.foo;company=ACME
- B: Export-Package: com.acme.foo;company=ACME; security=false
- </programlisting>
-
- <para>An exporter can limit the visibility of the classes in a package with the include and exclude directives on the export definition.</para>
-
- <programlisting>
- Export-Package: com.acme.foo; include:="Qux*,BarImpl"; exclude:=QuxImpl
- </programlisting>
-
- <emphasis role="bold">OSGi Life Cycle Layer</emphasis>
-
- <para>The Life Cycle Layer provides an API to control the security and life cycle operations of bundles.</para>
-
- <para>A bundle can be in one of the following states:</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/osgi-life-cycle.png"/>
- </imageobject>
- </mediaobject>
-
- <para>A bundle is activated by calling its <emphasis role="bold">Bundle Activator</emphasis> object, if one exists.
- The BundleActivator interface defines methods that the Framework invokes when it starts and stops the bundle.</para>
-
- <para>A Bundle Context object represents the execution context of a single bundle within the OSGi Service Platform,
- and acts as a proxy to the underlying Framework. A <emphasis role="bold">Bundle Context</emphasis> object is created by the Framework when a bundle is started.
- The bundle can use this private BundleContext object for the following purposes:</para>
-
- <itemizedlist>
- <listitem>Installing new bundles into the OSGi environment</listitem>
- <listitem>Interrogating other bundles installed in the OSGi environment</listitem>
- <listitem>Obtaining a persistent storage area</listitem>
- <listitem>Retrieving service objects of registered services</listitem>
- <listitem>Registering services in the Framework service</listitem>
- <listitem>Subscribing or unsubscribing to Famework events</listitem>
- </itemizedlist>
-
- <emphasis role="bold">OSGi Service Layer</emphasis>
-
- <para>The OSGi Service Layer defines a dynamic collaborative model that is highly integrated with the Life Cycle Layer.
- The service model is a publish, find and bind model. A service is a normal Java object that is registered under one or more
- Java interfaces with the service registry.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/osgi-service-registration.png"/>
- </imageobject>
- </mediaobject>
- </sect1>
-
- <sect1 xml:id="SecServiceCompendium">
- <title>OSGi Service Compendium</title>
-
- <para>The OSGi Service Compendium specifies a number of services that may be available in an OSGi runtime environment.
- Although the OSGi Framework specification is useful in itself already, it only defines the OSGi core infrastructure.
- The services defined in the compendium specification define the scope and functionality of some common services that
- bundle developers might want to use. Here is a quick summary:</para>
-
- <emphasis role="bold">Log Service</emphasis>
- <para>The Log Service provides a general purpose message logger for the OSGi Service Platform. It consists of two services,
- one for logging information and another for retrieving current or previously recorded log information.</para>
-
- <emphasis role="bold">Http Service</emphasis>
- <para>The Http Service supports two standard techniques for registering servlets and resources to develop communication and
- user interface solutions for standard technologies such as HTTP, HTML, XML, etc.</para>
-
- <emphasis role="bold">Device Access Specification</emphasis>
- <para>The Device Access specification supports the coordination of automatic detection and attachment of existing devices on
- an OSGi Service Platform, facilitates hot-plugging and -unplugging of new devices, and downloads and installs device drivers on demand.</para>
-
- <emphasis role="bold">Configuration Admin Service</emphasis>
- <para>The Configuration Admin service allows an Operator to set the configuration information of deployed bundles.</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/osgi-config-service.png" contentwidth="450"/>
- </imageobject>
- </mediaobject>
-
- <emphasis role="bold">Metatype Service</emphasis>
- <para>The Metatype Service specification defines interfaces that allow bundle developers to describe attribute
- types in a computer readable form using so-called metadata.</para>
-
- <emphasis role="bold">Preferences Service</emphasis>
- <para>The Preferences Service allows storage of data that is specific to a particular user.</para>
-
- <emphasis role="bold">User Admin Service</emphasis>
- <para>Bundles can use the User Admin Service to authenticate an initiator and represent this authentication as an Authorization object.
- Bundles that execute actions on behalf of this user can use the Authorization object to verify if that user is authorized.</para>
-
- <emphasis role="bold">Wire Admin Service</emphasis>
- <para>The Wire Admin Service is an administrative service that is used to control a wiring topology in the OSGi Service Platform.
- It is intended to be used by user interfaces or management programs that control the wiring of services in an OSGi Service Platform.</para>
-
- <emphasis role="bold">IO Connector Service</emphasis>
- <para>The IO Connector Service specification adopts the Java 2 Micro Edition (J2ME) javax.microedition.io packages as a basic communications
- infrastructure.</para>
-
- <emphasis role="bold">UPnP Device Service</emphasis>
- <para>The UPnP Device Service specifies how OSGi bundles can be developed that interoperate with UPnP (Universal Plug and Play)
- devices and UPnP control points.</para>
-
- <emphasis role="bold">Declarative Services Specification</emphasis>
- <para>The Declarative Services specification addresses some of the complications that arise when the OSGi service model is
- used for larger systems and wider deployments, such as: Startup Time, Memory Footprint, Complexity. The service component
- model uses a declarative model for publishing, finding and binding to OSGi services.</para>
-
- <emphasis role="bold">Event Admin Service</emphasis>
- <para>The Event Admin Service provides an inter-bundle communication mechanism. It is based on a event publish and subscribe model, popular in many message based systems.</para>
-
- <emphasis role="bold">Deployment Admin Service</emphasis>
- <para>The Deployment Admin Service specification, standardizes the access to some of the responsibilities of the management agent:
- that is, the lifecycle management of interlinked resources on an OSGi Service Platform.</para>
-
- <emphasis role="bold">Auto Configuration Specification</emphasis>
- <para>The Auto Configuration Specification is to allow the configuration of bundles.
- These bundles can be embedded in Deployment Packages or bundles that are already present on the OSGi Service Platform.</para>
-
- <emphasis role="bold">Application Admin Service</emphasis>
- <para>The Application Admin Service is intended to simplify the management of an environment with many different types of applications
- that are simultaneously available.</para>
-
- <emphasis role="bold">DMT Admin Service</emphasis>
- <para>The DMT Admin Service specification defines an API for managing a device using concepts from the OMA DM specifications.</para>
-
- <emphasis role="bold">Monitor Admin Service</emphasis>
- <para>The Monitor Admin Service specification outlines how a bundle can publish Status Variables and how administrative bundles
- can discover Status Variables as well as read and reset their values.</para>
-
- <emphasis role="bold">Foreign Application Access Specification</emphasis>
- <para>The Foreign Application Access specification is to enable foreign application models like MIDP, Xlets, Applets, other Java
- application models to participate in the OSGi service oriented architecture.</para>
-
- <emphasis role="bold">Service Tracker Specification</emphasis>
- <para>The Service Tracker specification defines a utility class, ServiceTracker, that makes tracking the registration, modification,
- and unregistration of services much easier.</para>
-
- <emphasis role="bold">XML Parser Service Specification</emphasis>
- <para>The XML Parser Service specification addresses how the classes defined in JAXP can be used in an OSGi Service Platform.</para>
-
- <emphasis role="bold">Position Specification</emphasis>
- <para>The Position Specification provides bundle developers with a consistent way of handling geographic positions in OSGi applications.</para>
-
- <emphasis role="bold">Measurement and State Specification</emphasis>
- <para>The Measurement and State Specification provides a consistent way of handling a diverse range of measurements for bundle developers.</para>
-
- <emphasis role="bold">Execution Environment Specification</emphasis>
- <para>This Execution Environment Specification defines different execution environments for OSGi Server Platform Servers.</para>
- </sect1>
-
-</chapter>
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch010-introduction.xml (from rev 89712, projects/jboss-osgi/trunk/docbook/en/modules/ch00-introduction.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch010-introduction.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch010-introduction.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,299 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapIntroduction">
+
+ <title>Introduction</title>
+
+ <sect1 xml:id="SecWhatIsOsgi">
+ <title>What is OSGi</title>
+
+ <para>The <ulink url="http://www2.osgi.org/Release4/HomePage">Open Services Gateway Initiative (OSGi)</ulink>,
+ specifications define a standardized, component-oriented, computing environment for networked services that is the foundation
+ of an enhanced service-oriented architecture.</para>
+
+ <para>The OSGi specification defines two things:</para>
+
+ <itemizedlist>
+ <listitem>A set of services that an OSGi container must implement</listitem>
+ <listitem>A contract between the container and your application</listitem>
+ </itemizedlist>
+
+ <para>Developing on the OSGi platform means first building your application using OSGi APIs, then deploying it in an OSGi container.</para>
+
+ <para>The <ulink url="http://www.jboss.org/community/docs/DOC-13273">JBoss OSGi Project</ulink> project has two distinct goals</para>
+
+ <orderedlist>
+ <listitem>Provide an integration platform for 3rd party OSGi Frameworks</listitem>
+ <listitem>Provide an OSGi compliant framework implementation based on the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink></listitem>
+ </orderedlist>
+
+
+ <emphasis role="bold">What does OSGi offer to Java developers?</emphasis>
+
+ <para>OSGi modules provide classloader semantics to partially expose code that can then be consumed by other modules.
+ The implementation details of a module, although scoped public by the Java programming language, remain private to the module.
+ On top of that you can install multiple versions of the same code and resolve dependencies by version and other criteria.
+ OSGi also offers advanced security and lifecycle, which I'll explain in more detail further down.</para>
+
+ <emphasis role="bold">What kind of applications benefit from OSGi?</emphasis>
+
+ <para>Any application that is designed in a modular fashion where it is necessary to start, stop, update individual modules with minimal impact
+ on other modules. Modules can define their own transitive dependencies without the need to resolve these dependencies at the container level.
+ The OSGi platform builds an exellent foundation for the next generation JBoss ESB for example.</para>
+
+ <emphasis role="bold">Should Java EE developers adopt the OSGi programming model?</emphasis>
+
+ <para>Probably not. The OSGi runtime may be used internally by Java EE container providers to achieve the desired isolation and configuration
+ flexibility that the container wishes to provide. At the application programming level, the Java EE model will continue to exist in its own right,
+ whereas the OSGi model may provide the more suitable runtime environment for applications that require the modular isolation, security and lifecycle
+ management that OSGi offers.</para>
+
+ </sect1>
+
+ <sect1 xml:id="SecFramworkOverview">
+ <title>OSGi Framework Overview</title>
+
+ <para>The functionality of the Framework is divided in the following layers:</para>
+
+ <itemizedlist>
+ <listitem>Security Layer</listitem>
+ <listitem>Module Layer</listitem>
+ <listitem>Life Cycle Layer</listitem>
+ <listitem>Service Layer</listitem>
+ <listitem>Actual Services</listitem>
+ </itemizedlist>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/osgi-layers.png"/>
+ </imageobject>
+ </mediaobject>
+
+
+ <emphasis role="bold">OSGi Security Layer</emphasis>
+
+ <para>The OSGi Security Layer is an optional layer that underlies the OSGi Service Platform.
+ The layer is based on the Java 2 security architecture. It provides the infrastructure to deploy and manage
+ applications that must run in fine grained controlled environments.</para>
+
+ <para>The OSGi Service Platform can authenticate code in the following ways:</para>
+
+ <itemizedlist>
+ <listitem>By location</listitem>
+ <listitem>By signer</listitem>
+ </itemizedlist>
+
+ <para>For example, an Operator can grant the ACME company the right to use networking on their devices.
+ The ACME company can then use networking in every bundle they digitally sign and deploy on the Operator’s device.
+ Also, a specific bundle can be granted permission to only manage the life cycle of bundles that are signed by the ACME company.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/osgi-delegation.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <emphasis role="bold">OSGi Module Layer</emphasis>
+
+ <para>The OSGi Module Layer provides a generic and standardized solution for Java modularization.
+ The Framework defines a unit of modularization, called a bundle. A bundle is comprised of Java classes and other resources,
+ which together can provide functions to end users. Bundles can share Java packages among an exporter bundle and an importer bundle
+ in a well-defined way.</para>
+
+ <para>Once a <emphasis role="bold">Bundle</emphasis> is started, its functionality is provided and services are exposed to other bundles installed in the OSGi Service Platform.
+ A bundle can carry descriptive information about itself in the manifest file that is contained in its JAR file.
+ Here are a few important <emphasis role="bold">Manifest Headers</emphasis> defined by the OSGi Framework:</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">Bundle-Activator</emphasis> - class used to start, stop the bundle</listitem>
+ <listitem><emphasis role="bold">Bundle-SymbolicName</emphasis> - identifies the bundle</listitem>
+ <listitem><emphasis role="bold">Bundle-Version</emphasis> - specifies the version of the bundle</listitem>
+ <listitem><emphasis role="bold">Export-Package</emphasis> - declaration of exported packages</listitem>
+ <listitem><emphasis role="bold">Import-Package</emphasis> - declaration of imported packages</listitem>
+ </itemizedlist>
+
+ <para>The notion of OSGi Version Range describes a range of versions using a mathematical interval notation. For example</para>
+
+ <programlisting>
+ Import-Package: com.acme.foo;version="[1.23, 2)", com.acme.bar;version="[4.0, 5.0)"
+ </programlisting>
+
+ <para>With the OSGi Class Loading Architecture many bundles can share a single virtual machine (VM).
+ Within this VM, bundles can hide packages and classes from other bundles, as well as share packages with other bundles.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/osgi-classloader.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>For example, the following import and export definition resolve correctly because the version range in the import definition
+ matches the version in the export definition:</para>
+
+ <programlisting>
+ A: Import-Package: p; version="[1,2)"
+ B: Export-Package: p; version=1.5.1
+ </programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/osgi-version-constraint.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>Apart from bundle versions, OSGi Attribute Matching is a generic mechanism to allow the importer and exporter to influence the
+ matching process in a declarative way. For example, the following statements will match.</para>
+
+ <programlisting>
+ A: Import-Package: com.acme.foo;company=ACME
+ B: Export-Package: com.acme.foo;company=ACME; security=false
+ </programlisting>
+
+ <para>An exporter can limit the visibility of the classes in a package with the include and exclude directives on the export definition.</para>
+
+ <programlisting>
+ Export-Package: com.acme.foo; include:="Qux*,BarImpl"; exclude:=QuxImpl
+ </programlisting>
+
+ <emphasis role="bold">OSGi Life Cycle Layer</emphasis>
+
+ <para>The Life Cycle Layer provides an API to control the security and life cycle operations of bundles.</para>
+
+ <para>A bundle can be in one of the following states:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/osgi-life-cycle.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>A bundle is activated by calling its <emphasis role="bold">Bundle Activator</emphasis> object, if one exists.
+ The BundleActivator interface defines methods that the Framework invokes when it starts and stops the bundle.</para>
+
+ <para>A Bundle Context object represents the execution context of a single bundle within the OSGi Service Platform,
+ and acts as a proxy to the underlying Framework. A <emphasis role="bold">Bundle Context</emphasis> object is created by the Framework when a bundle is started.
+ The bundle can use this private BundleContext object for the following purposes:</para>
+
+ <itemizedlist>
+ <listitem>Installing new bundles into the OSGi environment</listitem>
+ <listitem>Interrogating other bundles installed in the OSGi environment</listitem>
+ <listitem>Obtaining a persistent storage area</listitem>
+ <listitem>Retrieving service objects of registered services</listitem>
+ <listitem>Registering services in the Framework service</listitem>
+ <listitem>Subscribing or unsubscribing to Famework events</listitem>
+ </itemizedlist>
+
+ <emphasis role="bold">OSGi Service Layer</emphasis>
+
+ <para>The OSGi Service Layer defines a dynamic collaborative model that is highly integrated with the Life Cycle Layer.
+ The service model is a publish, find and bind model. A service is a normal Java object that is registered under one or more
+ Java interfaces with the service registry.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/osgi-service-registration.png"/>
+ </imageobject>
+ </mediaobject>
+ </sect1>
+
+ <sect1 xml:id="SecServiceCompendium">
+ <title>OSGi Service Compendium</title>
+
+ <para>The OSGi Service Compendium specifies a number of services that may be available in an OSGi runtime environment.
+ Although the OSGi Framework specification is useful in itself already, it only defines the OSGi core infrastructure.
+ The services defined in the compendium specification define the scope and functionality of some common services that
+ bundle developers might want to use. Here is a quick summary:</para>
+
+ <emphasis role="bold">Log Service</emphasis>
+ <para>The Log Service provides a general purpose message logger for the OSGi Service Platform. It consists of two services,
+ one for logging information and another for retrieving current or previously recorded log information.</para>
+
+ <emphasis role="bold">Http Service</emphasis>
+ <para>The Http Service supports two standard techniques for registering servlets and resources to develop communication and
+ user interface solutions for standard technologies such as HTTP, HTML, XML, etc.</para>
+
+ <emphasis role="bold">Device Access Specification</emphasis>
+ <para>The Device Access specification supports the coordination of automatic detection and attachment of existing devices on
+ an OSGi Service Platform, facilitates hot-plugging and -unplugging of new devices, and downloads and installs device drivers on demand.</para>
+
+ <emphasis role="bold">Configuration Admin Service</emphasis>
+ <para>The Configuration Admin service allows an Operator to set the configuration information of deployed bundles.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/osgi-config-service.png" contentwidth="450"/>
+ </imageobject>
+ </mediaobject>
+
+ <emphasis role="bold">Metatype Service</emphasis>
+ <para>The Metatype Service specification defines interfaces that allow bundle developers to describe attribute
+ types in a computer readable form using so-called metadata.</para>
+
+ <emphasis role="bold">Preferences Service</emphasis>
+ <para>The Preferences Service allows storage of data that is specific to a particular user.</para>
+
+ <emphasis role="bold">User Admin Service</emphasis>
+ <para>Bundles can use the User Admin Service to authenticate an initiator and represent this authentication as an Authorization object.
+ Bundles that execute actions on behalf of this user can use the Authorization object to verify if that user is authorized.</para>
+
+ <emphasis role="bold">Wire Admin Service</emphasis>
+ <para>The Wire Admin Service is an administrative service that is used to control a wiring topology in the OSGi Service Platform.
+ It is intended to be used by user interfaces or management programs that control the wiring of services in an OSGi Service Platform.</para>
+
+ <emphasis role="bold">IO Connector Service</emphasis>
+ <para>The IO Connector Service specification adopts the Java 2 Micro Edition (J2ME) javax.microedition.io packages as a basic communications
+ infrastructure.</para>
+
+ <emphasis role="bold">UPnP Device Service</emphasis>
+ <para>The UPnP Device Service specifies how OSGi bundles can be developed that interoperate with UPnP (Universal Plug and Play)
+ devices and UPnP control points.</para>
+
+ <emphasis role="bold">Declarative Services Specification</emphasis>
+ <para>The Declarative Services specification addresses some of the complications that arise when the OSGi service model is
+ used for larger systems and wider deployments, such as: Startup Time, Memory Footprint, Complexity. The service component
+ model uses a declarative model for publishing, finding and binding to OSGi services.</para>
+
+ <emphasis role="bold">Event Admin Service</emphasis>
+ <para>The Event Admin Service provides an inter-bundle communication mechanism. It is based on a event publish and subscribe model, popular in many message based systems.</para>
+
+ <emphasis role="bold">Deployment Admin Service</emphasis>
+ <para>The Deployment Admin Service specification, standardizes the access to some of the responsibilities of the management agent:
+ that is, the lifecycle management of interlinked resources on an OSGi Service Platform.</para>
+
+ <emphasis role="bold">Auto Configuration Specification</emphasis>
+ <para>The Auto Configuration Specification is to allow the configuration of bundles.
+ These bundles can be embedded in Deployment Packages or bundles that are already present on the OSGi Service Platform.</para>
+
+ <emphasis role="bold">Application Admin Service</emphasis>
+ <para>The Application Admin Service is intended to simplify the management of an environment with many different types of applications
+ that are simultaneously available.</para>
+
+ <emphasis role="bold">DMT Admin Service</emphasis>
+ <para>The DMT Admin Service specification defines an API for managing a device using concepts from the OMA DM specifications.</para>
+
+ <emphasis role="bold">Monitor Admin Service</emphasis>
+ <para>The Monitor Admin Service specification outlines how a bundle can publish Status Variables and how administrative bundles
+ can discover Status Variables as well as read and reset their values.</para>
+
+ <emphasis role="bold">Foreign Application Access Specification</emphasis>
+ <para>The Foreign Application Access specification is to enable foreign application models like MIDP, Xlets, Applets, other Java
+ application models to participate in the OSGi service oriented architecture.</para>
+
+ <emphasis role="bold">Service Tracker Specification</emphasis>
+ <para>The Service Tracker specification defines a utility class, ServiceTracker, that makes tracking the registration, modification,
+ and unregistration of services much easier.</para>
+
+ <emphasis role="bold">XML Parser Service Specification</emphasis>
+ <para>The XML Parser Service specification addresses how the classes defined in JAXP can be used in an OSGi Service Platform.</para>
+
+ <emphasis role="bold">Position Specification</emphasis>
+ <para>The Position Specification provides bundle developers with a consistent way of handling geographic positions in OSGi applications.</para>
+
+ <emphasis role="bold">Measurement and State Specification</emphasis>
+ <para>The Measurement and State Specification provides a consistent way of handling a diverse range of measurements for bundle developers.</para>
+
+ <emphasis role="bold">Execution Environment Specification</emphasis>
+ <para>This Execution Environment Specification defines different execution environments for OSGi Server Platform Servers.</para>
+ </sect1>
+
+</chapter>
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch020-getting-started.xml (from rev 89718, projects/jboss-osgi/trunk/docbook/en/modules/ch10-getting-started.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch020-getting-started.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch020-getting-started.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,397 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapGettingStarted">
+
+ <title>Getting Started</title>
+
+ <para>This chapter takes you through the first steps of getting JBoss OSGi and
+ provides the initial pointers to get up and running.</para>
+
+ <sect1 xml:id="SecDownload">
+ <title>Download the Distribution</title>
+
+ <para>JBoss OSGi is distributed as an <ulink url="http://izpack.org">IzPack</ulink> installer archive.
+ The installer is available from the JBoss OSGi <ulink url="https://sourceforge.net/project/showfiles.php?group_id=22866&package_id=316015">download area</ulink>.</para>
+ </sect1>
+
+ <sect1 xml:id="SecInstall">
+ <title>Running the Installer</title>
+
+ <para>To run the installer execute the following command:</para>
+
+ <programlisting>
+ java -jar jboss-osgi-installer-1.0.0.Beta2.jar
+ </programlisting>
+
+ <para>The installer first shows a welcome screen</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-welcome.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>Then you select the installation path for the JBoss OSGi distribution. This is the directory where you find the binary build artifacts,
+ the java sources, documentation and the JBoss OSGi Runtime.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-installpath.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>The installer contains multiple installation packs. Greyed packs are required, others are optional and can be deselected.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-packs.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">JBoss OSGi Distribution</emphasis> - Documentation, Binary Artifacts and Sources</listitem>
+ <listitem><emphasis role="bold">JBoss OSGi Runtime</emphasis> - Standalone JBoss OSGi Runtime</listitem>
+ <listitem><emphasis role="bold">JBoss OSGi Integration</emphasis> - Integration with an existing JBossAS instance</listitem>
+ </itemizedlist>
+
+ <para>Next, you will be presented with the choice of supported OSGi Frameworks.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-target-framework.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>In case you have selected 'JBoss OSGi Integration', you will be presented with the choice of supported target containers.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-target-container.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>You will then have to point the installer to your existing <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> installation.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-jboss-home.jpg"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>You can then verify the selected installation options and proceed with the actual installation.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-verify.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>The installer reports its installation progress and finally displays a confirmation screen. You can now optionally generate
+ an "automatic installation script" that you can use when you want to repeat what you have just done without user interaction.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-done.png"/>
+ </imageobject>
+ </mediaobject>
+ </sect1>
+
+ <sect1 xml:id="SecRuntimeStart">
+ <title>Starting the Runtime</title>
+
+ <para>If you selected <link linkend="ChapRuntime">JBoss OSGi Runtime</link> during installation you should see a <emphasis role="bold">runtime</emphasis> folder, which contains
+ the JBoss OSGi Runtime distribution. The JBoss OSGi Runtime is an OSGi container onto which services and applications can be deployed.</para>
+
+ <para>The layout of the JBoss OSGi Runtime after installation is similar to what you know from <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink>.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/izpack-structure.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>You can start the Runtime by running <emphasis role="bold">bin/run.sh</emphasis>. The supported command line
+ options are:</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">-c (--server-name)</emphasis> - The runtime profile to start.
+ The default is the 'default' profile.</listitem>
+ <listitem><emphasis role="bold">-b (--bind-address)</emphasis> - The network address various services can bind to.
+ The default is 'localhost'</listitem>
+ </itemizedlist>
+
+ <programlisting>
+ [tdiesler at tddell runtime]$ bin/run.sh
+ =========================================================================
+
+ JBoss OSGi Bootstrap Environment
+
+ OSGI_HOME: /home/tdiesler/jboss-osgi-1.0.0.Beta2/runtime
+
+ JAVA: /usr/java/jdk1.6/bin/java
+
+ JAVA_OPTS: ...
+
+ =========================================================================
+
+ 16:18:32,974 INFO [FelixIntegration] OSGi Integration Felix - 1.0.0.Beta2
+ 16:18:33,403 INFO [FelixIntegration] Installed bundle [1]: org.osgi.compendium
+ 16:18:33,412 INFO [FelixIntegration] Installed bundle [2]: org.apache.felix.log
+ 16:18:33,425 INFO [FelixIntegration] Installed bundle [3]: jboss-osgi-common
+ 16:18:33,435 INFO [FelixIntegration] Installed bundle [4]: jboss-osgi-hotdeploy
+ 16:18:33,550 INFO [jboss-osgi-hotdeploy] Start DeploymentScanner: [scandir=server/default/bundles,interval=2000ms]
+ 16:18:33,555 INFO [OSGiBootstrap] JBoss OSGi Runtime booted in 0.581sec
+ ...
+ 16:18:33,617 INFO [jboss-osgi-common] Installed: jboss-osgi-jndi [5]
+ 16:18:33,627 INFO [jboss-osgi-common] Installed: jboss-osgi-jmx [6]
+ 16:18:33,659 INFO [jboss-osgi-common] Installed: jboss-osgi-common-core [7]
+ ...
+ 16:18:34,170 INFO [jboss-osgi-jndi] JNDI started: JNP=localhost:1099, RMI=localhost:1098
+ 16:18:34,543 INFO [jboss-osgi-jmx] MBeanServerConnection bound to: jmx/invoker/RMIAdaptor
+ ...
+ <emphasis role="bold">16:18:34,544 INFO [OSGiBootstrap] JBoss OSGi Runtime started in 1.57sec</emphasis>
+ </programlisting>
+ </sect1>
+
+ <sect1 xml:id="SecProvidedExamples">
+ <title>Provided Examples</title>
+
+ <para>JBoss OSGi comes with a number of examples that you can build and deploy. Each example
+ deployment is verified by an accompaning test case</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">HTTP Service</emphasis> - Register servlets and resources with the HTTP Service</listitem>
+ <listitem><emphasis role="bold">Log Service</emphasis> - Interact with a local and remote Log Service</listitem>
+ <listitem><emphasis role="bold">JMX Service</emphasis> - Register an MBean through the JMX Service</listitem>
+ <listitem><emphasis role="bold">JNDI Service</emphasis> - Bind objects to the Naming Service</listitem>
+ <listitem><emphasis role="bold">Microcontainer Service</emphasis> - Call a service from an MC bean</listitem>
+ </itemizedlist>
+
+ <programlisting>
+ [tdiesler at tddell example]$ mvn test
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Building JBoss OSGi - Testsuite Examples
+ [INFO] task-segment: [test]
+ [INFO] ------------------------------------------------------------------------
+ ...
+ build-test-jars:
+ # example-http (example-http.jar) 4
+ # example-jmx (example-jmx.jar) 4
+ # example-jndi (example-jndi.jar) 1
+ # example-log (example-log.jar) 2
+ # example-mcservice-bundleA (example-mcservice-bundleA.jar) 2
+ # example-mcservice-bundleB (example-mcservice-bundleB.jar) 3
+ # example-simple (example-simple.jar) 2
+ # example-simple-husky (example-simple-husky.jar) 4
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.jboss.test.osgi.example.microcontainer.MicrocontainerTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 6.006 sec
+ Running org.jboss.test.osgi.example.http.HttpServiceTestCase
+ Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 5.735 sec
+ Running org.jboss.test.osgi.example.log.LogServiceTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.385 sec
+ Running org.jboss.test.osgi.example.jndi.JNDITestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.535 sec
+ Running org.jboss.test.osgi.example.jmx.JMXTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.643 sec
+ Running org.jboss.test.osgi.example.simple.SimpleTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.166 sec
+ Running org.jboss.test.osgi.example.simple.SimpleHuskyTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.384 sec
+ </programlisting>
+ </sect1>
+
+ <sect1 xml:id="SecBundleDeployment">
+ <title>Bundle Deployment</title>
+
+ <para>Bundle deployment works, as you would probably expect, by dropping your OSGi Bundle into the
+ JBoss OSGi Runtime <emphasis role="bold">deploy</emphasis> folder.</para>
+
+ <programlisting>
+ [tdiesler at tdvaio testsuite]$ cp .../test-libs/example/example-http.jar .../runtime/server/web/deploy
+ ...
+ 13:59:38,284 INFO [BundleRealDeployer] Installed: example-http [9]
+ 13:59:38,289 INFO [example-http] BundleEvent INSTALLED
+ 13:59:38,297 INFO [example-http] BundleEvent RESOLVED
+ 13:59:38,304 INFO [example-http] ServiceEvent REGISTERED
+ 13:59:38,306 INFO [BundleStartStopDeployer] Started: example-http [9]
+ 13:59:38,306 INFO [example-http] BundleEvent STARTED
+ </programlisting>
+ </sect1>
+
+ <sect1 xml:id="SecWebConsole">
+
+ <title>Managing installed Bundles</title>
+
+ <para>JBoss OSGi comes with a simple Web Console, which is currently based on the
+ <ulink url="http://felix.apache.org/site/apache-felix-web-console.html">Apache Felix Web Console</ulink> project.
+ By default the JBoss OSGi Web Console is available at <ulink url="http://localhost:8090/jboss-osgi">http://localhost:8090/jboss-osgi</ulink>.
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/webconsole.png" contentwidth="450"/>
+ </imageobject>
+ </mediaobject>
+
+ <note>
+ <title>TODO: Cleanup and document console provided functionality</title>
+ </note>
+ </sect1>
+
+ <sect1 xml:id="SecHudson">
+ <title>Hudson QA Environment</title>
+
+ <emphasis role="bold">Setup the Hudson QA Environment</emphasis>
+
+ <para>The JBoss OSGi <ulink url="http://jbmuc.dyndns.org:8280/hudson">Hudson QA Environment</ulink> is an integral part of the JBoss OSGi code base.
+ It is designed for simplicity because we believe that comprehensive QA will only get done if it is dead simple to do so.</para>
+
+ <para>Consequently, you only have to execute two simple ant targets to setup the QA environment that was used to QA the JBoss OSGi
+ release that you currently work with.</para>
+
+ <para>If in future we should discover a problem with a previous JBoss OSGi release, it will be possible to provide a patch and verify that change using
+ the original QA environment for that release.</para>
+
+ <para>With every release we test the matrix of supported target containers and JDKs.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/hudson-home.png" contentwidth="450"/>
+ </imageobject>
+ </mediaobject>
+
+ <emphasis role="bold">Set Hudson Properties</emphasis>
+
+ <para>You need to set a few properties, especially these</para>
+
+ <itemizedlist>
+ <listitem>hudson.maven.path</listitem>
+ <listitem>hudson.username</listitem>
+ <listitem>hudson.password</listitem>
+ <listitem>hudson.root</listitem>
+ </itemizedlist>
+
+ <programlisting>
+ cd build/hudson
+ cp ant.properties.example ant.properties
+ vi ant.properties
+
+ # The JBoss settings
+ jboss.server.instance=default
+ jboss.bind.address=127.0.0.1
+
+ # JDK settings
+ java.home.jdk15=/usr/java/jdk1.5.0_17
+ java.home.jdk16=/usr/java/jdk1.6.0_11
+
+ # Hudson QA Environment
+ hudson.username=chageme
+ hudson.password=chageme
+
+ hudson.maven.path=/usr/java/apache-maven-2.0.9
+
+ hudson.root=/home/tdiesler/workspace/hudson/jboss-osgi
+
+ hudson.maven.profile=$HUDSONDIR/profiles.xml.local.qa
+
+ hudson.host=jbpm.dyndns.org
+ hudson.admin.port=8250
+ hudson.http.port=8280
+
+ #hudson.jboss501.zip=file:///home/tdiesler/Download/java/jboss/jboss-5.0.1.GA.zip
+
+ hudson.mail.recipients=
+ hudson.smtp.host=localhost
+
+ # Hudson (1.290)
+ apache-tomcat=5.5.20
+ sun-hudson=2402/128862
+ </programlisting>
+
+ <emphasis role="bold">Run Hudson Setup</emphasis>
+
+ <programlisting>
+ [tdiesler at tdvaio hudson]$ ant hudson-setup
+ Buildfile: build.xml
+
+ init:
+ [echo] V1.0.0.Beta2
+
+ init-hudson:
+ [echo]
+ [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
+ [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
+ [echo]
+
+ ...
+
+ hudson-setup:
+ [copy] Copying 2 files to /home/.../hudson/jboss-osgi/apache-tomcat
+ ...
+ [echo]
+ [echo] *************************************
+ [echo] * Hudson setup successfully *
+ [echo] * ant hudson-start *
+ [echo] *************************************
+ [echo]
+ </programlisting>
+
+ <emphasis role="bold">Run Hudson Start</emphasis>
+
+ <programlisting>
+ [tdiesler at tdvaio hudson]$ ant hudson-start
+ Buildfile: build.xml
+
+ init:
+ [echo] V1.0.0.Beta2
+
+ init-hudson:
+ [echo]
+ [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
+ [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
+ [echo]
+
+ hudson-start:
+ [echo]
+ [echo] *************************************
+ [echo] * Hudson started successfully *
+ [echo] * http://localhost:8280/hudson *
+ [echo] *************************************
+ [echo]
+
+ BUILD SUCCESSFUL
+ </programlisting>
+
+ <emphasis role="bold">Run Hudson Stop</emphasis>
+
+ <programlisting>
+ [tdiesler at tdvaio hudson]$ ant hudson-stop
+ Buildfile: build.xml
+
+ init:
+ [echo] V1.0.0.Beta2
+
+ init-hudson:
+ [echo]
+ [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
+ [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
+ [echo]
+
+ hudson-stop:
+ [echo]
+ [echo] *************************************
+ [echo] * Hudson stopped successfully *
+ [echo] * ant hudson-start *
+ [echo] *************************************
+ [echo]
+
+ BUILD SUCCESSFUL
+ </programlisting>
+ </sect1>
+
+</chapter>
\ No newline at end of file
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch030-runtime.xml (from rev 89723, projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch030-runtime.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch030-runtime.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,209 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapRuntime">
+
+ <title>JBoss OSGi Runtime</title>
+
+ <sect1 xml:id="SecRuntimeOverview">
+
+ <title>Overview</title>
+
+ <para>Formerly a trimmed down <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> distribution, the
+ JBoss OSGi Runtime has now evolved into a pure OSGi container onto which components, services and applications can be deployed.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/jbossosgi-runtime.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para><link linkend="SecRuntimeProfiles">Preconfigured profiles</link>, contain OSGi bundles
+ that logically work together. A profile can be bootstrapped either as a standalone server or embedded in some other environment.
+ With a startup time of less than 600ms, the runtime can be easily be bootstrapped from within plain JUnit4 test cases.</para>
+
+ <para>The JBoss OSGi Runtime has an integration layer for the underlying OSGi frameworks. It comes with a choice of
+ <link linkend="SecIntegrationFelix">Apache Felix</link>, <link linkend="SecIntegrationEquinox">Eclipse Equinox</link> or
+ <link linkend="SecIntegrationKnopflerfish">MakeWave Knopflerfish</link>.</para>
+
+ <para>Through local and remote management capabilities the JBoss OSGi Runtime can be provisioned with new or updated bundles.
+ Similar to <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> it supports hot-deployment by dropping bundles
+ into the 'deploy' folder. Management of the runtime is provided through a <link linkend="SecWebConsole">Web Console</link></para>
+
+ <para>Integration of the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> as an OSGi service allows you
+ to write your applications in a POJO programming model without much "polution" of OSGi specific API - the MC will do the
+ wiring for you. Future releases of JBoss OSGi will come with a full implementation of
+ <ulink url="http://jbossosgi.blogspot.com/2009/04/osgi-blueprint-service-rfc-124.html">Blueprint Service (RFC-124)</ulink>,
+ which standardizes this idea and takes it further.</para>
+
+ <para>Great care has been taken about testability of deployed components and services. The <link linkend="ChapHuskyTesting">Husky Test Framework</link>
+ allows you to write plain JUnit tests that do not have a requirement on a specific test runner nor need to extend any specific test base class.
+ Access to the Runtime has been abstracted sufficiently that you can run the same test case against an embedded (bootstrapped from within the test case)
+ as well as a remote instance of the Runtime. You can run your OSGi tests from <ulink url="http://maven.apache.org">Maven</ulink>,
+ <ulink url="http://ant.apache.org">Ant</ulink>, <ulink url="http://www.eclipse.org">Eclipse</ulink> or any other test runner that supports JUnit4.</para>
+
+ <para>JBoss OSGi Runtime can be installed as a <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> service with abstractions
+ of the available OSGi services. The JBoss OSGi testsuite in fact runs the same set of tests against the embedded, standalone and AS integrated
+ instance of the Runtime</para>
+
+ </sect1>
+
+ <sect1 xml:id="SecRuntimeFeatures">
+ <title>Features</title>
+
+ <para>The current JBoss OSGi Runtime feature set includes</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">Embedded and Standalone usage</emphasis> -
+ The runtime can be bootstrapped as standalone container with a startup time of less than 2 sec
+ in its default configuration or embedded in some other container environment.</listitem>
+
+ <listitem><emphasis role="bold">Various Runtime Profiles</emphasis> -
+ It comes with the <link linkend="SecRuntimeProfiles">preconfigured profiles</link> 'Minimal', 'Default', 'Web', 'All'.
+ Setting up a new profile is a mater of creating a new directory and putting some bundles in it.</listitem>
+
+ <listitem><emphasis role="bold">Hot Deployement</emphasis> -
+ Similar to <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> there is a deployment scanner that scans
+ the 'deploy' folder for new or removed bundles.</listitem>
+
+ <listitem><emphasis role="bold">Multiple OSGi Frameworks</emphasis> -
+ The Installer can setup the JBoss OSGi Runtime using <link linkend="SecIntegrationFelix">Felix</link>,
+ <link linkend="SecIntegrationEquinox">Equinox</link> or <link linkend="SecIntegrationKnopflerfish">Knopflerfish</link>.
+ </listitem>
+
+ <listitem><emphasis role="bold">Local and Remote JMX Support</emphasis> -
+ There is local as well as remote support for JMX. Similar to <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink>
+ the JMXAdaptor (which provides the MBeanServerConnection) is bound to JNDI.
+ </listitem>
+
+ <listitem><emphasis role="bold">JNDI Support</emphasis> -
+ Components can access the JNDI InitialContext as a service from the registry.
+ </listitem>
+
+ <listitem><emphasis role="bold">SAX/DOM Parser Support</emphasis> -
+ The Runtime comes with an implementation of an <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/util/xml/XMLParserActivator.html">XMLParserActivator</ulink>
+ which provides access to a SAXParserFactory and DocumentBuilderFactory.
+ </listitem>
+
+ <listitem><emphasis role="bold">JAXB Support</emphasis> -
+ There is a bundle that provides JAXB support.
+ </listitem>
+
+ <listitem><emphasis role="bold">HttpService Support</emphasis> -
+ HttpService support is provided by a customized version of the <ulink url="http://felix.apache.org/site/apache-felix-web-console.html">Apache Felix Web Console</ulink>.
+ </listitem>
+
+ <listitem><emphasis role="bold">ConfigAdmin Support</emphasis> -
+ ConfigAdmin support is provided by the <ulink url="http://felix.apache.org/site/apache-felix-configuration-admin-service.html">Apache Felix Configuration Admin Service</ulink>.
+ </listitem>
+
+ <listitem><emphasis role="bold">Provisioning</emphasis> -
+ Bundle provisioning can be done through the JMX based Runtime Managment Interface.
+ </listitem>
+
+ <listitem><emphasis role="bold">Logging System</emphasis> -
+ The logging bridge writes OSGi LogEntries to the configured logging framework (e.g. Log4J). A local OSGi Runtime can receive LogEntries
+ from a remote instance.
+ </listitem>
+
+ <listitem><emphasis role="bold">Microcontainer Support</emphasis> -
+ The <ulink url="http://www.jboss.org/jbossmc">Microcontainer</ulink> service allows bundles to contain a *-beans.xml descriptor,
+ which can be used for component wiring and injection of base services. It also comes with a set of <link linkend="SecDeployers">deployers</link>
+ - so instead of simply installing a bundle to the underlying OSGi framework it passes to the chain of deployers which each deal with a specific
+ aspect of bundle deployment.
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml:id="SecRuntimeProfiles">
+ <title>Runtime Profiles</title>
+
+ <para>A runtime profile is a collection bundles that logically work together. The OSGi runtime configuration
+ contains the list of bundles that are installed/started automatically. You can start create you own profile
+ by setting up a new directory with your specific set of bundles.</para>
+
+ <note>
+ <title>TODO: [JBOSGI-98] Support configuration per profile</title>
+ </note>
+
+ <para>A runtime profile can be started using the <emphasis role="bold">-c comand line option</emphasis>.</para>
+
+ <programlisting>
+ [tdiesler at tddell runtime]$ bin/run.sh -c minimal
+ =========================================================================
+
+ JBossOSGi Bootstrap Environment
+
+ OSGI_HOME: /home/tdiesler/jboss-osgi-1.0.0.Beta2/runtime
+
+ JAVA: /usr/java/jdk1.6/bin/java
+
+ JAVA_OPTS: -Dprogram.name=run.sh ...
+
+ =========================================================================
+
+ 10:33:13,758 INFO [FelixIntegration] OSGi Integration Felix - 1.0.0.Beta2
+ 10:33:14,185 INFO [FelixIntegration] Installed bundle [1]: org.osgi.compendium
+ 10:33:14,194 INFO [FelixIntegration] Installed bundle [2]: org.apache.felix.log
+ 10:33:14,203 INFO [FelixIntegration] Installed bundle [3]: jboss-osgi-common
+ 10:33:14,212 INFO [FelixIntegration] Installed bundle [4]: jboss-osgi-hotdeploy
+ 10:33:14,247 INFO [FelixIntegration] Started bundle: org.apache.felix.log
+ 10:33:14,315 INFO [FelixIntegration] Started bundle: jboss-osgi-common
+ 10:33:14,357 INFO [jboss-osgi-hotdeploy] Start DeploymentScanner: [scandir=.../server/minimal/deploy,interval=2000ms]
+ 10:33:14,401 INFO [FelixIntegration] Started bundle: jboss-osgi-hotdeploy
+ <emphasis role="bold">10:33:14,403 INFO [OSGiBootstrap] JBossOSGi Runtime booted in 0.644sec</emphasis>
+ </programlisting>
+
+ <emphasis role="bold">Minimal Profile</emphasis>
+
+ <para>The 'minimal' profile provides logging and hot-deployment.</para>
+
+ <para>The following bundles are installed:</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">org.osgi.compendium.jar</emphasis> - OSGi compendium API</listitem>
+ <listitem><emphasis role="bold">jboss-osgi-common.jar</emphasis> - JBoss OSGi common services</listitem>
+ <listitem><emphasis role="bold">org.apache.felix.log.jar</emphasis> - Apache LogService</listitem>
+ <listitem><emphasis role="bold">jboss-osgi-hotdeploy.jar</emphasis> - JBoss OSGi hot deployment service</listitem>
+ </itemizedlist>
+
+ <emphasis role="bold">Default Profile</emphasis>
+
+ <para>The 'default' profile extends the 'minimal' profile by JNDI and JMX</para>
+
+ <para>These additional bundles are installed:</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">jboss-osgi-common-core.jar</emphasis> - JBoss Common Core functionality</listitem>
+ <listitem><emphasis role="bold">jboss-osgi-jmx.jar</emphasis> - JBoss OSGi JMX service</listitem>
+ <listitem><emphasis role="bold">jboss-osgi-jndi.jar</emphasis> - JBoss OSGi JNDI service</listitem>
+ </itemizedlist>
+
+ <emphasis role="bold">Web Profile</emphasis>
+
+ <para>The 'web' profile extends the 'default' profile by HttpService and ConfigAdmin</para>
+
+ <para>These additional bundles are installed:</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">org.apache.felix.configadmin.jar</emphasis> - Apache ConfigAdmin service</listitem>
+ <listitem><emphasis role="bold">org.apache.felix.http.jetty.jar</emphasis> - Apache HttpService</listitem>
+ <listitem><emphasis role="bold">jboss-osgi-webconsole.jar</emphasis> - JBoss OSGi Web Console</listitem>
+ </itemizedlist>
+
+ <emphasis role="bold">All Profile</emphasis>
+
+ <para>The 'all' profile extends the 'web' profile by SAX/DOM, JAXB, JBossXB and Microcontainer</para>
+
+ <para>These additional bundles are installed:</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">jboss-osgi-apache-xerces.jar</emphasis> - Apache Xerces support</listitem>
+ <listitem><emphasis role="bold">jboss-osgi-jaxb.jar</emphasis> - JAXB support</listitem>
+ <listitem><emphasis role="bold">jboss-osgi-xml-binding.jar</emphasis> - XML Binding (JBossXB) support</listitem>
+ <listitem><emphasis role="bold">jboss-osgi-microcontainer.jar</emphasis> - Microcontainer support</listitem>
+ </itemizedlist>
+ </sect1>
+
+</chapter>
+
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch040-framework-integration.xml (from rev 89712, projects/jboss-osgi/trunk/docbook/en/modules/ch30-framework-integration.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch040-framework-integration.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch040-framework-integration.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,221 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapFrameworkIntegration">
+
+ <title>Framework Integration</title>
+
+ <sect1 xml:id="SecIntegrationFelix">
+ <title>Apache Felix Integration</title>
+
+ <para>JBoss OSGi provides integration for the <ulink url="http://felix.apache.org">Apache Felix</ulink> OSGi Framework and some
+ of its core services</para>
+
+ <itemizedlist>
+ <listitem><ulink url="http://felix.apache.org/site/apache-felix-log-service.html">Log Service</ulink> - General purpose message logger</listitem>
+ <listitem><ulink url="http://felix.apache.org/site/apache-felix-http-service.html">HTTP Service</ulink> - Http access to servlets and resources</listitem>
+ <listitem><ulink url="http://felix.apache.org/site/apache-felix-configuration-admin-service.html">Config Admin Service</ulink> - Management of configuration data for configurable components</listitem>
+ </itemizedlist>
+
+ <para>The Apache Felix integration can be configured through properties in the <link linkend="ChapRuntime">JBoss OSGi Runtime</link>.
+ </para>
+
+ <programlisting role="XML"><![CDATA[
+ cat conf/jboss-osgi-framework.properties
+
+ # The OSGiFramework implementation
+ org.jboss.osgi.spi.framework.impl=org.jboss.osgi.felix.framework.FelixIntegration
+
+ # Properties to configure the Framework
+ org.osgi.framework.storage=${osgi.server.home}/data/osgi-store
+ org.osgi.framework.storage.clean=onFirstInit
+
+ # Hot Deployement
+ org.jboss.osgi.hotdeploy.scandir=${osgi.server.home}/bundles
+
+ ...
+
+ # Bundles that need to be installed with the Framework automatically
+ org.jboss.osgi.spi.framework.autoInstall=\
+ file://${osgi.home}/server/minimal/bundles/org.osgi.compendium.jar
+
+ # Bundles that need to be started automatically
+ org.jboss.osgi.spi.framework.autoStart=\
+ file://${osgi.home}/server/minimal/bundles/org.apache.felix.log.jar \
+ file://${osgi.home}/server/minimal/bundles/jboss-osgi-common.jar \
+ file://${osgi.home}/server/minimal/bundles/jboss-osgi-hotdeploy.jar
+ ]]></programlisting>
+
+ <para>In the <ulink url="http://www.jboss.org/jbossas">JBossAS</ulink> integration we use
+ <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> beans configuration.</para>
+
+ <programlisting role="XML"><![CDATA[
+ cat server/default/deployers/osgi.deployer/META-INF/osgi-deployers-jboss-beans.xml
+
+ <deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- The OSGiFramework -->
+ <bean name="jboss.osgi:service=Framework" class="org.jboss.osgi.felix.framework.FelixIntegration">
+ <property name="properties">
+ ...
+ </property>
+ <property name="autoStart">
+ <list elementClass="java.net.URL">
+ ...
+ </list>
+ </property>
+ </bean>
+ ...
+ </deployment>
+ ]]></programlisting>
+
+ <para>The following is a description of the configuration properties for the Apache Felix integration.</para>
+
+ <table>
+ <tr><th>Key</th><th>Value</th><th>Description</th></tr>
+ <tr valign="top">
+ <td>org.osgi.framework.storage</td>
+ <td>.../osgi-store</td>
+ <td>OSGi Framework storage area</td>
+ </tr>
+ <tr valign="top">
+ <td>org.osgi.framework.storage.clean</td>
+ <td>onFirstInit</td>
+ <td>Clean the storage area on first init</td>
+ </tr>
+ <tr valign="top">
+ <td>org.osgi.service.http.port</td>
+ <td>8090</td>
+ <td>The default Http Service port</td>
+ </tr>
+ <tr valign="top">
+ <td>felix.cm.dir</td>
+ <td>.../osgi-configadmin</td>
+ <td>Config Admin Service storage area</td>
+ </tr>
+ <tr valign="top">
+ <td>org.osgi.framework.system.packages.extra</td>
+ <td>javax.management, javax.xml...</td>
+ <td>Packages provided by the OSGi System ClassLoader</td>
+ </tr>
+ <tr valign="top">
+ <td>org.jboss.osgi.deferred.start</td>
+ <td>true</td>
+ <td>Bundles can be deployed in any order</td>
+ </tr>
+ </table>
+ </sect1>
+
+ <sect1 xml:id="SecIntegrationEquinox">
+ <title>Equinox Integration</title>
+
+ <para>JBoss OSGi also provides basic integration for the <ulink url="http://www.eclipse.org/equinox">Eclpipse Equinox</ulink> OSGi Framework.</para>
+
+ <para>Equinox integration can be configured through properties in the <link linkend="ChapRuntime">JBoss OSGi Runtime</link>.</para>
+
+ <programlisting role="XML"><![CDATA[
+ cat conf/jboss-osgi-framework.properties
+
+ # The OSGiFramework implementation
+ org.jboss.osgi.spi.framework.impl=org.jboss.osgi.equinox.framework.EquinoxIntegration
+
+ # Properties to configure the Framework
+ org.osgi.framework.storage=${osgi.server.home}/data/osgi-store
+ org.osgi.framework.storage.clean=onFirstInit
+
+ # Hot Deployement
+ org.jboss.osgi.hotdeploy.scandir=${osgi.server.home}/bundles
+
+ ...
+
+ # Bundles that need to be installed with the Framework automatically
+ org.jboss.osgi.spi.framework.autoInstall=\
+ file://${osgi.home}/server/minimal/bundles/org.osgi.compendium.jar
+
+ # Bundles that need to be started automatically
+ org.jboss.osgi.spi.framework.autoStart=\
+ file://${osgi.home}/server/minimal/bundles/org.apache.felix.log.jar \
+ file://${osgi.home}/server/minimal/bundles/jboss-osgi-common.jar \
+ file://${osgi.home}/server/minimal/bundles/jboss-osgi-hotdeploy.jar
+ ]]></programlisting>
+
+ <para>In the <ulink url="http://www.jboss.org/jbossas">JBossAS</ulink> integration we use
+ <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> beans configuration.</para>
+
+ <programlisting role="XML"><![CDATA[
+ <deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- The OSGiFramework -->
+ <bean name="jboss.osgi:service=Framework" class="org.jboss.osgi.equinox.framework.EquinoxIntegration">
+ <property name="properties">
+ ...
+ </property>
+ <property name="autoStart">
+ <list elementClass="java.net.URL">
+ ...
+ </list>
+ </property>
+ </bean>
+ ...
+ </deployment>
+ ]]></programlisting>
+
+ </sect1>
+
+ <sect1 xml:id="SecIntegrationKnopflerfish">
+ <title>Knopflerfish Integration</title>
+
+ <para>JBoss OSGi provides basic integration for the <ulink url="http://www.knopflerfish.org">Makewave Knopflerfish</ulink> OSGi Framework.</para>
+
+ <para>Knopflerfish integration can be configured through properties in the <link linkend="ChapRuntime">JBoss OSGi Runtime</link>.</para>
+
+ <programlisting role="XML"><![CDATA[
+ cat conf/jboss-osgi-framework.properties
+
+ # The OSGiFramework implementation
+ org.jboss.osgi.spi.framework.impl=org.jboss.osgi.knopflerfish.framework.KnopflerfishIntegration
+
+ # Properties to configure the Framework
+ org.osgi.framework.storage=${osgi.server.home}/data/osgi-store
+ org.osgi.framework.storage.clean=onFirstInit
+
+ # Hot Deployement
+ org.jboss.osgi.hotdeploy.scandir=${osgi.server.home}/bundles
+
+ ...
+
+ # Bundles that need to be installed with the Framework automatically
+ org.jboss.osgi.spi.framework.autoInstall=\
+ file://${osgi.home}/server/minimal/bundles/org.osgi.compendium.jar
+
+ # Bundles that need to be started automatically
+ org.jboss.osgi.spi.framework.autoStart=\
+ file://${osgi.home}/server/minimal/bundles/org.apache.felix.log.jar \
+ file://${osgi.home}/server/minimal/bundles/jboss-osgi-common.jar \
+ file://${osgi.home}/server/minimal/bundles/jboss-osgi-hotdeploy.jar
+ ]]></programlisting>
+
+ <para>In the <ulink url="http://www.jboss.org/jbossas">JBossAS</ulink> integration we use
+ <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> beans configuration.</para>
+
+ <programlisting role="XML"><![CDATA[
+ <deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- The OSGiFramework -->
+ <bean name="jboss.osgi:service=Framework" class="org.jboss.osgi.knopflerfish.KnopflerfishIntegration">
+ <property name="properties">
+ ...
+ </property>
+ <property name="autoStart">
+ <list elementClass="java.net.URL">
+ ...
+ </list>
+ </property>
+ </bean>
+ ...
+ </deployment>
+ ]]></programlisting>
+
+ </sect1>
+
+</chapter>
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch050-developer-guide.xml (from rev 89723, projects/jboss-osgi/trunk/docbook/en/modules/ch40-developer-guide.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch050-developer-guide.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch050-developer-guide.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,362 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapDeveloperGuide">
+
+ <title>Developer Documentation</title>
+
+ <sect1 xml:id="SecSPI">
+ <title>Service Provider Interface</title>
+
+ <para>The JBoss OSGi Service Provider Interface (SPI) is the integration point for:</para>
+
+ <itemizedlist>
+ <listitem>Supported OSGi Frameworks</listitem>
+ <listitem>Supported Target Containers</listitem>
+ <listitem>Administration, Provisioning and Management</listitem>
+ <listitem>Various Provided Services</listitem>
+ <listitem>Testing Framework</listitem>
+ </itemizedlist>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/jbossosgi-spi.png" contentwidth="450"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>The latest version of the <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc">JBoss OSGi SPI</ulink>
+ JavaDoc is published online as part of the JBoss OSGi <ulink url="http://jbmuc.dyndns.org:8280/hudson">Hudson QA Environment</ulink>.</para>
+
+ <itemizedlist>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/package-summary.html">org.jboss.osgi.spi</ulink> - Common classes and interfaces.</listitem>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/capability/package-summary.html">org.jboss.osgi.spi.capability</ulink> - Capabilities that can be installed in the OSGi framework.</listitem>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/framework/package-summary.html">org.jboss.osgi.spi.framework</ulink> - Framework integration and bootstrap.</listitem>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/logging/package-summary.html">org.jboss.osgi.spi.logging</ulink> - Support for Bundle logging.</listitem>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/management/package-summary.html">org.jboss.osgi.spi.management</ulink> - Management view on deployed bundles.</listitem>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/service/package-summary.html">org.jboss.osgi.spi.service</ulink> - A collection of SPI provided services.</listitem>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/testing/package-summary.html">org.jboss.osgi.spi.testing</ulink> - OSGi test support classes and interfaces.</listitem>
+ </itemizedlist>
+
+ <emphasis role="bold">Bootstrapping JBoss OSGi</emphasis>
+
+ <para>The OSGiBootstrap provides an OSGiFramework through a OSGiBootstrapProvider.</para>
+
+ <para>A OSGiBootstrapProvider is discovered in two stages</para>
+
+ <orderedlist>
+ <listitem>Read the bootstrap provider class name from a system property</listitem>
+ <listitem>Read the bootstrap provider class name from a resource file</listitem>
+ </orderedlist>
+
+ <para>In both cases the key is the fully qalified name of the <code>org.jboss.osgi.spi.framework.OSGiBootstrapProvider</code> interface.</para>
+
+ <para>The following code shows how to get the default <code>OSGiFramework</code> from the <code>OSGiBootstrapProvider</code>.</para>
+
+ <programlisting role="JAVA">
+ OSGiBootstrapProvider bootProvider = OSGiBootstrap.getBootstrapProvider();
+ OSGiFramework framework = bootProvider.getFramework();
+ Bundle bundle = framework.getSystemBundle();
+ </programlisting>
+
+ <para>The <code>OSGiBootstrapProvider</code> can also be configured explicitly. The <code>OSGiFramework</code> is a named
+ object from the configuration.</para>
+
+ <programlisting role="JAVA">
+ OSGiBootstrapProvider bootProvider = OSGiBootstrap.getBootstrapProvider();
+ bootProvider.configure(configURL);
+
+ OSGiFramework framework = bootProvider.getFramework("AnotherOSGiFramework");
+ Bundle bundle = framework.getSystemBundle();
+ </programlisting>
+
+ <para>The JBoss OSGi SPI comes with two bootstrap providers:</para>
+
+ <itemizedlist>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/framework/PropertiesBootstrapProvider.html">PropertiesBootstrapProvider</ulink></listitem>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/framework/MicrocontainerBootstrapProvider.html">MicrocontainerBootstrapProvider</ulink></listitem>
+ </itemizedlist>
+
+ <para>OSGiBootstrapProvider implementations that read their configurtation from some other source are possible, but currently not
+ part of the JBoss OSGi SPI.</para>
+
+ <tip>
+ <title>Using the SPI from within JBossAS deployed components</title>
+ <para>If you need access to the OSGi Framework from within an JBossAS deployed component (e.g. servlet, ejb, mbean) you
+ <emphasis role="bold">would not</emphasis> bootstrap JBoss OSGi through the SPI. Instead, you would inject the already bootstrapped
+ OSGi Framework instance into your component.</para>
+ </tip>
+ </sect1>
+
+ <sect1 xml:id="SecDeployers">
+ <title>Bundle Deployers</title>
+
+ <para>JBoss OSGi comes with a number of <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> based deployers. Each deployer
+ takes care of a specific aspect of bundle deployment.</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">BundleClassLoaderDeployer</emphasis> - Creates a BundleClassLoader for the deployed Bundle</listitem>
+ <listitem><emphasis role="bold">BundleContainedBeansDeployer</emphasis> - Deploy the bundle contained MC beans onto the Kernel</listitem>
+ <listitem><emphasis role="bold">BundleManagementDeployer</emphasis> - Register the Bundle as MBean with JMX</listitem>
+ <listitem><emphasis role="bold">BundleMetaDataDeployer</emphasis> - Create BundleMetaData from Manifest Headers</listitem>
+ <listitem><emphasis role="bold">BundleRealDeployer</emphasis> - Installs the Bundle into the Framework's SystemContext</listitem>
+ <listitem><emphasis role="bold">BundleStartStopDeployer</emphasis> - Starts the Bundle when dependencies are resolved</listitem>
+ <listitem><emphasis role="bold">BundleStructureDeployer</emphasis> - Determine the structure of a Bundle deployment</listitem>
+ </itemizedlist>
+
+ <emphasis role="bold">BundleClassLoaderDeployer</emphasis>
+
+ <para>The BundleClassLoaderDeployer attaches a ClassLoaderFactory that creates a BundleClassLoader for the deployed Bundle.
+ A BundleClassLoader delegates all classloading concerns to the underlying Bundle.</para>
+
+ <emphasis role="bold">BundleContainedBeansDeployer</emphasis>
+
+ <para>The BundleContainedBeansDeployer is a ComponentDeployer that deployes the MC bean components onto
+ the Kernel.</para>
+
+ <emphasis role="bold">BundleManagementDeployer</emphasis>
+
+ <para>The BundleManagementDeployer registers the Bundle as <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/StandardMBean.html">StandardMBean</ulink> with JMX.
+ Please see the section on <link linkend="SecJMXView">Management View</link> for details.</para>
+
+ <emphasis role="bold">BundleMetaDataDeployer</emphasis>
+
+ <para>The BundleMetaDataDeployer creates the BundleMetaData from Manifest Headers. If the manifest does not contain
+ a header named <emphasis role="bold">Bundle-SymbolicName</emphasis> this deployer does nothing. </para>
+
+ <emphasis role="bold">BundleRealDeployer</emphasis>
+
+ <para>The BundleRealDeployer installs the Bundle into the Framework's SystemContext. Optionally you can configure a list of
+ bundle locations that should be skipped and hence not installed. Typically, these bundles are already installed during
+ Framework startup.</para>
+
+ <para>On undeploy the Bundle gets uninstalled from the Framework's SystemContext.</para>
+
+ <emphasis role="bold">BundleStartStopDeployer</emphasis>
+
+ <para>The BundleStartStopDeployer currently works in two modes:</para>
+
+ <itemizedlist>
+ <listitem>deferredStart (default)</listitem>
+ <listitem>simpleStart</listitem>
+ </itemizedlist>
+
+ <para>In mode <emphasis role="bold">deferredStart</emphasis> the Bundle is added to a list of unresolved Bundles, which then get passed
+ on to <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/packageadmin/PackageAdmin.html#resolveBundles(org.osgi.framework.Bundle[])"><code>PackageAdmin.resolveBundles(Bundle[])</code></ulink>.
+ The deployer then iterates over the unresolved Bundles and only starts those Bundles that are in state
+ <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/framework/Bundle.html#RESOLVED"><code>RESOLVED</code></ulink>.
+ In this mode Bundles can be deployed in any order and only get started when all their respective dependencies can be resolved.</para>
+
+ <para>In mode <emphasis role="bold">simpleStart</emphasis> the deployer attempts to start the Bundle regardless of whether its
+ dependencies can get resolved. In case the Bundle has a dependency oin a package that is not yet available, deployment will fail.
+ In this mode Bundles must be deployed in the order required to start them.</para>
+
+ <para>The start mode is a configurable property on the Framework's SystemContext.</para>
+
+ <programlisting role="XML"><![CDATA[
+ <!--
+ If set to 'true' bundles can be deployed in any order. Deployed bundle will get started when their dependencies can be resolved.
+ If set to 'false' bundles must be deployed in the order that is required to start them.
+ -->
+ <entry><key>org.jboss.osgi.deferred.start</key><value>true</value></entry>
+ ]]></programlisting>
+
+ <emphasis role="bold">BundleStructureDeployer</emphasis>
+
+ <para>The BundleStructureDeployer determines the structure of a Bundle deployment. It ignores all deployments that
+ are not top-level or do not have a manifest header named <emphasis role="bold">Bundle-SymbolicName</emphasis></para>
+
+ </sect1>
+
+ <sect1 xml:id="SecJMXView">
+ <title>Management View</title>
+
+ <para>JBoss OSGi registers the Framework and every deployed Bundle with the JMX <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServer.html">MBeanServer</ulink>.</para>
+
+ <emphasis role="bold">The ManagedFramework</emphasis>
+
+ <para>The <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/management/ManagedFrameworkMBean.html">
+ ManagedFramework</ulink> gives you access to the MBean views of the deployed Bundles. It is registerd under the name:</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">jboss.osgi:service=ManagedFramework</emphasis></listitem>
+ </itemizedlist>
+
+ <emphasis role="bold">The ManagedBundle</emphasis>
+
+ <para>The <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/management/ManagedBundle.html">
+ ManagedBundle</ulink> gives you access to the MBean views of a deployed Bundle. It is registerd under the name:</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">jboss.osgi:bundle=[SymbolicName],id=[BundleId]</emphasis></listitem>
+ </itemizedlist>
+
+ <emphasis role="bold">Accessing the Management Objects</emphasis>
+
+ <para>If you work with the JBoss OSGi Testsuite you get access to the Managed Objects through the JBoss OSGi SPI provided
+ <ulink url="http://junit.sourceforge.net/">JUnit</ulink> support package <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/testing/package-summary.html">org.jboss.osgi.spi.testing</ulink>.
+ </para>
+
+ <para>If you install JBoss OSGi in an already existing JBossAS instance you also get access to the Managed Objects through the JBoss provided
+ JMX Console (<ulink url="http://localhost:8080/jmx-console">http://localhost:8080/jmx-console</ulink>).</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/jmx-agent-view.png" contentwidth="450"/>
+ </imageobject>
+ </mediaobject>
+
+ <note>
+ <para>The JMX Console is <emphasis role="bold">not part</emphasis> of the <link linkend="ChapRuntime">JBoss OSGi Runtime</link>.</para>
+ </note>
+ </sect1>
+
+ <sect1 xml:id="SecWritingTests">
+ <title>Writing Test Cases</title>
+
+ <para>JBoss OSGi comes with <ulink url="http://www.junit.org">JUnit</ulink> test support as part of the SPI provided
+ <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/testing/package-summary.html">org.jboss.osgi.spi.testing</ulink>
+ package. There are two distinct test scenarios that we support:</para>
+
+ <itemizedlist>
+ <listitem>Embedded OSGi Framework</listitem>
+ <listitem>Remote OSGi Framework</listitem>
+ </itemizedlist>
+
+ <para>The remote scenario can actually be separated again in:</para>
+
+ <itemizedlist>
+ <listitem>Standalone JBoss OSGi Runtime</listitem>
+ <listitem>JBoss OSGi Runtime running in JBossAS</listitem>
+ </itemizedlist>
+
+ <para>A test case that takes advantage of the SPI provided OSGi runtime abstration would transparently handle these scenarios.</para>
+
+ <sect2 xml:id="SecWritingTestsSimpleTestCase">
+
+ <title>Simple Test Case</title>
+
+ <para>The test case bootstraps the OSGi Runtime, installes/starts the bundle, asserts the bundle state and finally
+ shuts down the runtime again. Please note, this is a plain JUnit4 test case that transparently handles embedded/remote
+ nature of the runtime.
+ </para>
+
+ <programlisting role="JAVA">
+ public class SimpleTestCase
+ {
+ @Test
+ public void testSimpleBundle() throws Exception
+ {
+ // Get the default runtime
+ OSGiRuntime runtime = new OSGiTestHelper().getDefaultRuntime();
+
+ // Install the bundle
+ OSGiBundle bundle = runtime.installBundle("example-simple.jar");
+ assertEquals("Bundle installed", Bundle.INSTALLED, bundle.getState());
+
+ // Start the bundle
+ bundle.start();
+ assertEquals("Bundle active", Bundle.ACTIVE, bundle.getState());
+
+ // Uninstall the bundle
+ bundle.uninstall();
+
+ // Shutdown the runtime
+ runtime.shutdown();
+ }
+ }
+ </programlisting>
+
+ <para>To run the test in embedded mode (which is the default) you would execute your test runner like this
+ </para>
+
+ <programlisting role="JAVA">
+ [tdiesler at tddell example]$ mvn -Dtest=SimpleTestCase test
+ ...
+ Running org.jboss.test.osgi.example.simple.SimpleTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.361 sec
+ </programlisting>
+
+ <para>To run the test against the remote JBoss OSGi Runtime you would execute your test runner like this
+ </para>
+
+ <programlisting role="JAVA">
+ [tdiesler at tddell example]$ mvn -Dtarget.container=runtime -Dtest=SimpleTestCase test
+ ...
+ Running org.jboss.test.osgi.example.simple.SimpleTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.303 sec
+ </programlisting>
+
+ <para>In the runtime console you should see</para>
+
+ <programlisting role="JAVA">
+ 12:44:30,960 INFO [jboss-osgi-common] Installed: example-simple [8]
+ 12:44:31,081 INFO [example-simple] Start: example-simple [8]
+ 12:44:31,089 INFO [example-simple] Stop: example-simple [8]
+ 12:44:31,095 INFO [jboss-osgi-common] Uninstalled: example-simple [8]
+ </programlisting>
+
+ <para>Due to classloading restrictions it is not possible to interact with the services that get registered in the OSGi Framework
+ directly. Instead, there must be some means for the bundle under test to communicate with the test case that lives outside the
+ Framework. The approach of OSGi testing based on remote log messages is covered in
+ <ulink url="http://jbossosgi.blogspot.com/2009/04/non-intrusive-osgi-bundle-testing.html">Non intrusive OSGi Bundle Testing</ulink>.</para>
+
+ <para>The next section explains how to write a plain JUnit test that is then executed within the OSGi Runtime.</para>
+ </sect2>
+
+ <sect2 xml:id="SecWritingTestsSimpleHuskyTestCase">
+
+ <title>Simple Husky Test Case</title>
+
+ <para>The test case does everthing identical to <link linkend="SecWritingTestsSimpleTestCase">SimpleTestCase</link>
+ (setUp and tearDown not shown again), but only executes the code in the test method when Husky injected the BundleContext.
+ </para>
+
+ <programlisting role="JAVA">
+ public class SimpleHuskyTestCase
+ {
+ @ProvideContext
+ public BundleContext context;
+
+ ...
+
+ @Test
+ public void testSimpleBundle() throws Exception
+ {
+ // Tell Husky to run this test method within the OSGi Runtime
+ if (context == null)
+ BridgeFactory.getBridge().run();
+
+ // Stop here if the context is not injected
+ assumeNotNull(context);
+
+ // Get the SimpleService reference
+ ServiceReference sref = context.getServiceReference(SimpleService.class.getName());
+ assertNotNull("SimpleService Not Null", sref);
+
+ // Access the SimpleService
+ SimpleService service = (SimpleService)context.getService(sref);
+ assertEquals("hello", service.echo("hello"));
+ }
+ }
+ </programlisting>
+
+ <para>Running this test is also no different from <link linkend="SecWritingTestsSimpleTestCase">SimpleTestCase</link>.</para>
+
+ <para>In the runtime console you should see</para>
+
+ <programlisting role="JAVA">
+ 13:29:15,924 INFO [jboss-osgi-common] Installed: example-simple-husky [16]
+ 13:29:15,972 INFO [example-simple-husky] Start: example-simple-husky [16]
+ 13:29:15,981 INFO [jboss-osgi-husky] Test-Package [org.jboss.test.osgi.example.simple] in bundle: example-simple-husky [16]
+ 13:29:16,160 INFO [example-simple-husky] echo: hello
+ 13:29:16,191 INFO [example-simple-husky] Stop: example-simple-husky [16]
+ 13:29:16,196 INFO [jboss-osgi-common] Uninstalled: example-simple-husky [16]
+ </programlisting>
+
+ <para>To learn more about the magic of the BridgeFactory have a look at <link linkend="ChapHuskyTesting">Husky Test Framework</link>
+ which comes next.</para>
+ </sect2>
+
+ </sect1>
+
+</chapter>
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch060-husky-testing.xml (from rev 89723, projects/jboss-osgi/trunk/docbook/en/modules/ch50-husky-testing.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch060-husky-testing.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch060-husky-testing.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,29 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapHuskyTesting">
+
+ <title>Husky Test Framework</title>
+
+ <sect1 xml:id="SecHuskyOverview">
+ <title>Overview</title>
+
+ <para>[TODO]</para>
+
+ </sect1>
+
+ <sect1 xml:id="SecHuskyConfiguration">
+ <title>Configuration</title>
+
+ <para>[TODO]</para>
+
+ </sect1>
+
+ <sect1 xml:id="SecHuskyWritingTests">
+ <title>Writing Husky Tests</title>
+
+ <para>[TODO]</para>
+
+ </sect1>
+
+</chapter>
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch070-provided-bundles.xml (from rev 89712, projects/jboss-osgi/trunk/docbook/en/modules/ch60-provided-bundles.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch070-provided-bundles.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch070-provided-bundles.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,141 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapProvidedBundles">
+
+ <title>Provided Bundles and Services</title>
+
+ <sect1 xml:id="SecLoggingService">
+ <title>Logging Bridge Service</title>
+
+ <para>The JBoss OSGi <emphasis role="bold">jboss-osgi-logging.jar</emphasis> bundle contains a simple Logging Bridge Service to
+ <ulink url="http://www.jboss.org/community/docs/DOC-11280">JBoss Logging</ulink>. It registers a trivial LogListener with the
+ LogReaderService in case that service is registered with the Framework.</para>
+
+ <itemizedlist>
+ <listitem><ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListener.html">LogListener</ulink> - Subscribes to LogEntry objects from the LogReaderService</listitem>
+ <listitem><ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReaderService.html">LogReaderService</ulink> - Provides methods to retrieve LogEntry objects from the log</listitem>
+ </itemizedlist>
+
+ <para>The LogReaderService is part of the standard <ulink url="http://www.osgi.org/Download/File?url=/download/r4v41/r4.cmpn.pdf">OSGi
+ Compendium Services</ulink>. JBoss OSGi currently uses the <ulink url="http://felix.apache.org/site/apache-felix-log-service.html">Log Service</ulink>
+ from <ulink url="http://felix.apache.org">Apache Felix</ulink>, which gets deployed as Bundle <emphasis role="bold">org.apache.felix.log.jar</emphasis>
+ </para>
+
+ <para>The LogListener itself logs messages under the Bundle's symbolic name.</para>
+
+ <programlisting role="JAVA">
+ public class JBossLoggingLogListener implements LogListener
+ {
+ public void logged(LogEntry entry)
+ {
+ Bundle bundle = entry.getBundle();
+ int level = entry.getLevel();
+ Throwable throwable = entry.getException();
+
+ String loggerName = bundle.getSymbolicName();
+ Logger log = Logger.getLogger(loggerName);
+
+ if (level == LogService.LOG_DEBUG)
+ log.debug(entry.getMessage(), throwable);
+
+ else if (level == LogService.LOG_INFO)
+ log.info(entry.getMessage(), throwable);
+
+ else if (level == LogService.LOG_WARNING)
+ log.warn(entry.getMessage(), throwable);
+
+ else if (level == LogService.LOG_ERROR)
+ log.error(entry.getMessage(), throwable);
+ }
+ }
+ </programlisting>
+
+ <para>You can therefore change the logging for specific Bundles by
+ <ulink url="http://www.jboss.org/community/docs/DOC-12490">setting the respective logging level</ulink>.</para>
+ </sect1>
+
+ <sect1 xml:id="SecRemoteLogService">
+ <title>Remote Log Service</title>
+
+ <para>The JBoss OSGi <emphasis role="bold">jboss-osgi-remotelog.jar</emphasis> bundle contains a client side
+ <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReaderService.html">RemoteLogReaderService</ulink> that remotely
+ communicates with a server side <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListener.html">LogListener</ulink>.
+ </para>
+
+ <para>The Remote Log Service is configured with these properties.</para>
+
+ <table>
+ <tr><th>Key</th><th>Value</th><th>Description</th></tr>
+ <tr valign="top">
+ <td>org.jboss.osgi.service.remote.log.sender</td>
+ <td>true/false</td>
+ <td>Enable the server side LogListener</td>
+ </tr>
+ <tr valign="top">
+ <td>org.jboss.osgi.service.remote.log.reader</td>
+ <td>true/false</td>
+ <td>Enable the client side LogReaderService</td>
+ </tr>
+ <tr valign="top">
+ <td>org.jboss.osgi.service.remote.log.host</td>
+ <td>localhost</td>
+ <td>The remote host that log messages are sent to</td>
+ </tr>
+ <tr valign="top">
+ <td>org.jboss.osgi.service.remote.log.port</td>
+ <td>5400</td>
+ <td>The remote port that log messages are sent to</td>
+ </tr>
+ </table>
+
+ <para>On the client side you can install an arbitrary <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListener.html">LogListener</ulink>
+ with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReaderService.html">RemoteLogReaderService</ulink>. The testsuite typically
+ installs an <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/ws/jboss-osgi/spi/target/apidocs/org/jboss/osgi/spi/logging/LogEntryCache.html">LogEntryCache</ulink>
+ that filters the received log messages.</para>
+
+ <programlisting role="JAVA">
+ LogEntryCache logEntryCache = new LogEntryCache();
+ logEntryCache.addFilter(new LogEntryFilter("example-log(.*)", LogService.LOG_INFO, "\\[ServiceA\\](.*)"));
+
+ // Track the RemoteLogReaderService to add the LogEntryCache as LogListener
+ ServiceTracker tracker = new ServiceTracker(sysContext, RemoteLogReaderService.class.getName(), null)
+ {
+ @Override
+ public Object addingService(ServiceReference sref)
+ {
+ LogReaderService service = (LogReaderService)super.addingService(sref);
+ service.addLogListener(logEntryCache);
+ return service;
+ }
+ };
+ tracker.open();
+ </programlisting>
+ </sect1>
+
+ <sect1 xml:id="SecMicrocontainerService">
+ <title>Microcontainer Service</title>
+
+ <para>JBoss OSGi SPI comes with a service that give access to the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> Kernel
+ and the JMX <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServer.html">MBeanServer</ulink>. The service is
+ registered with the Framework under the name</para>
+
+ <itemizedlist>
+ <listitem><emphasis role="bold">org.jboss.osgi.service.MicrocontainerService</emphasis></listitem>
+ </itemizedlist>
+
+ <para>Here is an example of how an OSGi component can register an arbitrary MBean with the
+ <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServer.html">MBeanServer</ulink>.</para>
+
+ <programlisting role="JAVA">
+ ServiceReference sref = context.getServiceReference(MicrocontainerService.class.getName());
+ if (sref == null)
+ throw new IllegalStateException("MicrocontainerService not registered");
+
+ MicrocontainerService mcService = (MicrocontainerService)context.getService(sref);
+ MBeanServer mbeanServer = mcService.getMbeanServer();
+ mbeanServer.registerMBean(new Foo(), OBJECT_NAME);
+ </programlisting>
+ </sect1>
+
+</chapter>
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch080-provided-examples.xml (from rev 89712, projects/jboss-osgi/trunk/docbook/en/modules/ch70-provided-examples.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch080-provided-examples.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch080-provided-examples.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,165 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapProvidedExamples">
+
+ <title>Provided Examples</title>
+
+ <sect1 xml:id="SecBuildAndRunExamples">
+ <title>Building the Examples</title>
+
+ <para>JBoss OSGi comes with a number of examples that demonstrate supported functionality
+ and show best practices. All examples are part of the binary distribution and tightly
+ integrated in our <ulink url="http://www.jboss.org/community/docs/DOC-13275">Maven Build Process</ulink>
+ and <ulink url="http://www.jboss.org/community/docs/DOC-13420">Hudson QA Environment</ulink>.</para>
+
+ <para>The examples can be either run against a local embedded OSGi Framework or against
+ a remote OSGi Runtime instance. Here is how you build and run the against the embedded OSGi Framework.</para>
+
+ <programlisting>
+ /home/yourname/jboss-osgi-1.0.0.Beta1/example
+ [tdiesler at tddell example]$ mvn test
+ ...
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Building JBoss OSGi - Testsuite Examples
+ [INFO] task-segment: [test]
+ [INFO] ------------------------------------------------------------------------
+ ...
+ build-example-jars:
+ # example-log (example-log.jar) 2
+ # example-http (example-http.jar) 4
+ # example-microcontainer (example-microcontainer.jar) 4
+ ...
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.jboss.test.osgi.example.log.LogServiceTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.876 sec
+ ...
+ [INFO] ------------------------------------------------------------------------
+ [INFO] BUILD SUCCESSFUL
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Total time: 17 seconds
+ [INFO] Finished at: Tue Apr 21 14:32:31 CEST 2009
+ [INFO] Final Memory: 21M/51M
+ [INFO] ------------------------------------------------------------------------
+ </programlisting>
+
+ <para>To run the examples against a remote OSGi Runtime, you need to provide the
+ host theat the runtime binds to. This can be done with the
+ <emphasis role="bold">-Djboss.bind.address=localhost</emphasis> property.</para>
+
+ <programlisting>
+ /home/yourname/jboss-osgi-1.0.0.Beta1/example
+ [tdiesler at tddell example]$ mvn -Djboss.bind.address=localhost test
+ ...
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Building JBoss OSGi - Testsuite Examples
+ [INFO] task-segment: [test]
+ [INFO] ------------------------------------------------------------------------
+ ...
+ build-example-jars:
+ # example-log (example-log.jar) 2
+ # example-http (example-http.jar) 4
+ # example-microcontainer (example-microcontainer.jar) 4
+ ...
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.jboss.test.osgi.example.http.HttpServiceRemoteTestCase
+ Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.435 sec
+ Running org.jboss.test.osgi.example.log.LogServiceTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.06 sec
+ Running org.jboss.test.osgi.example.microcontainer.MBeanServiceRemoteTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.177 sec
+ Running org.jboss.test.osgi.example.log.LogServiceRemoteTestCase
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.632 sec
+ ...
+ [INFO] ------------------------------------------------------------------------
+ [INFO] BUILD SUCCESSFUL
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Total time: 29 seconds
+ [INFO] Finished at: Tue Apr 21 14:47:33 CEST 2009
+ [INFO] Final Memory: 44M/82M
+ [INFO] ------------------------------------------------------------------------
+ </programlisting>
+ </sect1>
+
+ <sect1 xml:id="SecHTTPServiceExample">
+ <title>HTTP Service Example</title>
+
+ <para>The <emphasis role="bold">example-http.jar</emphasis> bundle contains a Service
+ that registeres a servlet and a resource with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/http/HttpService.html">HttpService</ulink>.
+ </para>
+
+ <programlisting role="JAVA">
+ ServiceTracker tracker = new ServiceTracker(context, HttpService.class.getName(), null);
+ tracker.open();
+
+ HttpService httpService = (HttpService)tracker.getService();
+ if (httpService == null)
+ throw new IllegalStateException("HttpService not registered");
+
+ Properties initParams = new Properties();
+ initParams.setProperty("initProp", "SomeValue");
+ httpService.registerServlet("/servlet", new EndpointServlet(context), initParams, null);
+ httpService.registerResources("/file", "/res", null);
+ </programlisting>
+
+ <para>The test then verifies that the registered servlet context and the registered resource can be accessed.</para>
+ </sect1>
+
+ <sect1 xml:id="SecLogServiceExample">
+ <title>Log Service Example</title>
+
+ <para>The <emphasis role="bold">example-log.jar</emphasis> bundle contains a Service
+ that logs messages to the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogService.html">LogService</ulink>.
+
+ </para>
+
+ <programlisting role="JAVA">
+ public ServiceA(BundleContext context)
+ {
+ log = new LogServiceTracker(context);
+ log.log(LOG_INFO, "[ServiceA] new Service");
+ }
+ </programlisting>
+
+ <para>The test then filters and verifies the log messages.</para>
+
+ <programlisting role="JAVA">
+ LogEntryCache logEntryCache = new LogEntryCache();
+ logEntryCache.addFilter(new LogEntryFilter(null, 0, "\\[ServiceA\\](.*)"));
+ startLogEntryTracking(logEntryCache);
+
+ // Verify the received log entries
+ List entries = logEntryCache.getLog();
+ assertEquals("Number of entries", 1, entries.size());
+ assertEquals("[ServiceA] new Service", entries.get(0).getMessage());
+ </programlisting>
+
+ <para>The test is available both for embedded and remote LogService testing.</para>
+ </sect1>
+
+ <sect1 xml:id="SecMicrocontainerServiceExample">
+ <title>MC Service Example</title>
+
+ <para>The <emphasis role="bold">example-microcontainer.jar</emphasis> bundle contains a Service
+ that registers an MBean with the <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServer.html">MBeanServer</ulink>.
+ </para>
+
+ <programlisting role="JAVA">
+ MicrocontainerService service = (MicrocontainerService)tracker.getService();
+ mbeanServer = mcService.getMbeanServer();
+ mbeanServer.registerMBean(new Foo(), OBJECT_NAME);
+ </programlisting>
+
+ <para>The test then accesses the registered MBean.</para>
+
+ <programlisting role="JAVA">
+ FooMBean foo = (FooMBean)MBeanProxy.get(FooMBean.class, OBJECT_NAME, getServer());
+ assertEquals("hello", foo.echo("hello"));
+ </programlisting>
+ </sect1>
+
+</chapter>
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch090-references.xml (from rev 89712, projects/jboss-osgi/trunk/docbook/en/modules/ch80-references.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch090-references.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch090-references.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,27 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapReferences">
+
+ <title>References</title>
+
+ <para><emphasis role="bold">Resources</emphasis></para>
+
+ <itemizedlist>
+ <listitem><ulink url="http://www.jboss.org/community/wiki/JBoss OSGi">JBoss OSGi Wiki</ulink></listitem>
+ <listitem><ulink url="http://jbossosgi.blogspot.com">JBoss OSGi Diary (Blog)</ulink></listitem>
+ <listitem><ulink url="https://jira.jboss.org/jira/browse/JBOSGI">Issue Tracking</ulink></listitem>
+ <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson">Hudson QA</ulink></listitem>
+ <listitem><ulink url="https://anonsvn.jboss.org/repos/jbossas/projects/jboss-osgi">Subversion</ulink></listitem>
+ <listitem><ulink url="http://fisheye.jboss.com/browse/JBoss OSGi">Fisheye</ulink></listitem>
+ <listitem><ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=257">User Forum</ulink></listitem>
+ <listitem><ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=256">Design Forum</ulink></listitem>
+ </itemizedlist>
+
+ <para><emphasis role="bold">Authors</emphasis></para>
+
+ <itemizedlist>
+ <listitem><ulink url="email:thomas.diesler at jboss.com">Thomas Diesler</ulink></listitem>
+ </itemizedlist>
+
+</chapter>
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch10-getting-started.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch10-getting-started.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch10-getting-started.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,388 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapGettingStarted">
-
- <title>Getting Started</title>
-
- <para>This chapter takes you through the first steps of getting JBoss OSGi and
- provides the initial pointers to get up and running.</para>
-
- <sect1 xml:id="SecDownload">
- <title>Download the Distribution</title>
-
- <para>JBoss OSGi is distributed as an <ulink url="http://izpack.org">IzPack</ulink> installer archive.
- The installer is available from the JBoss OSGi <ulink url="https://sourceforge.net/project/showfiles.php?group_id=22866&package_id=316015">download area</ulink>.</para>
- </sect1>
-
- <sect1 xml:id="SecInstall">
- <title>Running the Installer</title>
-
- <para>To run the installer execute the following command:</para>
-
- <programlisting>
- java -jar jboss-osgi-installer-1.0.0.Beta2.jar
- </programlisting>
-
- <para>The installer first shows a welcome screen</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-welcome.png"/>
- </imageobject>
- </mediaobject>
-
- <para>Then you select the installation path for the JBoss OSGi distribution. This is the directory where you find the binary build artifacts,
- the java sources, documentation and the JBoss OSGi Runtime.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-installpath.png"/>
- </imageobject>
- </mediaobject>
-
- <para>The installer contains multiple installation packs. Greyed packs are required, others are optional and can be deselected.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-packs.png"/>
- </imageobject>
- </mediaobject>
-
- <itemizedlist>
- <listitem><emphasis role="bold">JBoss OSGi Distribution</emphasis> - Documentation, Binary Artifacts and Sources</listitem>
- <listitem><emphasis role="bold">JBoss OSGi Runtime</emphasis> - Standalone JBoss OSGi Runtime</listitem>
- <listitem><emphasis role="bold">JBoss OSGi Integration</emphasis> - Integration with an existing JBossAS instance</listitem>
- </itemizedlist>
-
- <para>Next, you will be presented with the choice of supported OSGi Frameworks.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-target-framework.png"/>
- </imageobject>
- </mediaobject>
-
- <para>In case you have selected 'JBoss OSGi Integration', you will be presented with the choice of supported target containers.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-target-container.png"/>
- </imageobject>
- </mediaobject>
-
- <para>You will then have to point the installer to your existing <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> installation.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-jboss-home.jpg"/>
- </imageobject>
- </mediaobject>
-
- <para>You can then verify the selected installation options and proceed with the actual installation.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-verify.png"/>
- </imageobject>
- </mediaobject>
-
- <para>The installer reports its installation progress and finally displays a confirmation screen. You can now optionally generate
- an "automatic installation script" that you can use when you want to repeat what you have just done without user interaction.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-done.png"/>
- </imageobject>
- </mediaobject>
- </sect1>
-
- <sect1 xml:id="SecRuntimeStart">
- <title>Starting the Runtime</title>
-
- <para>If you selected <link linkend="ChapRuntime">JBoss OSGi Runtime</link> during installation you should see a <emphasis role="bold">runtime</emphasis> folder, which contains
- the JBoss OSGi Runtime distribution. The JBoss OSGi Runtime is an OSGi container onto which services and applications can be deployed.</para>
-
- <para>The layout of the JBoss OSGi Runtime after installation is similar to what you know from <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink>.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/izpack-structure.png"/>
- </imageobject>
- </mediaobject>
-
- <para>You can start the Runtime by running <emphasis role="bold">bin/run.sh</emphasis>. The supported command line
- options are:</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">-c (--server-name)</emphasis> - The runtime profile to start.
- The default is the 'default' profile.</listitem>
- <listitem><emphasis role="bold">-b (--bind-address)</emphasis> - The network address various services can bind to.
- The default is 'localhost'</listitem>
- </itemizedlist>
-
- <programlisting>
- [tdiesler at tddell runtime]$ bin/run.sh
- =========================================================================
-
- JBoss OSGi Bootstrap Environment
-
- OSGI_HOME: /home/tdiesler/jboss-osgi-1.0.0.Beta2/runtime
-
- JAVA: /usr/java/jdk1.6/bin/java
-
- JAVA_OPTS: ...
-
- =========================================================================
-
- 16:18:32,974 INFO [FelixIntegration] OSGi Integration Felix - 1.0.0.Beta2
- 16:18:33,403 INFO [FelixIntegration] Installed bundle [1]: org.osgi.compendium
- 16:18:33,412 INFO [FelixIntegration] Installed bundle [2]: org.apache.felix.log
- 16:18:33,425 INFO [FelixIntegration] Installed bundle [3]: jboss-osgi-common
- 16:18:33,435 INFO [FelixIntegration] Installed bundle [4]: jboss-osgi-hotdeploy
- 16:18:33,550 INFO [jboss-osgi-hotdeploy] Start DeploymentScanner: [scandir=server/default/bundles,interval=2000ms]
- 16:18:33,555 INFO [OSGiBootstrap] JBoss OSGi Runtime booted in 0.581sec
- ...
- 16:18:33,617 INFO [jboss-osgi-common] Installed: jboss-osgi-jndi [5]
- 16:18:33,627 INFO [jboss-osgi-common] Installed: jboss-osgi-jmx [6]
- 16:18:33,659 INFO [jboss-osgi-common] Installed: jboss-osgi-common-core [7]
- ...
- 16:18:34,170 INFO [jboss-osgi-jndi] JNDI started: JNP=localhost:1099, RMI=localhost:1098
- 16:18:34,543 INFO [jboss-osgi-jmx] MBeanServerConnection bound to: jmx/invoker/RMIAdaptor
- ...
- <emphasis role="bold">16:18:34,544 INFO [OSGiBootstrap] JBoss OSGi Runtime started in 1.57sec</emphasis>
- </programlisting>
- </sect1>
-
- <sect1 xml:id="SecProvidedExamples">
- <title>Provided Examples</title>
-
- <para>JBoss OSGi comes with a number of examples that you can build and deploy. Each example
- deployment is verified by an accompaning test case</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">HTTP Service</emphasis> - Register servlets and resources with the HTTP Service</listitem>
- <listitem><emphasis role="bold">Log Service</emphasis> - Interact with a local and remote Log Service</listitem>
- <listitem><emphasis role="bold">JMX Service</emphasis> - Register an MBean through the JMX Service</listitem>
- <listitem><emphasis role="bold">JNDI Service</emphasis> - Bind objects to the Naming Service</listitem>
- <listitem><emphasis role="bold">Microcontainer Service</emphasis> - Call a service from an MC bean</listitem>
- </itemizedlist>
-
- <programlisting>
- [tdiesler at tddell example]$ mvn package
- [INFO] ------------------------------------------------------------------------
- [INFO] Building JBoss OSGi - Testsuite Examples
- [INFO] task-segment: [package]
- [INFO] ------------------------------------------------------------------------
- ...
- build-test-jars:
- # example-http (example-http.jar) 4
- # example-jmx (example-jmx.jar) 4
- # example-jndi (example-jndi.jar) 1
- # example-log (example-log.jar) 2
- # example-mcservice-bundleA (example-mcservice-bundleA.jar) 2
- # example-mcservice-bundleB (example-mcservice-bundleB.jar) 3
- ...
- Running org.jboss.test.osgi.example.microcontainer.MicrocontainerTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.418 sec
- Running org.jboss.test.osgi.example.http.HttpServiceTestCase
- Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 5.476 sec
- Running org.jboss.test.osgi.example.log.LogServiceTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.312 sec
- Running org.jboss.test.osgi.example.jndi.JNDITestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.231 sec
- Running org.jboss.test.osgi.example.jmx.JMXTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.517 sec
- </programlisting>
- </sect1>
-
- <sect1 xml:id="SecBundleDeployment">
- <title>Bundle Deployment</title>
-
- <para>Bundle deployment works, as you would probably expect, by dropping your OSGi Bundle into the
- JBoss OSGi Runtime <emphasis role="bold">deploy</emphasis> folder.</para>
-
- <programlisting>
- [tdiesler at tdvaio testsuite]$ cp .../test-libs/example/example-http.jar .../runtime/server/web/deploy
- ...
- 13:59:38,284 INFO [BundleRealDeployer] Installed: example-http [9]
- 13:59:38,289 INFO [example-http] BundleEvent INSTALLED
- 13:59:38,297 INFO [example-http] BundleEvent RESOLVED
- 13:59:38,304 INFO [example-http] ServiceEvent REGISTERED
- 13:59:38,306 INFO [BundleStartStopDeployer] Started: example-http [9]
- 13:59:38,306 INFO [example-http] BundleEvent STARTED
- </programlisting>
- </sect1>
-
- <sect1 xml:id="SecWebConsole">
-
- <title>Managing installed Bundles</title>
-
- <para>JBoss OSGi comes with a simple Web Console, which is currently based on the
- <ulink url="http://felix.apache.org/site/apache-felix-web-console.html">Apache Felix Web Console</ulink> project.
- By default the JBoss OSGi Web Console is available at <ulink url="http://localhost:8090/jboss-osgi">http://localhost:8090/jboss-osgi</ulink>.
- </para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/webconsole.png" contentwidth="450"/>
- </imageobject>
- </mediaobject>
-
- <note>
- <title>TODO: Cleanup and document console provided functionality</title>
- </note>
- </sect1>
-
- <sect1 xml:id="SecHudson">
- <title>Hudson QA Environment</title>
-
- <emphasis role="bold">Setup the Hudson QA Environment</emphasis>
-
- <para>The JBoss OSGi <ulink url="http://jbmuc.dyndns.org:8280/hudson">Hudson QA Environment</ulink> is an integral part of the JBoss OSGi code base.
- It is designed for simplicity because we believe that comprehensive QA will only get done if it is dead simple to do so.</para>
-
- <para>Consequently, you only have to execute two simple ant targets to setup the QA environment that was used to QA the JBoss OSGi
- release that you currently work with.</para>
-
- <para>If in future we should discover a problem with a previous JBoss OSGi release, it will be possible to provide a patch and verify that change using
- the original QA environment for that release.</para>
-
- <para>With every release we test the matrix of supported target containers and JDKs.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/hudson-home.png" contentwidth="450"/>
- </imageobject>
- </mediaobject>
-
- <emphasis role="bold">Set Hudson Properties</emphasis>
-
- <para>You need to set a few properties, especially these</para>
-
- <itemizedlist>
- <listitem>hudson.maven.path</listitem>
- <listitem>hudson.username</listitem>
- <listitem>hudson.password</listitem>
- <listitem>hudson.root</listitem>
- </itemizedlist>
-
- <programlisting>
- cd build/hudson
- cp ant.properties.example ant.properties
- vi ant.properties
-
- # The JBoss settings
- jboss.server.instance=default
- jboss.bind.address=127.0.0.1
-
- # JDK settings
- java.home.jdk15=/usr/java/jdk1.5.0_17
- java.home.jdk16=/usr/java/jdk1.6.0_11
-
- # Hudson QA Environment
- hudson.username=chageme
- hudson.password=chageme
-
- hudson.maven.path=/usr/java/apache-maven-2.0.9
-
- hudson.root=/home/tdiesler/workspace/hudson/jboss-osgi
-
- hudson.maven.profile=$HUDSONDIR/profiles.xml.local.qa
-
- hudson.host=jbpm.dyndns.org
- hudson.admin.port=8250
- hudson.http.port=8280
-
- #hudson.jboss501.zip=file:///home/tdiesler/Download/java/jboss/jboss-5.0.1.GA.zip
-
- hudson.mail.recipients=
- hudson.smtp.host=localhost
-
- # Hudson (1.290)
- apache-tomcat=5.5.20
- sun-hudson=2402/128862
- </programlisting>
-
- <emphasis role="bold">Run Hudson Setup</emphasis>
-
- <programlisting>
- [tdiesler at tdvaio hudson]$ ant hudson-setup
- Buildfile: build.xml
-
- init:
- [echo] V1.0.0.Beta2
-
- init-hudson:
- [echo]
- [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
- [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
- [echo]
-
- ...
-
- hudson-setup:
- [copy] Copying 2 files to /home/.../hudson/jboss-osgi/apache-tomcat
- ...
- [echo]
- [echo] *************************************
- [echo] * Hudson setup successfully *
- [echo] * ant hudson-start *
- [echo] *************************************
- [echo]
- </programlisting>
-
- <emphasis role="bold">Run Hudson Start</emphasis>
-
- <programlisting>
- [tdiesler at tdvaio hudson]$ ant hudson-start
- Buildfile: build.xml
-
- init:
- [echo] V1.0.0.Beta2
-
- init-hudson:
- [echo]
- [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
- [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
- [echo]
-
- hudson-start:
- [echo]
- [echo] *************************************
- [echo] * Hudson started successfully *
- [echo] * http://localhost:8280/hudson *
- [echo] *************************************
- [echo]
-
- BUILD SUCCESSFUL
- </programlisting>
-
- <emphasis role="bold">Run Hudson Stop</emphasis>
-
- <programlisting>
- [tdiesler at tdvaio hudson]$ ant hudson-stop
- Buildfile: build.xml
-
- init:
- [echo] V1.0.0.Beta2
-
- init-hudson:
- [echo]
- [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
- [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
- [echo]
-
- hudson-stop:
- [echo]
- [echo] *************************************
- [echo] * Hudson stopped successfully *
- [echo] * ant hudson-start *
- [echo] *************************************
- [echo]
-
- BUILD SUCCESSFUL
- </programlisting>
- </sect1>
-
-</chapter>
\ No newline at end of file
Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch100-getting-support.xml (from rev 89712, projects/jboss-osgi/trunk/docbook/en/modules/ch90-getting-support.xml)
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch100-getting-support.xml (rev 0)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch100-getting-support.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -0,0 +1,16 @@
+<!--
+ $Id$
+-->
+<chapter xml:id="ChapGettingSupport">
+
+ <title>Getting Support</title>
+
+ <para>We offer free support through the <ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=257">JBoss OSGi User Forum</ulink>.</para>
+
+ <para>Please note, that posts to this forum will be dealt with at the community's leisure.
+ If your business is such that you need to rely on qualified answers within a known time frame,
+ this forum might not be your preferred support channel.</para>
+
+ <para>For professional support please go to <ulink url="http://www.jboss.com/services">JBoss Support Services</ulink>.</para>
+
+</chapter>
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,209 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapRuntime">
-
- <title>JBoss OSGi Runtime</title>
-
- <sect1 xml:id="SecRuntimeOverview">
-
- <title>Overview</title>
-
- <para>Formerly a trimmed down <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> distribution, the
- JBoss OSGi Runtime has now evolved into a pure OSGi container onto which components, services and applications can be deployed.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/jbossosgi-runtime.png"/>
- </imageobject>
- </mediaobject>
-
- <para><link linkend="SecRuntimeProfiles">Preconfigured profiles</link>, contain OSGi bundles
- that logically work together. A profile can be bootstrapped either as a standalone server or embedded in some other environment.
- With a startup time of less than 600ms, the runtime can be easily be bootstrapped from within plain JUnit4 test cases.</para>
-
- <para>The JBoss OSGi Runtime has an integration layer for the underlying OSGi frameworks. It comes with a choice of
- <link linkend="SecIntegrationFelix">Apache Felix</link>, <link linkend="SecIntegrationEquinox">Eclipse Equinox</link> or
- <link linkend="SecIntegrationKnopflerfish">MakeWave Knopflerfish</link>.</para>
-
- <para>Through local and remote management capabilities the JBoss OSGi Runtime can be provisioned with new or updated bundles.
- Similar to <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> it supports hot-deployment by dropping bundles
- into the 'deploy' folder. Management of the runtime is provided through a <link linkend="SecWebConsole">Web Console</link></para>
-
- <para>Integration of the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> as an OSGi service allows you
- to write your applications in a POJO programming model without much "polution" of OSGi specific API - the MC will do the
- wiring for you. Future releases of JBoss OSGi will come with a full implementation of
- <ulink url="http://jbossosgi.blogspot.com/2009/04/osgi-blueprint-service-rfc-124.html">Blueprint Service (RFC-124)</ulink>,
- which standardizes this idea and takes it further.</para>
-
- <para>Great care has been taken about testability of deployed components and services. The <link linkend="ChapHuskyTesting">Husky Test Framework</link>
- allows you to write plain JUnit tests that do not have a requirement on a specific test runner nor need to extend any specific test base class.
- Access to the Runtime has been abstracted sufficiently that you can run the same test case against an embedded (bootstrapped from within the test case)
- as well as a remote instance of the Runtime. You can run your OSGi tests from <ulink url="http://maven.apache.org">Maven</ulink>,
- <ulink url="http://ant.apache.org">Ant</ulink>, <ulink url="http://www.eclipse.org">Eclipse</ulink> or any other test runner that supports JUnit4.</para>
-
- <para>JBoss OSGi Runtime can be installed as a <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> service with abstractions
- of the available OSGi services. The JBoss OSGi testsuite in fact runs the same set of tests against the embedded, standalone and AS integrated
- instance of the Runtime</para>
-
- </sect1>
-
- <sect1 xml:id="SecRuntimeFeatures">
- <title>Features</title>
-
- <para>The current JBoss OSGi Runtime feature set includes</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">Embedded and Standalone usage</emphasis> -
- The runtime can be bootstrapped as standalone container with a startup time of less than 2 sec
- in its default configuration or embedded in some other container environment.</listitem>
-
- <listitem><emphasis role="bold">Various Runtime Profiles</emphasis> -
- It comes with the <link linkend="SecRuntimeProfiles">preconfigured profiles</link> 'Minimal', 'Default', 'Web', 'All'.
- Setting up a new profile is a mater of creating a new directory and putting some bundles in it.</listitem>
-
- <listitem><emphasis role="bold">Hot Deployement</emphasis> -
- Similar to <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> there is a deployment scanner that scans
- the 'deploy' folder for new or removed bundles.</listitem>
-
- <listitem><emphasis role="bold">Multiple OSGi Frameworks</emphasis> -
- The Installer can setup the JBoss OSGi Runtime using <link linkend="SecIntegrationFelix">Felix</link>,
- <link linkend="SecIntegrationEquinox">Equinox</link> or <link linkend="SecIntegrationKnopflerfish">Knopflerfish</link>.
- </listitem>
-
- <listitem><emphasis role="bold">Local and Remote JMX Support</emphasis> -
- There is local as well as remote support for JMX. Similar to <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink>
- the JMXAdaptor (which provides the MBeanServerConnection) is bound to JNDI.
- </listitem>
-
- <listitem><emphasis role="bold">JNDI Support</emphasis> -
- Components can access the JNDI InitialContext as a service from the registry.
- </listitem>
-
- <listitem><emphasis role="bold">SAX/DOM Parser Support</emphasis> -
- The Runtime comes with an implementation of an <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/util/xml/XMLParserActivator.html">XMLParserActivator</ulink>
- which provides access to a SAXParserFactory and DocumentBuilderFactory.
- </listitem>
-
- <listitem><emphasis role="bold">JAXB Support</emphasis> -
- There is a bundle that provides JAXB support.
- </listitem>
-
- <listitem><emphasis role="bold">HttpService Support</emphasis> -
- HttpService support is provided by a customized version of the <ulink url="http://felix.apache.org/site/apache-felix-web-console.html">Apache Felix Web Console</ulink>.
- </listitem>
-
- <listitem><emphasis role="bold">ConfigAdmin Support</emphasis> -
- ConfigAdmin support is provided by the <ulink url="http://felix.apache.org/site/apache-felix-configuration-admin-service.html">Apache Felix Configuration Admin Service</ulink>.
- </listitem>
-
- <listitem><emphasis role="bold">Provisioning</emphasis> -
- Bundle provisioning can be done through the JMX based Runtime Managment Interface.
- </listitem>
-
- <listitem><emphasis role="bold">Logging System</emphasis> -
- The logging bridge writes OSGi LogEntries to the configured logging framework (e.g. Log4J). A local OSGi Runtime can receive LogEntries
- from a remote instance.
- </listitem>
-
- <listitem><emphasis role="bold">Microcontainer Support</emphasis> -
- The <ulink url="http://www.jboss.org/jbossmc">Microcontainer</ulink> service allows bundles to contain a *-beans.xml descriptor,
- which can be used for component wiring and injection of base services. It also comes with a set of <link linkend="SecDeployers">deployers</link>
- - so instead of simply installing a bundle to the underlying OSGi framework it passes to the chain of deployers which each deal with a specific
- aspect of bundle deployment.
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1 xml:id="SecRuntimeProfiles">
- <title>Runtime Profiles</title>
-
- <para>A runtime profile is a collection bundles that logically work together. The OSGi runtime configuration
- contains the list of bundles that are installed/started automatically. You can start create you own profile
- by setting up a new directory with your specific set of bundles.</para>
-
- <note>
- <title>TODO: [JBOSGI-98] Support configuration per profile</title>
- </note>
-
- <para>A runtime profile can be started using the <emphasis role="bold">-c comand line option</emphasis>.</para>
-
- <programlisting>
- [tdiesler at tddell runtime]$ bin/run.sh -c minimal
- =========================================================================
-
- JBossOSGi Bootstrap Environment
-
- OSGI_HOME: /home/tdiesler/jboss-osgi-1.0.0.Beta2/runtime
-
- JAVA: /usr/java/jdk1.6/bin/java
-
- JAVA_OPTS: -Dprogram.name=run.sh ...
-
- =========================================================================
-
- 10:33:13,758 INFO [FelixIntegration] OSGi Integration Felix - 1.0.0.Beta2
- 10:33:14,185 INFO [FelixIntegration] Installed bundle [1]: org.osgi.compendium
- 10:33:14,194 INFO [FelixIntegration] Installed bundle [2]: org.apache.felix.log
- 10:33:14,203 INFO [FelixIntegration] Installed bundle [3]: jboss-osgi-common
- 10:33:14,212 INFO [FelixIntegration] Installed bundle [4]: jboss-osgi-hotdeploy
- 10:33:14,247 INFO [FelixIntegration] Started bundle: org.apache.felix.log
- 10:33:14,315 INFO [FelixIntegration] Started bundle: jboss-osgi-common
- 10:33:14,357 INFO [jboss-osgi-hotdeploy] Start DeploymentScanner: [scandir=.../server/minimal/deploy,interval=2000ms]
- 10:33:14,401 INFO [FelixIntegration] Started bundle: jboss-osgi-hotdeploy
- <emphasis role="bold">10:33:14,403 INFO [OSGiBootstrap] JBossOSGi Runtime booted in 0.644sec</emphasis>
- </programlisting>
-
- <emphasis role="bold">Minimal Profile</emphasis>
-
- <para>The 'minimal' profile provides logging and hot-deployment.</para>
-
- <para>The following bundles are installed:</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">org.osgi.compendium.jar</emphasis> - OSGi compendium API</listitem>
- <listitem><emphasis role="bold">jboss-osgi-common.jar</emphasis> - JBoss OSGi common services</listitem>
- <listitem><emphasis role="bold">org.apache.felix.log.jar</emphasis> - Apache LogService</listitem>
- <listitem><emphasis role="bold">jboss-osgi-hotdeploy.jar</emphasis> - JBoss OSGi hot deployment service</listitem>
- </itemizedlist>
-
- <emphasis role="bold">Default Profile</emphasis>
-
- <para>The 'default' profile extends the 'minimal' profile by JNDI and JMX</para>
-
- <para>These additional bundles are installed:</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">jboss-osgi-common-core.jar</emphasis> - JBoss Common Core functionality</listitem>
- <listitem><emphasis role="bold">jboss-osgi-jmx.jar</emphasis> - JBoss OSGi JMX service</listitem>
- <listitem><emphasis role="bold">jboss-osgi-jndi.jar</emphasis> - JBoss OSGi JNDI service</listitem>
- </itemizedlist>
-
- <emphasis role="bold">Web Profile</emphasis>
-
- <para>The 'web' profile extends the 'default' profile by HttpService and ConfigAdmin</para>
-
- <para>These additional bundles are installed:</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">org.apache.felix.configadmin.jar</emphasis> - Apache ConfigAdmin service</listitem>
- <listitem><emphasis role="bold">org.apache.felix.http.jetty.jar</emphasis> - Apache HttpService</listitem>
- <listitem><emphasis role="bold">jboss-osgi-webconsole.jar</emphasis> - JBoss OSGi Web Console</listitem>
- </itemizedlist>
-
- <emphasis role="bold">All Profile</emphasis>
-
- <para>The 'all' profile extends the 'web' profile by SAX/DOM, JAXB, JBossXB and Microcontainer</para>
-
- <para>These additional bundles are installed:</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">jboss-osgi-apache-xerces.jar</emphasis> - Apache Xerces support</listitem>
- <listitem><emphasis role="bold">jboss-osgi-jaxb.jar</emphasis> - JAXB support</listitem>
- <listitem><emphasis role="bold">jboss-osgi-xml-binding.jar</emphasis> - XML Binding (JBossXB) support</listitem>
- <listitem><emphasis role="bold">jboss-osgi-microcontainer.jar</emphasis> - Microcontainer support</listitem>
- </itemizedlist>
- </sect1>
-
-</chapter>
-
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch30-framework-integration.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch30-framework-integration.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch30-framework-integration.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,221 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapFrameworkIntegration">
-
- <title>Framework Integration</title>
-
- <sect1 xml:id="SecIntegrationFelix">
- <title>Apache Felix Integration</title>
-
- <para>JBoss OSGi provides integration for the <ulink url="http://felix.apache.org">Apache Felix</ulink> OSGi Framework and some
- of its core services</para>
-
- <itemizedlist>
- <listitem><ulink url="http://felix.apache.org/site/apache-felix-log-service.html">Log Service</ulink> - General purpose message logger</listitem>
- <listitem><ulink url="http://felix.apache.org/site/apache-felix-http-service.html">HTTP Service</ulink> - Http access to servlets and resources</listitem>
- <listitem><ulink url="http://felix.apache.org/site/apache-felix-configuration-admin-service.html">Config Admin Service</ulink> - Management of configuration data for configurable components</listitem>
- </itemizedlist>
-
- <para>The Apache Felix integration can be configured through properties in the <link linkend="ChapRuntime">JBoss OSGi Runtime</link>.
- </para>
-
- <programlisting role="XML"><![CDATA[
- cat conf/jboss-osgi-framework.properties
-
- # The OSGiFramework implementation
- org.jboss.osgi.spi.framework.impl=org.jboss.osgi.felix.framework.FelixIntegration
-
- # Properties to configure the Framework
- org.osgi.framework.storage=${osgi.server.home}/data/osgi-store
- org.osgi.framework.storage.clean=onFirstInit
-
- # Hot Deployement
- org.jboss.osgi.hotdeploy.scandir=${osgi.server.home}/bundles
-
- ...
-
- # Bundles that need to be installed with the Framework automatically
- org.jboss.osgi.spi.framework.autoInstall=\
- file://${osgi.home}/server/minimal/bundles/org.osgi.compendium.jar
-
- # Bundles that need to be started automatically
- org.jboss.osgi.spi.framework.autoStart=\
- file://${osgi.home}/server/minimal/bundles/org.apache.felix.log.jar \
- file://${osgi.home}/server/minimal/bundles/jboss-osgi-common.jar \
- file://${osgi.home}/server/minimal/bundles/jboss-osgi-hotdeploy.jar
- ]]></programlisting>
-
- <para>In the <ulink url="http://www.jboss.org/jbossas">JBossAS</ulink> integration we use
- <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> beans configuration.</para>
-
- <programlisting role="XML"><![CDATA[
- cat server/default/deployers/osgi.deployer/META-INF/osgi-deployers-jboss-beans.xml
-
- <deployment xmlns="urn:jboss:bean-deployer:2.0">
-
- <!-- The OSGiFramework -->
- <bean name="jboss.osgi:service=Framework" class="org.jboss.osgi.felix.framework.FelixIntegration">
- <property name="properties">
- ...
- </property>
- <property name="autoStart">
- <list elementClass="java.net.URL">
- ...
- </list>
- </property>
- </bean>
- ...
- </deployment>
- ]]></programlisting>
-
- <para>The following is a description of the configuration properties for the Apache Felix integration.</para>
-
- <table>
- <tr><th>Key</th><th>Value</th><th>Description</th></tr>
- <tr valign="top">
- <td>org.osgi.framework.storage</td>
- <td>.../osgi-store</td>
- <td>OSGi Framework storage area</td>
- </tr>
- <tr valign="top">
- <td>org.osgi.framework.storage.clean</td>
- <td>onFirstInit</td>
- <td>Clean the storage area on first init</td>
- </tr>
- <tr valign="top">
- <td>org.osgi.service.http.port</td>
- <td>8090</td>
- <td>The default Http Service port</td>
- </tr>
- <tr valign="top">
- <td>felix.cm.dir</td>
- <td>.../osgi-configadmin</td>
- <td>Config Admin Service storage area</td>
- </tr>
- <tr valign="top">
- <td>org.osgi.framework.system.packages.extra</td>
- <td>javax.management, javax.xml...</td>
- <td>Packages provided by the OSGi System ClassLoader</td>
- </tr>
- <tr valign="top">
- <td>org.jboss.osgi.deferred.start</td>
- <td>true</td>
- <td>Bundles can be deployed in any order</td>
- </tr>
- </table>
- </sect1>
-
- <sect1 xml:id="SecIntegrationEquinox">
- <title>Equinox Integration</title>
-
- <para>JBoss OSGi also provides basic integration for the <ulink url="http://www.eclipse.org/equinox">Eclpipse Equinox</ulink> OSGi Framework.</para>
-
- <para>Equinox integration can be configured through properties in the <link linkend="ChapRuntime">JBoss OSGi Runtime</link>.</para>
-
- <programlisting role="XML"><![CDATA[
- cat conf/jboss-osgi-framework.properties
-
- # The OSGiFramework implementation
- org.jboss.osgi.spi.framework.impl=org.jboss.osgi.equinox.framework.EquinoxIntegration
-
- # Properties to configure the Framework
- org.osgi.framework.storage=${osgi.server.home}/data/osgi-store
- org.osgi.framework.storage.clean=onFirstInit
-
- # Hot Deployement
- org.jboss.osgi.hotdeploy.scandir=${osgi.server.home}/bundles
-
- ...
-
- # Bundles that need to be installed with the Framework automatically
- org.jboss.osgi.spi.framework.autoInstall=\
- file://${osgi.home}/server/minimal/bundles/org.osgi.compendium.jar
-
- # Bundles that need to be started automatically
- org.jboss.osgi.spi.framework.autoStart=\
- file://${osgi.home}/server/minimal/bundles/org.apache.felix.log.jar \
- file://${osgi.home}/server/minimal/bundles/jboss-osgi-common.jar \
- file://${osgi.home}/server/minimal/bundles/jboss-osgi-hotdeploy.jar
- ]]></programlisting>
-
- <para>In the <ulink url="http://www.jboss.org/jbossas">JBossAS</ulink> integration we use
- <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> beans configuration.</para>
-
- <programlisting role="XML"><![CDATA[
- <deployment xmlns="urn:jboss:bean-deployer:2.0">
-
- <!-- The OSGiFramework -->
- <bean name="jboss.osgi:service=Framework" class="org.jboss.osgi.equinox.framework.EquinoxIntegration">
- <property name="properties">
- ...
- </property>
- <property name="autoStart">
- <list elementClass="java.net.URL">
- ...
- </list>
- </property>
- </bean>
- ...
- </deployment>
- ]]></programlisting>
-
- </sect1>
-
- <sect1 xml:id="SecIntegrationKnopflerfish">
- <title>Knopflerfish Integration</title>
-
- <para>JBoss OSGi provides basic integration for the <ulink url="http://www.knopflerfish.org">Makewave Knopflerfish</ulink> OSGi Framework.</para>
-
- <para>Knopflerfish integration can be configured through properties in the <link linkend="ChapRuntime">JBoss OSGi Runtime</link>.</para>
-
- <programlisting role="XML"><![CDATA[
- cat conf/jboss-osgi-framework.properties
-
- # The OSGiFramework implementation
- org.jboss.osgi.spi.framework.impl=org.jboss.osgi.knopflerfish.framework.KnopflerfishIntegration
-
- # Properties to configure the Framework
- org.osgi.framework.storage=${osgi.server.home}/data/osgi-store
- org.osgi.framework.storage.clean=onFirstInit
-
- # Hot Deployement
- org.jboss.osgi.hotdeploy.scandir=${osgi.server.home}/bundles
-
- ...
-
- # Bundles that need to be installed with the Framework automatically
- org.jboss.osgi.spi.framework.autoInstall=\
- file://${osgi.home}/server/minimal/bundles/org.osgi.compendium.jar
-
- # Bundles that need to be started automatically
- org.jboss.osgi.spi.framework.autoStart=\
- file://${osgi.home}/server/minimal/bundles/org.apache.felix.log.jar \
- file://${osgi.home}/server/minimal/bundles/jboss-osgi-common.jar \
- file://${osgi.home}/server/minimal/bundles/jboss-osgi-hotdeploy.jar
- ]]></programlisting>
-
- <para>In the <ulink url="http://www.jboss.org/jbossas">JBossAS</ulink> integration we use
- <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> beans configuration.</para>
-
- <programlisting role="XML"><![CDATA[
- <deployment xmlns="urn:jboss:bean-deployer:2.0">
-
- <!-- The OSGiFramework -->
- <bean name="jboss.osgi:service=Framework" class="org.jboss.osgi.knopflerfish.KnopflerfishIntegration">
- <property name="properties">
- ...
- </property>
- <property name="autoStart">
- <list elementClass="java.net.URL">
- ...
- </list>
- </property>
- </bean>
- ...
- </deployment>
- ]]></programlisting>
-
- </sect1>
-
-</chapter>
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch40-developer-guide.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch40-developer-guide.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch40-developer-guide.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,366 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapDeveloperGuide">
-
- <title>Developer Documentation</title>
-
- <sect1 xml:id="SecSPI">
- <title>Service Provider Interface</title>
-
- <para>The JBoss OSGi Service Provider Interface (SPI) is the integration point for:</para>
-
- <itemizedlist>
- <listitem>Supported OSGi Frameworks</listitem>
- <listitem>Supported Target Containers</listitem>
- <listitem>Administration, Provisioning and Management</listitem>
- <listitem>Various Provided Services</listitem>
- <listitem>Testing Framework</listitem>
- </itemizedlist>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/jbossosgi-spi.png" contentwidth="450"/>
- </imageobject>
- </mediaobject>
-
- <para>The latest version of the <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc">JBoss OSGi SPI</ulink>
- JavaDoc is published online as part of the JBoss OSGi <ulink url="http://jbmuc.dyndns.org:8280/hudson">Hudson QA Environment</ulink>.</para>
-
- <itemizedlist>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/package-summary.html">org.jboss.osgi.spi</ulink> - Common classes and interfaces.</listitem>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/capability/package-summary.html">org.jboss.osgi.spi.capability</ulink> - Capabilities that can be installed in the OSGi framework.</listitem>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/framework/package-summary.html">org.jboss.osgi.spi.framework</ulink> - Framework integration and bootstrap.</listitem>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/logging/package-summary.html">org.jboss.osgi.spi.logging</ulink> - Support for Bundle logging.</listitem>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/management/package-summary.html">org.jboss.osgi.spi.management</ulink> - Management view on deployed bundles.</listitem>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/service/package-summary.html">org.jboss.osgi.spi.service</ulink> - A collection of SPI provided services.</listitem>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/testing/package-summary.html">org.jboss.osgi.spi.testing</ulink> - OSGi test support classes and interfaces.</listitem>
- </itemizedlist>
-
- <emphasis role="bold">Bootstrapping JBoss OSGi</emphasis>
-
- <para>The OSGiBootstrap provides an OSGiFramework through a OSGiBootstrapProvider.</para>
-
- <para>A OSGiBootstrapProvider is discovered in two stages</para>
-
- <orderedlist>
- <listitem>Read the bootstrap provider class name from a system property</listitem>
- <listitem>Read the bootstrap provider class name from a resource file</listitem>
- </orderedlist>
-
- <para>In both cases the key is the fully qalified name of the <code>org.jboss.osgi.spi.framework.OSGiBootstrapProvider</code> interface.</para>
-
- <para>The following code shows how to get the default <code>OSGiFramework</code> from the <code>OSGiBootstrapProvider</code>.</para>
-
- <programlisting role="JAVA">
- OSGiBootstrapProvider bootProvider = OSGiBootstrap.getBootstrapProvider();
- OSGiFramework framework = bootProvider.getFramework();
- Bundle bundle = framework.getSystemBundle();
- </programlisting>
-
- <para>The <code>OSGiBootstrapProvider</code> can also be configured explicitly. The <code>OSGiFramework</code> is a named
- object from the configuration.</para>
-
- <programlisting role="JAVA">
- OSGiBootstrapProvider bootProvider = OSGiBootstrap.getBootstrapProvider();
- bootProvider.configure(configURL);
-
- OSGiFramework framework = bootProvider.getFramework("AnotherOSGiFramework");
- Bundle bundle = framework.getSystemBundle();
- </programlisting>
-
- <para>The JBoss OSGi SPI comes with two bootstrap providers:</para>
-
- <itemizedlist>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/framework/PropertiesBootstrapProvider.html">PropertiesBootstrapProvider</ulink></listitem>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/framework/MicrocontainerBootstrapProvider.html">MicrocontainerBootstrapProvider</ulink></listitem>
- </itemizedlist>
-
- <para>OSGiBootstrapProvider implementations that read their configurtation from some other source are possible, but currently not
- part of the JBoss OSGi SPI.</para>
-
- <tip>
- <title>Using the SPI from within JBossAS deployed components</title>
- <para>If you need access to the OSGi Framework from within an JBossAS deployed component (e.g. servlet, ejb, mbean) you
- <emphasis role="bold">would not</emphasis> bootstrap JBoss OSGi through the SPI. Instead, you would inject the already bootstrapped
- OSGi Framework instance into your component.</para>
- </tip>
- </sect1>
-
- <sect1 xml:id="SecDeployers">
- <title>Bundle Deployers</title>
-
- <para>JBoss OSGi comes with a number of <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> based deployers. Each deployer
- takes care of a specific aspect of bundle deployment.</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">BundleClassLoaderDeployer</emphasis> - Creates a BundleClassLoader for the deployed Bundle</listitem>
- <listitem><emphasis role="bold">BundleContainedBeansDeployer</emphasis> - Deploy the bundle contained MC beans onto the Kernel</listitem>
- <listitem><emphasis role="bold">BundleManagementDeployer</emphasis> - Register the Bundle as MBean with JMX</listitem>
- <listitem><emphasis role="bold">BundleMetaDataDeployer</emphasis> - Create BundleMetaData from Manifest Headers</listitem>
- <listitem><emphasis role="bold">BundleRealDeployer</emphasis> - Installs the Bundle into the Framework's SystemContext</listitem>
- <listitem><emphasis role="bold">BundleStartStopDeployer</emphasis> - Starts the Bundle when dependencies are resolved</listitem>
- <listitem><emphasis role="bold">BundleStructureDeployer</emphasis> - Determine the structure of a Bundle deployment</listitem>
- </itemizedlist>
-
- <emphasis role="bold">BundleClassLoaderDeployer</emphasis>
-
- <para>The BundleClassLoaderDeployer attaches a ClassLoaderFactory that creates a BundleClassLoader for the deployed Bundle.
- A BundleClassLoader delegates all classloading concerns to the underlying Bundle.</para>
-
- <emphasis role="bold">BundleContainedBeansDeployer</emphasis>
-
- <para>The BundleContainedBeansDeployer is a ComponentDeployer that deployes the MC bean components onto
- the Kernel.</para>
-
- <emphasis role="bold">BundleManagementDeployer</emphasis>
-
- <para>The BundleManagementDeployer registers the Bundle as <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/StandardMBean.html">StandardMBean</ulink> with JMX.
- Please see the section on <link linkend="SecJMXView">Management View</link> for details.</para>
-
- <emphasis role="bold">BundleMetaDataDeployer</emphasis>
-
- <para>The BundleMetaDataDeployer creates the BundleMetaData from Manifest Headers. If the manifest does not contain
- a header named <emphasis role="bold">Bundle-SymbolicName</emphasis> this deployer does nothing. </para>
-
- <emphasis role="bold">BundleRealDeployer</emphasis>
-
- <para>The BundleRealDeployer installs the Bundle into the Framework's SystemContext. Optionally you can configure a list of
- bundle locations that should be skipped and hence not installed. Typically, these bundles are already installed during
- Framework startup.</para>
-
- <para>On undeploy the Bundle gets uninstalled from the Framework's SystemContext.</para>
-
- <emphasis role="bold">BundleStartStopDeployer</emphasis>
-
- <para>The BundleStartStopDeployer currently works in two modes:</para>
-
- <itemizedlist>
- <listitem>deferredStart (default)</listitem>
- <listitem>simpleStart</listitem>
- </itemizedlist>
-
- <para>In mode <emphasis role="bold">deferredStart</emphasis> the Bundle is added to a list of unresolved Bundles, which then get passed
- on to <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/packageadmin/PackageAdmin.html#resolveBundles(org.osgi.framework.Bundle[])"><code>PackageAdmin.resolveBundles(Bundle[])</code></ulink>.
- The deployer then iterates over the unresolved Bundles and only starts those Bundles that are in state
- <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/framework/Bundle.html#RESOLVED"><code>RESOLVED</code></ulink>.
- In this mode Bundles can be deployed in any order and only get started when all their respective dependencies can be resolved.</para>
-
- <para>In mode <emphasis role="bold">simpleStart</emphasis> the deployer attempts to start the Bundle regardless of whether its
- dependencies can get resolved. In case the Bundle has a dependency oin a package that is not yet available, deployment will fail.
- In this mode Bundles must be deployed in the order required to start them.</para>
-
- <para>The start mode is a configurable property on the Framework's SystemContext.</para>
-
- <programlisting role="XML"><![CDATA[
- <!--
- If set to 'true' bundles can be deployed in any order. Deployed bundle will get started when their dependencies can be resolved.
- If set to 'false' bundles must be deployed in the order that is required to start them.
- -->
- <entry><key>org.jboss.osgi.deferred.start</key><value>true</value></entry>
- ]]></programlisting>
-
- <emphasis role="bold">BundleStructureDeployer</emphasis>
-
- <para>The BundleStructureDeployer determines the structure of a Bundle deployment. It ignores all deployments that
- are not top-level or do not have a manifest header named <emphasis role="bold">Bundle-SymbolicName</emphasis></para>
-
- </sect1>
-
- <sect1 xml:id="SecJMXView">
- <title>Management View</title>
-
- <para>JBoss OSGi registers the Framework and every deployed Bundle with the JMX <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServer.html">MBeanServer</ulink>.</para>
-
- <emphasis role="bold">The ManagedFramework</emphasis>
-
- <para>The <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/management/ManagedFrameworkMBean.html">
- ManagedFramework</ulink> gives you access to the MBean views of the deployed Bundles. It is registerd under the name:</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">jboss.osgi:service=ManagedFramework</emphasis></listitem>
- </itemizedlist>
-
- <emphasis role="bold">The ManagedBundle</emphasis>
-
- <para>The <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/management/ManagedBundle.html">
- ManagedBundle</ulink> gives you access to the MBean views of a deployed Bundle. It is registerd under the name:</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">jboss.osgi:bundle=[SymbolicName],id=[BundleId]</emphasis></listitem>
- </itemizedlist>
-
- <emphasis role="bold">Accessing the Management Objects</emphasis>
-
- <para>If you work with the JBoss OSGi Testsuite you get access to the Managed Objects through the JBoss OSGi SPI provided
- <ulink url="http://junit.sourceforge.net/">JUnit</ulink> support package <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/testing/package-summary.html">org.jboss.osgi.spi.testing</ulink>.
- </para>
-
- <para>If you install JBoss OSGi in an already existing JBossAS instance you also get access to the Managed Objects through the JBoss provided
- JMX Console (<ulink url="http://localhost:8080/jmx-console">http://localhost:8080/jmx-console</ulink>).</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/jmx-agent-view.png" contentwidth="450"/>
- </imageobject>
- </mediaobject>
-
- <note>
- <para>The JMX Console is <emphasis role="bold">not part</emphasis> of the <link linkend="ChapRuntime">JBoss OSGi Runtime</link>.</para>
- </note>
- </sect1>
-
- <sect1 xml:id="SecWritingTests">
- <title>Writing Test Cases</title>
-
- <para>JBoss OSGi comes with <ulink url="http://www.junit.org">JUnit</ulink> test support as part of the SPI provided
- <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/testing/package-summary.html">org.jboss.osgi.spi.testing</ulink>
- package. There are two distinct test scenarios that we support:</para>
-
- <itemizedlist>
- <listitem>Embedded OSGi Framework</listitem>
- <listitem>Remote OSGi Framework</listitem>
- </itemizedlist>
-
- <para>The remote scenario can actually be separated again in:</para>
-
- <itemizedlist>
- <listitem>Standalone JBoss OSGi Runtime</listitem>
- <listitem>JBoss OSGi Runtime running in JBossAS</listitem>
- </itemizedlist>
-
- <para>A test case that takes advantage of the SPI provided OSGi runtime abstration would transparently handle these scenarios.</para>
-
- <sect2 xml:id="SecWritingTestsSimpleTestCase">
-
- <title>Simple Test Case</title>
-
- <para>The test case bootstraps the OSGi Runtime, installes/starts the bundle, asserts the bundle state and finally
- shuts down the OSGi Runtime. Please note, this is a plain JUnit4 test case that transparently handles embedded/remote
- nature of the OSGi Runtime.
- </para>
-
- <programlisting role="JAVA">
- public class SimpleTestCase
- {
- @Test
- public void testSimpleBundle() throws Exception
- {
- // Get the default runtime
- OSGiRuntime runtime = new OSGiTestHelper().getDefaultRuntime();
- try
- {
- // Install the bundle
- OSGiBundle bundle = runtime.installBundle("example-simple.jar");
- assertEquals("Bundle installed", Bundle.INSTALLED, bundle.getState());
-
- // Start the bundle
- bundle.start();
- assertEquals("Bundle active", Bundle.ACTIVE, bundle.getState());
-
- // Uninstall the bundle
- bundle.uninstall();
- }
- finally
- {
- // Shutdown the runtime
- runtime.shutdown();
- }
- }
- }
- </programlisting>
-
- <para>To run the test in embedded mode (which is the default) you would execute your test runner like this
- </para>
-
- <programlisting role="JAVA">
- [tdiesler at tddell example]$ mvn -Dtest=SimpleTestCase test
- ...
- Running org.jboss.test.osgi.example.simple.SimpleTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.361 sec
- </programlisting>
-
- <para>To run the test against the remote JBoss OSGi Runtime you would execute your test runner like this
- </para>
-
- <programlisting role="JAVA">
- [tdiesler at tddell example]$ mvn -Dtarget.container=runtime -Dtest=SimpleTestCase test
- ...
- Running org.jboss.test.osgi.example.simple.SimpleTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.303 sec
- </programlisting>
-
- <para>In the runtime console you should see</para>
-
- <programlisting role="JAVA">
- 12:44:30,960 INFO [jboss-osgi-common] Installed: example-simple [8]
- 12:44:31,081 INFO [example-simple] Start: example-simple [8]
- 12:44:31,089 INFO [example-simple] Stop: example-simple [8]
- 12:44:31,095 INFO [jboss-osgi-common] Uninstalled: example-simple [8]
- </programlisting>
-
- <para>Due to classloading restrictions it is not possible to interact with the services that get registered in the OSGi Framework
- directly. Instead, there must be some means for the bundle under test to communicate with the test case that lives outside the
- Framework. The approach of OSGi testing based on remote log messages is covered in
- <ulink url="http://jbossosgi.blogspot.com/2009/04/non-intrusive-osgi-bundle-testing.html">Non intrusive OSGi Bundle Testing</ulink>.</para>
-
- <para>The next section explains how to write a plain JUnit test that is then executed within the OSGi Runtime.</para>
- </sect2>
-
- <sect2 xml:id="SecWritingTestsSimpleHuskyTestCase">
-
- <title>Simple Husky Test Case</title>
-
- <para>The test case does everthing identical to <link linkend="SecWritingTestsSimpleTestCase">SimpleTestCase</link> (setUp and tearDown not shown),
- but only executes the code in the test method when Husky injected the BundleContext.
- </para>
-
- <programlisting role="JAVA">
- public class SimpleHuskyTestCase
- {
- @ProvideContext
- public BundleContext context;
-
- ...
-
- @Test
- public void testSimpleBundle() throws Exception
- {
- // Tell Husky to run this test method within the OSGi Runtime
- if (context == null)
- BridgeFactory.getBridge().run();
-
- // Stop here if the context is not injected
- assumeNotNull(context);
-
- // Get the SimpleService reference
- ServiceReference sref = context.getServiceReference(SimpleService.class.getName());
- assertNotNull("SimpleService Not Null", sref);
-
- // Access the SimpleService
- SimpleService service = (SimpleService)context.getService(sref);
- assertEquals("hello", service.echo("hello"));
- }
- }
- </programlisting>
-
- <para>Running this test is also no different from <link linkend="SecWritingTestsSimpleTestCase">SimpleTestCase</link>.</para>
-
- <para>In the runtime console you should see</para>
-
- <programlisting role="JAVA">
- 13:29:15,924 INFO [jboss-osgi-common] Installed: example-simple-husky [16]
- 13:29:15,972 INFO [example-simple-husky] Start: example-simple-husky [16]
- 13:29:15,981 INFO [jboss-osgi-husky] Test-Package [org.jboss.test.osgi.example.simple] in bundle: example-simple-husky [16]
- 13:29:16,160 INFO [example-simple-husky] echo: hello
- 13:29:16,191 INFO [example-simple-husky] Stop: example-simple-husky [16]
- 13:29:16,196 INFO [jboss-osgi-common] Uninstalled: example-simple-husky [16]
- </programlisting>
-
- <para>To learn more about the magic of the BridgeFactory have a look at <link linkend="ChapHuskyTesting">Husky Test Framework</link>
- which comes next.</para>
- </sect2>
-
- </sect1>
-
-</chapter>
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch50-husky-testing.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch50-husky-testing.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch50-husky-testing.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,29 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapHuskyTesting">
-
- <title>Husky Test Framework</title>
-
- <sect1 xml:id="SecHuskyOverview">
- <title>Overview</title>
-
- <para>[TODO]</para>
-
- </sect1>
-
- <sect1 xml:id="SecHuskyConfiguration">
- <title>Configuration</title>
-
- <para>[TODO]</para>
-
- </sect1>
-
- <sect1 xml:id="SecHuskyWritingTests">
- <title>Writing Husky Tests</title>
-
- <para>[TODO]</para>
-
- </sect1>
-
-</chapter>
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch60-provided-bundles.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch60-provided-bundles.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch60-provided-bundles.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,141 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapProvidedBundles">
-
- <title>Provided Bundles and Services</title>
-
- <sect1 xml:id="SecLoggingService">
- <title>Logging Bridge Service</title>
-
- <para>The JBoss OSGi <emphasis role="bold">jboss-osgi-logging.jar</emphasis> bundle contains a simple Logging Bridge Service to
- <ulink url="http://www.jboss.org/community/docs/DOC-11280">JBoss Logging</ulink>. It registers a trivial LogListener with the
- LogReaderService in case that service is registered with the Framework.</para>
-
- <itemizedlist>
- <listitem><ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListener.html">LogListener</ulink> - Subscribes to LogEntry objects from the LogReaderService</listitem>
- <listitem><ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReaderService.html">LogReaderService</ulink> - Provides methods to retrieve LogEntry objects from the log</listitem>
- </itemizedlist>
-
- <para>The LogReaderService is part of the standard <ulink url="http://www.osgi.org/Download/File?url=/download/r4v41/r4.cmpn.pdf">OSGi
- Compendium Services</ulink>. JBoss OSGi currently uses the <ulink url="http://felix.apache.org/site/apache-felix-log-service.html">Log Service</ulink>
- from <ulink url="http://felix.apache.org">Apache Felix</ulink>, which gets deployed as Bundle <emphasis role="bold">org.apache.felix.log.jar</emphasis>
- </para>
-
- <para>The LogListener itself logs messages under the Bundle's symbolic name.</para>
-
- <programlisting role="JAVA">
- public class JBossLoggingLogListener implements LogListener
- {
- public void logged(LogEntry entry)
- {
- Bundle bundle = entry.getBundle();
- int level = entry.getLevel();
- Throwable throwable = entry.getException();
-
- String loggerName = bundle.getSymbolicName();
- Logger log = Logger.getLogger(loggerName);
-
- if (level == LogService.LOG_DEBUG)
- log.debug(entry.getMessage(), throwable);
-
- else if (level == LogService.LOG_INFO)
- log.info(entry.getMessage(), throwable);
-
- else if (level == LogService.LOG_WARNING)
- log.warn(entry.getMessage(), throwable);
-
- else if (level == LogService.LOG_ERROR)
- log.error(entry.getMessage(), throwable);
- }
- }
- </programlisting>
-
- <para>You can therefore change the logging for specific Bundles by
- <ulink url="http://www.jboss.org/community/docs/DOC-12490">setting the respective logging level</ulink>.</para>
- </sect1>
-
- <sect1 xml:id="SecRemoteLogService">
- <title>Remote Log Service</title>
-
- <para>The JBoss OSGi <emphasis role="bold">jboss-osgi-remotelog.jar</emphasis> bundle contains a client side
- <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReaderService.html">RemoteLogReaderService</ulink> that remotely
- communicates with a server side <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListener.html">LogListener</ulink>.
- </para>
-
- <para>The Remote Log Service is configured with these properties.</para>
-
- <table>
- <tr><th>Key</th><th>Value</th><th>Description</th></tr>
- <tr valign="top">
- <td>org.jboss.osgi.service.remote.log.sender</td>
- <td>true/false</td>
- <td>Enable the server side LogListener</td>
- </tr>
- <tr valign="top">
- <td>org.jboss.osgi.service.remote.log.reader</td>
- <td>true/false</td>
- <td>Enable the client side LogReaderService</td>
- </tr>
- <tr valign="top">
- <td>org.jboss.osgi.service.remote.log.host</td>
- <td>localhost</td>
- <td>The remote host that log messages are sent to</td>
- </tr>
- <tr valign="top">
- <td>org.jboss.osgi.service.remote.log.port</td>
- <td>5400</td>
- <td>The remote port that log messages are sent to</td>
- </tr>
- </table>
-
- <para>On the client side you can install an arbitrary <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListener.html">LogListener</ulink>
- with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReaderService.html">RemoteLogReaderService</ulink>. The testsuite typically
- installs an <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/ws/jboss-osgi/spi/target/apidocs/org/jboss/osgi/spi/logging/LogEntryCache.html">LogEntryCache</ulink>
- that filters the received log messages.</para>
-
- <programlisting role="JAVA">
- LogEntryCache logEntryCache = new LogEntryCache();
- logEntryCache.addFilter(new LogEntryFilter("example-log(.*)", LogService.LOG_INFO, "\\[ServiceA\\](.*)"));
-
- // Track the RemoteLogReaderService to add the LogEntryCache as LogListener
- ServiceTracker tracker = new ServiceTracker(sysContext, RemoteLogReaderService.class.getName(), null)
- {
- @Override
- public Object addingService(ServiceReference sref)
- {
- LogReaderService service = (LogReaderService)super.addingService(sref);
- service.addLogListener(logEntryCache);
- return service;
- }
- };
- tracker.open();
- </programlisting>
- </sect1>
-
- <sect1 xml:id="SecMicrocontainerService">
- <title>Microcontainer Service</title>
-
- <para>JBoss OSGi SPI comes with a service that give access to the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> Kernel
- and the JMX <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServer.html">MBeanServer</ulink>. The service is
- registered with the Framework under the name</para>
-
- <itemizedlist>
- <listitem><emphasis role="bold">org.jboss.osgi.service.MicrocontainerService</emphasis></listitem>
- </itemizedlist>
-
- <para>Here is an example of how an OSGi component can register an arbitrary MBean with the
- <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServer.html">MBeanServer</ulink>.</para>
-
- <programlisting role="JAVA">
- ServiceReference sref = context.getServiceReference(MicrocontainerService.class.getName());
- if (sref == null)
- throw new IllegalStateException("MicrocontainerService not registered");
-
- MicrocontainerService mcService = (MicrocontainerService)context.getService(sref);
- MBeanServer mbeanServer = mcService.getMbeanServer();
- mbeanServer.registerMBean(new Foo(), OBJECT_NAME);
- </programlisting>
- </sect1>
-
-</chapter>
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch70-provided-examples.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch70-provided-examples.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch70-provided-examples.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,165 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapProvidedExamples">
-
- <title>Provided Examples</title>
-
- <sect1 xml:id="SecBuildAndRunExamples">
- <title>Building the Examples</title>
-
- <para>JBoss OSGi comes with a number of examples that demonstrate supported functionality
- and show best practices. All examples are part of the binary distribution and tightly
- integrated in our <ulink url="http://www.jboss.org/community/docs/DOC-13275">Maven Build Process</ulink>
- and <ulink url="http://www.jboss.org/community/docs/DOC-13420">Hudson QA Environment</ulink>.</para>
-
- <para>The examples can be either run against a local embedded OSGi Framework or against
- a remote OSGi Runtime instance. Here is how you build and run the against the embedded OSGi Framework.</para>
-
- <programlisting>
- /home/yourname/jboss-osgi-1.0.0.Beta1/example
- [tdiesler at tddell example]$ mvn test
- ...
- [INFO] ------------------------------------------------------------------------
- [INFO] Building JBoss OSGi - Testsuite Examples
- [INFO] task-segment: [test]
- [INFO] ------------------------------------------------------------------------
- ...
- build-example-jars:
- # example-log (example-log.jar) 2
- # example-http (example-http.jar) 4
- # example-microcontainer (example-microcontainer.jar) 4
- ...
- -------------------------------------------------------
- T E S T S
- -------------------------------------------------------
- Running org.jboss.test.osgi.example.log.LogServiceTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.876 sec
- ...
- [INFO] ------------------------------------------------------------------------
- [INFO] BUILD SUCCESSFUL
- [INFO] ------------------------------------------------------------------------
- [INFO] Total time: 17 seconds
- [INFO] Finished at: Tue Apr 21 14:32:31 CEST 2009
- [INFO] Final Memory: 21M/51M
- [INFO] ------------------------------------------------------------------------
- </programlisting>
-
- <para>To run the examples against a remote OSGi Runtime, you need to provide the
- host theat the runtime binds to. This can be done with the
- <emphasis role="bold">-Djboss.bind.address=localhost</emphasis> property.</para>
-
- <programlisting>
- /home/yourname/jboss-osgi-1.0.0.Beta1/example
- [tdiesler at tddell example]$ mvn -Djboss.bind.address=localhost test
- ...
- [INFO] ------------------------------------------------------------------------
- [INFO] Building JBoss OSGi - Testsuite Examples
- [INFO] task-segment: [test]
- [INFO] ------------------------------------------------------------------------
- ...
- build-example-jars:
- # example-log (example-log.jar) 2
- # example-http (example-http.jar) 4
- # example-microcontainer (example-microcontainer.jar) 4
- ...
- -------------------------------------------------------
- T E S T S
- -------------------------------------------------------
- Running org.jboss.test.osgi.example.http.HttpServiceRemoteTestCase
- Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.435 sec
- Running org.jboss.test.osgi.example.log.LogServiceTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.06 sec
- Running org.jboss.test.osgi.example.microcontainer.MBeanServiceRemoteTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.177 sec
- Running org.jboss.test.osgi.example.log.LogServiceRemoteTestCase
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.632 sec
- ...
- [INFO] ------------------------------------------------------------------------
- [INFO] BUILD SUCCESSFUL
- [INFO] ------------------------------------------------------------------------
- [INFO] Total time: 29 seconds
- [INFO] Finished at: Tue Apr 21 14:47:33 CEST 2009
- [INFO] Final Memory: 44M/82M
- [INFO] ------------------------------------------------------------------------
- </programlisting>
- </sect1>
-
- <sect1 xml:id="SecHTTPServiceExample">
- <title>HTTP Service Example</title>
-
- <para>The <emphasis role="bold">example-http.jar</emphasis> bundle contains a Service
- that registeres a servlet and a resource with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/http/HttpService.html">HttpService</ulink>.
- </para>
-
- <programlisting role="JAVA">
- ServiceTracker tracker = new ServiceTracker(context, HttpService.class.getName(), null);
- tracker.open();
-
- HttpService httpService = (HttpService)tracker.getService();
- if (httpService == null)
- throw new IllegalStateException("HttpService not registered");
-
- Properties initParams = new Properties();
- initParams.setProperty("initProp", "SomeValue");
- httpService.registerServlet("/servlet", new EndpointServlet(context), initParams, null);
- httpService.registerResources("/file", "/res", null);
- </programlisting>
-
- <para>The test then verifies that the registered servlet context and the registered resource can be accessed.</para>
- </sect1>
-
- <sect1 xml:id="SecLogServiceExample">
- <title>Log Service Example</title>
-
- <para>The <emphasis role="bold">example-log.jar</emphasis> bundle contains a Service
- that logs messages to the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogService.html">LogService</ulink>.
-
- </para>
-
- <programlisting role="JAVA">
- public ServiceA(BundleContext context)
- {
- log = new LogServiceTracker(context);
- log.log(LOG_INFO, "[ServiceA] new Service");
- }
- </programlisting>
-
- <para>The test then filters and verifies the log messages.</para>
-
- <programlisting role="JAVA">
- LogEntryCache logEntryCache = new LogEntryCache();
- logEntryCache.addFilter(new LogEntryFilter(null, 0, "\\[ServiceA\\](.*)"));
- startLogEntryTracking(logEntryCache);
-
- // Verify the received log entries
- List entries = logEntryCache.getLog();
- assertEquals("Number of entries", 1, entries.size());
- assertEquals("[ServiceA] new Service", entries.get(0).getMessage());
- </programlisting>
-
- <para>The test is available both for embedded and remote LogService testing.</para>
- </sect1>
-
- <sect1 xml:id="SecMicrocontainerServiceExample">
- <title>MC Service Example</title>
-
- <para>The <emphasis role="bold">example-microcontainer.jar</emphasis> bundle contains a Service
- that registers an MBean with the <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanServer.html">MBeanServer</ulink>.
- </para>
-
- <programlisting role="JAVA">
- MicrocontainerService service = (MicrocontainerService)tracker.getService();
- mbeanServer = mcService.getMbeanServer();
- mbeanServer.registerMBean(new Foo(), OBJECT_NAME);
- </programlisting>
-
- <para>The test then accesses the registered MBean.</para>
-
- <programlisting role="JAVA">
- FooMBean foo = (FooMBean)MBeanProxy.get(FooMBean.class, OBJECT_NAME, getServer());
- assertEquals("hello", foo.echo("hello"));
- </programlisting>
- </sect1>
-
-</chapter>
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch80-references.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch80-references.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch80-references.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,27 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapReferences">
-
- <title>References</title>
-
- <para><emphasis role="bold">Resources</emphasis></para>
-
- <itemizedlist>
- <listitem><ulink url="http://www.jboss.org/community/wiki/JBoss OSGi">JBoss OSGi Wiki</ulink></listitem>
- <listitem><ulink url="http://jbossosgi.blogspot.com">JBoss OSGi Diary (Blog)</ulink></listitem>
- <listitem><ulink url="https://jira.jboss.org/jira/browse/JBOSGI">Issue Tracking</ulink></listitem>
- <listitem><ulink url="http://jbmuc.dyndns.org:8280/hudson">Hudson QA</ulink></listitem>
- <listitem><ulink url="https://anonsvn.jboss.org/repos/jbossas/projects/jboss-osgi">Subversion</ulink></listitem>
- <listitem><ulink url="http://fisheye.jboss.com/browse/JBoss OSGi">Fisheye</ulink></listitem>
- <listitem><ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=257">User Forum</ulink></listitem>
- <listitem><ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=256">Design Forum</ulink></listitem>
- </itemizedlist>
-
- <para><emphasis role="bold">Authors</emphasis></para>
-
- <itemizedlist>
- <listitem><ulink url="email:thomas.diesler at jboss.com">Thomas Diesler</ulink></listitem>
- </itemizedlist>
-
-</chapter>
Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch90-getting-support.xml
===================================================================
--- projects/jboss-osgi/trunk/docbook/en/modules/ch90-getting-support.xml 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/docbook/en/modules/ch90-getting-support.xml 2009-06-03 12:09:49 UTC (rev 89724)
@@ -1,16 +0,0 @@
-<!--
- $Id$
--->
-<chapter xml:id="ChapGettingSupport">
-
- <title>Getting Support</title>
-
- <para>We offer free support through the <ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=257">JBoss OSGi User Forum</ulink>.</para>
-
- <para>Please note, that posts to this forum will be dealt with at the community's leisure.
- If your business is such that you need to rely on qualified answers within a known time frame,
- this forum might not be your preferred support channel.</para>
-
- <para>For professional support please go to <ulink url="http://www.jboss.com/services">JBoss Support Services</ulink>.</para>
-
-</chapter>
Modified: projects/jboss-osgi/trunk/testsuite/example/src/test/java/org/jboss/test/osgi/example/simple/SimpleHuskyTestCase.java
===================================================================
--- projects/jboss-osgi/trunk/testsuite/example/src/test/java/org/jboss/test/osgi/example/simple/SimpleHuskyTestCase.java 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/testsuite/example/src/test/java/org/jboss/test/osgi/example/simple/SimpleHuskyTestCase.java 2009-06-03 12:09:49 UTC (rev 89724)
@@ -25,6 +25,7 @@
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
import static org.junit.Assume.assumeNotNull;
import org.jboss.osgi.husky.BridgeFactory;
@@ -43,7 +44,8 @@
import org.osgi.framework.ServiceReference;
/**
- * A test that deployes a bundle and verifies its state
+ * A test that deployes a bundle and accesses
+ * a service from within the test case
*
* @author thomas.diesler at jboss.com
* @since 12-Feb-2009
@@ -67,7 +69,7 @@
// Install the bundle
bundle = runtime.installBundle("example-simple-husky.jar");
- assertEquals("Bundle installed", Bundle.INSTALLED, bundle.getState());
+ assertTrue("Bundle installed", (Bundle.INSTALLED & bundle.getState()) > 0);
// Start the bundle
bundle.start();
Modified: projects/jboss-osgi/trunk/testsuite/example/src/test/java/org/jboss/test/osgi/example/simple/SimpleTestCase.java
===================================================================
--- projects/jboss-osgi/trunk/testsuite/example/src/test/java/org/jboss/test/osgi/example/simple/SimpleTestCase.java 2009-06-03 11:52:41 UTC (rev 89723)
+++ projects/jboss-osgi/trunk/testsuite/example/src/test/java/org/jboss/test/osgi/example/simple/SimpleTestCase.java 2009-06-03 12:09:49 UTC (rev 89724)
@@ -24,6 +24,7 @@
//$Id$
import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
import org.jboss.osgi.spi.testing.OSGiBundle;
import org.jboss.osgi.spi.testing.OSGiRuntime;
@@ -49,7 +50,7 @@
{
// Install the bundle
OSGiBundle bundle = runtime.installBundle("example-simple.jar");
- assertEquals("Bundle installed", Bundle.INSTALLED, bundle.getState());
+ assertTrue("Bundle installed", (Bundle.INSTALLED & bundle.getState()) > 0);
// Start the bundle
bundle.start();
More information about the jboss-cvs-commits
mailing list