[jboss-osgi-commits] JBoss-OSGI SVN: r89711 - in projects/jboss-osgi/trunk/docbook: en/images and 2 other directories.

Author: thomas.diesler(a)jboss.com Date: 2009-06-03 02:55:36 -0400 (Wed, 03 Jun 2009) New Revision: 89711 Added: 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 Removed: projects/jboss-osgi/trunk/docbook/en/modules/ch01-introduction.xml projects/jboss-osgi/trunk/docbook/en/modules/ch02-getting-started.xml projects/jboss-osgi/trunk/docbook/en/modules/ch03-framework-integration.xml projects/jboss-osgi/trunk/docbook/en/modules/ch04-developer-guide.xml projects/jboss-osgi/trunk/docbook/en/modules/ch05-husky-testing.xml projects/jboss-osgi/trunk/docbook/en/modules/ch06-provided-bundles.xml projects/jboss-osgi/trunk/docbook/en/modules/ch07-provided-examples.xml projects/jboss-osgi/trunk/docbook/en/modules/ch08-references.xml projects/jboss-osgi/trunk/docbook/en/modules/ch09-getting-support.xml Modified: projects/jboss-osgi/trunk/docbook/en/images/jbossosgi-runtime.png projects/jboss-osgi/trunk/docbook/en/master.xml projects/jboss-osgi/trunk/docbook/src/main/graphics/jbossosgi-runtime.odp Log: More userguide - WIP Modified: projects/jboss-osgi/trunk/docbook/en/images/jbossosgi-runtime.png =================================================================== (Binary files differ) Modified: projects/jboss-osgi/trunk/docbook/en/master.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/master.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/master.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -10,14 +10,15 @@ <toc/> - <xi:include href="modules/ch01-introduction.xml"/> - <xi:include href="modules/ch02-getting-started.xml"/> - <xi:include href="modules/ch03-framework-integration.xml"/> - <xi:include href="modules/ch04-developer-guide.xml"/> - <xi:include href="modules/ch05-husky-testing.xml"/> - <xi:include href="modules/ch06-provided-bundles.xml"/> - <xi:include href="modules/ch07-provided-examples.xml"/> - <xi:include href="modules/ch08-references.xml"/> - <xi:include href="modules/ch09-getting-support.xml"/> + <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"/> </book> \ No newline at end of file Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch00-introduction.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch01-introduction.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch00-introduction.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch00-introduction.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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> Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch01-introduction.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch01-introduction.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch01-introduction.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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">JBossOSGi 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> Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch02-getting-started.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch02-getting-started.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch02-getting-started.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -1,462 +0,0 @@ -<!-- - $Id$ ---> -<chapter xml:id="ChapGettingStarted"> - - <title>Getting Started</title> - - <para>This chapter takes you through the first steps of getting JBossOSGi and - provides the initial pointers to get up and running.</para> - - <sect1 xml:id="SecInstall"> - <title>Installing JBossOSGi</title> - - <para>JBossOSGi is distributed as an <ulink url="http://izpack.org">IzPack</ulink> installer archive. - The installer is available from the JBossOSGi <ulink url="https://sourceforge.net/project/showfiles.php?group_id=22866&am... area</ulink>.</para> - - <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 JBossOSGi distribution. This is the directory where you find the binary build artifacts, - the java sources, documentation and the JBossOSGi 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">JBossOSGi Distribution</emphasis> - Documentation, Binary Artifacts and Sources</listitem> - <listitem><emphasis role="bold">JBossOSGi Runtime</emphasis> - Standalone JBossOSGi Runtime based on JBossAS</listitem> - <listitem><emphasis role="bold">JBossOSGi 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 'JBossOSGi 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="SecRuntime"> - <title>JBossOSGi Runtime</title> - - <para>If you selected 'JBossOSGi Runtime' during installation you should see a <emphasis role="bold">runtime</emphasis> folder, which contains - the JBossOSGi Runtime distribution. Formerly a trimmed down <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> distribution, the - JBossOSGi Runtime has now evolved into a pure OSGi container onto which services and applications can be deployed.</para> - - <mediaobject> - <imageobject> - <imagedata fileref="images/jbossosgi-runtime.png"/> - </imageobject> - </mediaobject> - - <para>The current JBossOSGi 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 various preconfigured profiles <link linkend="SecRuntimeProfileMinimal">Minimal</link>, - <link linkend="SecRuntimeProfileDefault">Default</link>, <link linkend="SecRuntimeProfileWeb">Web</link>, - <link linkend="SecRuntimeProfileWeb">All</link> which are explained in detail below. 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 JBossOSGi 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 <ulink url="http://java.sun.com/javase/6/docs/technotes/guides/jmx">... Management Extensions (JMX)</ulink>. - Similar to <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink> the JMXAdaptor which provides the - <ulink url="http://java.sun.com/javase/6/docs/api/javax/management/MBeanSer... is bound to JNDI. - </listitem> - - <listitem><emphasis role="bold">JNDI Support</emphasis> - - - Components can access the <ulink url="http://java.sun.com/javase/6/docs/technotes/guides/jndi"&g... Naming and Directory Interface</ulink> - 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/XMLParserAc... - which provides access to a <ulink url="http://java.sun.com/javase/6/docs/api/javax/xml/parsers/SAXPars... and - <ulink url="http://java.sun.com/javase/6/docs/api/javax/xml/parsers/Documen... - </listitem> - - <listitem><emphasis role="bold">JAXB Support</emphasis> - - - There is a bundle that provides initial <ulink url="https://jaxb.dev.java.net">JAXB</ulink> support. - </listitem> - - <listitem><emphasis role="bold">HttpService Support</emphasis> - [TODO]</listitem> - <listitem><emphasis role="bold">ConfigAdmin Support</emphasis> - [TODO]</listitem> - <listitem><emphasis role="bold">Provisioning</emphasis> - [TODO]</listitem> - <listitem><emphasis role="bold">Logging System</emphasis> - [TODO]</listitem> - <listitem><emphasis role="bold">Microcontainer Support</emphasis> - [TODO]</listitem> - </itemizedlist> - - <para>The layout of the JBossOSGi Runtime after installation is similar to what you know from <ulink url="http://http://jboss.org/jbossas">JBossAS</ulink>.... - - <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 (--profile-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@tddell runtime]$ bin/run.sh - ========================================================================= - - JBossOSGi 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] JBossOSGi 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] JBossOSGi Runtime started in 1.57sec</emphasis> - </programlisting> - - <sect2 xml:id="SecRuntimeProfileMinimal"> - <title>Minimal Profile</title> - <para>[TODO]</para> - </sect2> - - <sect2 xml:id="SecRuntimeProfileDefault"> - <title>Default Profile</title> - <para>[TODO]</para> - </sect2> - - <sect2 xml:id="SecRuntimeProfileWeb"> - <title>Web Profile</title> - <para>[TODO]</para> - </sect2> - - <sect2 xml:id="SecRuntimeProfileAll"> - <title>All Profile</title> - <para>[TODO]</para> - </sect2> - - <emphasis role="bold">Provided Examples</emphasis> - - <para>JBossOSGi 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@tddell example]$ mvn package - [INFO] ------------------------------------------------------------------------ - [INFO] Building JBossOSGi - 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> - - <emphasis role="bold">Bundle Deployment</emphasis> - - <para>Bundle deployment works, as you would probably expect, by dropping your OSGi Bundle into the - JBossOSGi Runtime <emphasis role="bold">deploy</emphasis> folder.</para> - - <programlisting> - [tdiesler@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> - - <emphasis role="bold">Managing installed Bundles</emphasis> - - <para>JBossOSGi comes with a simple Web Console, which is currently based on the - <ulink url="http://felix.apache.org/site/apache-felix-web-console.html"... Felix Web Console</ulink> project. - By default the JBossOSGi 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 JBossOSGi <ulink url="http://jbmuc.dyndns.org:8280/hudson">Hudson QA Environment</ulink> is an integral part of the JBossOSGi 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 JBossOSGi - release that you currently work with.</para> - - <para>If in future we should discover a problem with a previous JBossOSGi 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@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@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@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 Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch03-framework-integration.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch03-framework-integration.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch03-framework-integration.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -1,221 +0,0 @@ -<!-- - $Id$ ---> -<chapter xml:id="ChapFrameworkIntegration"> - - <title>Framework Integration</title> - - <sect1 xml:id="SecIntegrationFelix"> - <title>Apache Felix Integration</title> - - <para>JBossOSGi 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"... Service</ulink> - General purpose message logger</listitem> - <listitem><ulink url="http://felix.apache.org/site/apache-felix-http-service.html&quo... Service</ulink> - Http access to servlets and resources</listitem> - <listitem><ulink url="http://felix.apache.org/site/apache-felix-configuration-admin-s... 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="SecRuntime">JBossOSGi 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>JBossOSGi 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="SecRuntime">JBossOSGi 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>JBossOSGi 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="SecRuntime">JBossOSGi 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/ch04-developer-guide.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch04-developer-guide.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch04-developer-guide.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -1,400 +0,0 @@ -<!-- - $Id$ ---> -<chapter xml:id="ChapDeveloperGuide"> - - <title>Developer Documentation</title> - - <sect1 xml:id="SecSPI"> - <title>Service Provider Interface</title> - - <para>The JBossOSGi Service Provider Interface (SPI) is the integration point between the supported OSGi Frameworks and - the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink>. The configuration defines MC beans for the - framework itself and its associated deployers.</para> - - <mediaobject> - <imageobject> - <imagedata fileref="images/jboss-osgi.png" contentwidth="450"/> - </imageobject> - </mediaobject> - - <para>The latest version of the <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc">JBossOSGi SPI</ulink> - JavaDoc is published online as part of the JBossOSGi <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/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/junit/package-summary.html">org.jboss.osgi.spi.junit</ulink> - JUnit test integration.</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/microcontainer/package-summary.html">org.jboss.osgi.spi.service.microcontainer</ulink> - Access to the Kernel and MBeanServer.</listitem> - </itemizedlist> - - <emphasis role="bold">Bootstrapping JBossOSGi</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 JBossOSGi SPI comes with a OSGiBootstrapProvider that uses a <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> - bean 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.felix.framework.FelixIntegration"> - <property name="felixProperties"> - <map keyClass="java.lang.String" valueClass="java.lang.String"> - <entry><key>org.osgi.framework.storage.clean</key><value>onFirstInit</value></entry> - <entry> - <key>org.osgi.framework.system.packages</key> - <value> - org.osgi.framework; version=1.4, - org.osgi.util.tracker - </value> - </entry> - </map> - </property> - </bean> - - ... - - </deployment> - ]]></programlisting> - - <para>OSGiBootstrapProvider implementations that read their configurtation from some other source are possible, but currently not - part of the JBossOSGi 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 JBossOSGi 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>JBossOSGi 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">BundleMetaDataDeployer</emphasis> - Create BundleMetaData from Manifest Headers</listitem> - <listitem><emphasis role="bold">BundleStructureDeployer</emphasis> - Determine the structure of a Bundle deployment</listitem> - <listitem><emphasis role="bold">BundleRealDeployer</emphasis> - Installs the Bundle into the Framework's SystemContext</listitem> - <listitem><emphasis role="bold">BundleClassLoaderDeployer</emphasis> - Creates a BundleClassLoader for the deployed Bundle</listitem> - <listitem><emphasis role="bold">BundleStartStopDeployer</emphasis> - Starts the Bundle when dependencies are resolved</listitem> - <listitem><emphasis role="bold">BundleManagementDeployer</emphasis> - Register the Bundle as MBean with JMX</listitem> - </itemizedlist> - - <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">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> - - <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">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">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...;. - 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.htm...;. - 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">BundleManagementDeployer</emphasis> - - <para>The BundleManagementDeployer registers the Bundle as <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/Standa... with JMX. - Please see the section on <link linkend="SecJMXView">Management View</link> for details.</para> - - </sect1> - - <sect1 xml:id="SecJMXView"> - <title>Management View</title> - - <para>JBossOSGi registers the Framework and every deployed Bundle with the JMX <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/MBeanS... - - <emphasis role="bold">The ManagedFramework</emphasis> - - <para>The <code>ManagedFramework</code> 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> - - <programlisting role="JAVA"> - public interface ManagedFrameworkMBean - { - /** - * Get the list of all installed bundles - */ - Set&lt;ObjectName> getBundles(); - - /** - * Get the installed bundle - */ - ObjectName getBundle(String symbolicName); - } - </programlisting> - - <emphasis role="bold">The ManagedBundle</emphasis> - - <para>The <code>ManagedBundle</code> 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> - - <programlisting role="JAVA"> - public interface ManagedBundleMBean - { - /** - * Returns this bundle's current state. - * A bundle can be in only one state at any time. - * - * @return An element of UNINSTALLED,INSTALLED, RESOLVED,STARTING, STOPPING,ACTIVE. - */ - int getState(); - - /** - * Get the bundles object name. - */ - ObjectName getObjectName(); - - /** - * Returns this bundle's unique identifier. - */ - long getBundleId(); - - /** - * Returns the symbolic name of this bundle as specified by its Bundle-SymbolicName manifest header - */ - String getSymbolicName(); - - /** - * Returns the value of the specified property from the BundleContext. - */ - String getProperty(String key); - - /** - * Starts this bundle with no options - */ - void start() throws BundleException; - - /** - * Stops this bundle with no options. - */ - void stop() throws BundleException; - } - </programlisting> - - <emphasis role="bold">Accessing the Management Objects</emphasis> - - <para>If you work with the JBossOSGi Testsuite you get access to the Managed Objects through the JBossOSGi 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/junit/package-summary.html">org.jboss.osgi.spi.junit</ulink>. - </para> - - <para>If you install JBossOSGi 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="SecRuntime">JBossOSGi Runtime</link>.</para> - </note> - </sect1> - - <sect1 xml:id="SecWritingTests"> - <title>Writing Testcases</title> - - <para>JBossOSGi 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/junit/package-summary.html">org.jboss.osgi.spi.junit</ulink> - package. There are two distinct test scenarios that we support</para> - - <itemizedlist> - <listitem>Embedded OSGi Framework</listitem> - <listitem>Remote OSGi Framework</listitem> - </itemizedlist> - - <emphasis role="bold">Testing an embedded OSGi Framework</emphasis> - - <para>In the embedded scenario the testcase bootstraps the OSGi Framework and installes and tests the bundles locally. The base class for - embedded OSGi testing is <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/junit/OSGiTest.html">org.jboss.osgi.spi.junit.OSGiTest</ulink>. - </para> - - <programlisting role="JAVA"> - public class EmbeddedTestCase extends OSGiTest - { - public void testSomeBundle() throws Exception - { - // Bootstrap the Framework and get the system bundle - OSGiFramework framework = getBootstrapProvider().getFramework(); - BundleContext sysContext = framework.getSystemBundleContext(); - - // Install and start the test bundle - Bundle bundleA = installBundle(sysContext, "some-bundle.jar", true); - - // Verify that the bundle is active - assertEquals("Test bundle ACTIVE", Bundle.ACTIVE, bundleA.getState()); - } - } - </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. We use an approach where the test case registeres a <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListe... - with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReade...;. Log messages are filtered and - can be verified by the test case. For this to work certain conditions must be true:</para> - - <itemizedlist> - <listitem>The Framework must have a LogService installed</listitem> - <listitem>The bundle under test must write log messages to LogService</listitem> - <listitem>The LogListener must be seen by the classloader that loads the test case</listitem> - </itemizedlist> - - <programlisting role="JAVA"> - // Setup log entry tracking - LogEntryCache logEntryCache = new LogEntryCache(); - logEntryCache.addFilter(new LogEntryFilter("example-log(.*)", LogService.LOG_INFO, "\\[ServiceA\\](.*)")); - - // Start log entry tracking - startLogEntryTracking(logEntryCache); - - // do stuff - - // Verify the received log entries - List entries = logEntryCache.getLog(); - assertEquals("Number of entries", 1, entries.size()); - assertEquals("[ServiceA] new Service", entries.get(0).getMessage()); - - // Stop log entry tracking - stopLogEntryTracking(); - </programlisting> - - <emphasis role="bold">Testing a remote OSGi Framework</emphasis> - - <para>In the remote scenario the testcase deploys the test bundle on the remote OSGi Framework. The base class for embedded OSGi testing - is <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/junit/IntegrationTest.html">org.jboss.osgi.spi.junit.IntegrationTest</ulink>. - </para> - - <programlisting role="JAVA"> - public class RemoteTestCase extends IntegrationTest - { - public void testSomeBundle() throws Exception - { - // Deploy the test bundle - RemoteBundle bundleA = deployBundle("some-bundle.jar"); - - // Verify that the bundle is active - assertEquals("Test bundle ACTIVE", Bundle.ACTIVE, bundleA.getState()); - - // Undeploy the test bundle - undeployBundle("some-bundle.jar"); - } - } - </programlisting> - - <para>The test approach is simmilar to the embedded scenario. The test bundle writes log messages to the LogService. A RemoteLogListener transmits - the log messages to the RemoteLogReaderService that is installed locally. The test case registeres a LogListener with the RemoteLogReaderService. - Log messages are filtered and can be verified by the test case. Again, certain conditions must be true:</para> - - <itemizedlist> - <listitem>The remote Framework must have a LogService installed</listitem> - <listitem>The <emphasis role="bold">jboss-osgi-remotelog.jar</emphasis> bundle must be installed in both the remote and local Framework</listitem> - <listitem>The bundle under test must write log messages to LogService</listitem> - <listitem>The LogListener must be seen by the classloader that loads the test case</listitem> - </itemizedlist> - - <programlisting role="JAVA"> - // Setup log entry tracking - LogEntryCache logEntryCache = new LogEntryCache(); - logEntryCache.addFilter(new LogEntryFilter("example-log(.*)", LogService.LOG_INFO, "\\[ServiceA\\](.*)")); - - // Start log entry tracking - startRemoteLogEntryTracking(logEntryCache); - - // do stuff - - // Verify the received log entries - List entries = logEntryCache.getLog(); - assertEquals("Number of entries", 1, entries.size()); - assertEquals("[ServiceA] new Service", entries.get(0).getMessage()); - - // Stop log entry tracking - stopRemoteLogEntryTracking(); - </programlisting> - - <para>For details on how to setup remote log message tracking, have a look at <xref linkend="SecRemoteLogService"/>.</para> - - </sect1> - -</chapter> Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch05-husky-testing.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch05-husky-testing.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch05-husky-testing.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -1,29 +0,0 @@ -<!-- - $Id$ ---> -<chapter xml:id="ChapHuskyTesting"> - - <title>Husky OSGi 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/ch06-provided-bundles.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch06-provided-bundles.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch06-provided-bundles.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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 JBossOSGi <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/LogListe... - Subscribes to LogEntry objects from the LogReaderService</listitem> - <listitem><ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReade... - 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.p... - Compendium Services</ulink>. JBossOSGi currently uses the <ulink url="http://felix.apache.org/site/apache-felix-log-service.html"... 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 JBossOSGi <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/LogReade... that remotely - communicates with a server side <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListe...;. - </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/LogListe... - with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReade...;. 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>JBossOSGi 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/MBeanS...;. 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/MBeanS... - - <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/ch07-provided-examples.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch07-provided-examples.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch07-provided-examples.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -1,165 +0,0 @@ -<!-- - $Id$ ---> -<chapter xml:id="ChapProvidedExamples"> - - <title>Provided Examples</title> - - <sect1 xml:id="SecBuildAndRunExamples"> - <title>Building the Examples</title> - - <para>JBossOSGi 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@tddell example]$ mvn test - ... - [INFO] ------------------------------------------------------------------------ - [INFO] Building JBossOSGi - 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@tddell example]$ mvn -Djboss.bind.address=localhost test - ... - [INFO] ------------------------------------------------------------------------ - [INFO] Building JBossOSGi - 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/HttpSer...;. - </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/LogServi...;. - - </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/MBeanS...;. - </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/ch08-references.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch08-references.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch08-references.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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/JBossOSGi">JBossOSGi Wiki</ulink></listitem> - <listitem><ulink url="http://jbossosgi.blogspot.com">JBossOSGi 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&quo... - <listitem><ulink url="http://fisheye.jboss.com/browse/JBossOSGi">Fisheye</... - <listitem><ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... Forum</ulink></listitem> - <listitem><ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... Forum</ulink></listitem> - </itemizedlist> - - <para><emphasis role="bold">Authors</emphasis></para> - - <itemizedlist> - <listitem><ulink url="email:thomas.diesler@jboss.com">Thomas Diesler</ulink></listitem> - </itemizedlist> - -</chapter> Deleted: projects/jboss-osgi/trunk/docbook/en/modules/ch09-getting-support.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch09-getting-support.xml 2009-06-03 06:13:53 UTC (rev 89710) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch09-getting-support.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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&amp;op=viewforum&... 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> Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch10-getting-started.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch02-getting-started.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch10-getting-started.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch10-getting-started.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -0,0 +1,388 @@ +<!-- + $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&am... 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 based on JBossAS</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>.... + + <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 (--profile-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@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@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@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"... 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@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@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@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 Added: projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -0,0 +1,129 @@ +<!-- + $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-rf... 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="SecWritingTests">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/XMLParserAc... + 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"... 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-s... 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). + </listitem> + + <listitem><emphasis role="bold">Microcontainer Support</emphasis> - [TODO]</listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="SecRuntimeProfiles"> + <title>Runtime Profiles</title> + + <emphasis role="bold">Minimal Profile</emphasis> + <para>[TODO]</para> + + <emphasis role="bold">Default Profile</emphasis> + <para>[TODO]</para> + + <emphasis role="bold">Web Profile</emphasis> + <para>[TODO]</para> + + <emphasis role="bold">All Profile</emphasis> + <para>[TODO]</para> + </sect1> + +</chapter> + Property changes on: projects/jboss-osgi/trunk/docbook/en/modules/ch20-runtime.xml ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:eol-style + LF Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch30-framework-integration.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch03-framework-integration.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch30-framework-integration.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch30-framework-integration.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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"... Service</ulink> - General purpose message logger</listitem> + <listitem><ulink url="http://felix.apache.org/site/apache-felix-http-service.html&quo... Service</ulink> - Http access to servlets and resources</listitem> + <listitem><ulink url="http://felix.apache.org/site/apache-felix-configuration-admin-s... 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/ch40-developer-guide.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch04-developer-guide.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch40-developer-guide.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch40-developer-guide.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -0,0 +1,400 @@ +<!-- + $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 between the supported OSGi Frameworks and + the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink>. The configuration defines MC beans for the + framework itself and its associated deployers.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/jboss-osgi.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/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/junit/package-summary.html">org.jboss.osgi.spi.junit</ulink> - JUnit test integration.</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/microcontainer/package-summary.html">org.jboss.osgi.spi.service.microcontainer</ulink> - Access to the Kernel and MBeanServer.</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 a OSGiBootstrapProvider that uses a <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> + bean 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.felix.framework.FelixIntegration"> + <property name="felixProperties"> + <map keyClass="java.lang.String" valueClass="java.lang.String"> + <entry><key>org.osgi.framework.storage.clean</key><value>onFirstInit</value></entry> + <entry> + <key>org.osgi.framework.system.packages</key> + <value> + org.osgi.framework; version=1.4, + org.osgi.util.tracker + </value> + </entry> + </map> + </property> + </bean> + + ... + + </deployment> + ]]></programlisting> + + <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">BundleMetaDataDeployer</emphasis> - Create BundleMetaData from Manifest Headers</listitem> + <listitem><emphasis role="bold">BundleStructureDeployer</emphasis> - Determine the structure of a Bundle deployment</listitem> + <listitem><emphasis role="bold">BundleRealDeployer</emphasis> - Installs the Bundle into the Framework's SystemContext</listitem> + <listitem><emphasis role="bold">BundleClassLoaderDeployer</emphasis> - Creates a BundleClassLoader for the deployed Bundle</listitem> + <listitem><emphasis role="bold">BundleStartStopDeployer</emphasis> - Starts the Bundle when dependencies are resolved</listitem> + <listitem><emphasis role="bold">BundleManagementDeployer</emphasis> - Register the Bundle as MBean with JMX</listitem> + </itemizedlist> + + <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">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> + + <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">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">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...;. + 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.htm...;. + 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">BundleManagementDeployer</emphasis> + + <para>The BundleManagementDeployer registers the Bundle as <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/Standa... with JMX. + Please see the section on <link linkend="SecJMXView">Management View</link> for details.</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/MBeanS... + + <emphasis role="bold">The ManagedFramework</emphasis> + + <para>The <code>ManagedFramework</code> 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> + + <programlisting role="JAVA"> + public interface ManagedFrameworkMBean + { + /** + * Get the list of all installed bundles + */ + Set&lt;ObjectName> getBundles(); + + /** + * Get the installed bundle + */ + ObjectName getBundle(String symbolicName); + } + </programlisting> + + <emphasis role="bold">The ManagedBundle</emphasis> + + <para>The <code>ManagedBundle</code> 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> + + <programlisting role="JAVA"> + public interface ManagedBundleMBean + { + /** + * Returns this bundle's current state. + * A bundle can be in only one state at any time. + * + * @return An element of UNINSTALLED,INSTALLED, RESOLVED,STARTING, STOPPING,ACTIVE. + */ + int getState(); + + /** + * Get the bundles object name. + */ + ObjectName getObjectName(); + + /** + * Returns this bundle's unique identifier. + */ + long getBundleId(); + + /** + * Returns the symbolic name of this bundle as specified by its Bundle-SymbolicName manifest header + */ + String getSymbolicName(); + + /** + * Returns the value of the specified property from the BundleContext. + */ + String getProperty(String key); + + /** + * Starts this bundle with no options + */ + void start() throws BundleException; + + /** + * Stops this bundle with no options. + */ + void stop() throws BundleException; + } + </programlisting> + + <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/junit/package-summary.html">org.jboss.osgi.spi.junit</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 Testcases</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/junit/package-summary.html">org.jboss.osgi.spi.junit</ulink> + package. There are two distinct test scenarios that we support</para> + + <itemizedlist> + <listitem>Embedded OSGi Framework</listitem> + <listitem>Remote OSGi Framework</listitem> + </itemizedlist> + + <emphasis role="bold">Testing an embedded OSGi Framework</emphasis> + + <para>In the embedded scenario the testcase bootstraps the OSGi Framework and installes and tests the bundles locally. The base class for + embedded OSGi testing is <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/junit/OSGiTest.html">org.jboss.osgi.spi.junit.OSGiTest</ulink>. + </para> + + <programlisting role="JAVA"> + public class EmbeddedTestCase extends OSGiTest + { + public void testSomeBundle() throws Exception + { + // Bootstrap the Framework and get the system bundle + OSGiFramework framework = getBootstrapProvider().getFramework(); + BundleContext sysContext = framework.getSystemBundleContext(); + + // Install and start the test bundle + Bundle bundleA = installBundle(sysContext, "some-bundle.jar", true); + + // Verify that the bundle is active + assertEquals("Test bundle ACTIVE", Bundle.ACTIVE, bundleA.getState()); + } + } + </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. We use an approach where the test case registeres a <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListe... + with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReade...;. Log messages are filtered and + can be verified by the test case. For this to work certain conditions must be true:</para> + + <itemizedlist> + <listitem>The Framework must have a LogService installed</listitem> + <listitem>The bundle under test must write log messages to LogService</listitem> + <listitem>The LogListener must be seen by the classloader that loads the test case</listitem> + </itemizedlist> + + <programlisting role="JAVA"> + // Setup log entry tracking + LogEntryCache logEntryCache = new LogEntryCache(); + logEntryCache.addFilter(new LogEntryFilter("example-log(.*)", LogService.LOG_INFO, "\\[ServiceA\\](.*)")); + + // Start log entry tracking + startLogEntryTracking(logEntryCache); + + // do stuff + + // Verify the received log entries + List entries = logEntryCache.getLog(); + assertEquals("Number of entries", 1, entries.size()); + assertEquals("[ServiceA] new Service", entries.get(0).getMessage()); + + // Stop log entry tracking + stopLogEntryTracking(); + </programlisting> + + <emphasis role="bold">Testing a remote OSGi Framework</emphasis> + + <para>In the remote scenario the testcase deploys the test bundle on the remote OSGi Framework. The base class for embedded OSGi testing + is <ulink url="http://jbmuc.dyndns.org:8280/hudson/job/jbossosgi-jdk16/javadoc/org/jboss/osgi/spi/junit/IntegrationTest.html">org.jboss.osgi.spi.junit.IntegrationTest</ulink>. + </para> + + <programlisting role="JAVA"> + public class RemoteTestCase extends IntegrationTest + { + public void testSomeBundle() throws Exception + { + // Deploy the test bundle + RemoteBundle bundleA = deployBundle("some-bundle.jar"); + + // Verify that the bundle is active + assertEquals("Test bundle ACTIVE", Bundle.ACTIVE, bundleA.getState()); + + // Undeploy the test bundle + undeployBundle("some-bundle.jar"); + } + } + </programlisting> + + <para>The test approach is simmilar to the embedded scenario. The test bundle writes log messages to the LogService. A RemoteLogListener transmits + the log messages to the RemoteLogReaderService that is installed locally. The test case registeres a LogListener with the RemoteLogReaderService. + Log messages are filtered and can be verified by the test case. Again, certain conditions must be true:</para> + + <itemizedlist> + <listitem>The remote Framework must have a LogService installed</listitem> + <listitem>The <emphasis role="bold">jboss-osgi-remotelog.jar</emphasis> bundle must be installed in both the remote and local Framework</listitem> + <listitem>The bundle under test must write log messages to LogService</listitem> + <listitem>The LogListener must be seen by the classloader that loads the test case</listitem> + </itemizedlist> + + <programlisting role="JAVA"> + // Setup log entry tracking + LogEntryCache logEntryCache = new LogEntryCache(); + logEntryCache.addFilter(new LogEntryFilter("example-log(.*)", LogService.LOG_INFO, "\\[ServiceA\\](.*)")); + + // Start log entry tracking + startRemoteLogEntryTracking(logEntryCache); + + // do stuff + + // Verify the received log entries + List entries = logEntryCache.getLog(); + assertEquals("Number of entries", 1, entries.size()); + assertEquals("[ServiceA] new Service", entries.get(0).getMessage()); + + // Stop log entry tracking + stopRemoteLogEntryTracking(); + </programlisting> + + <para>For details on how to setup remote log message tracking, have a look at <xref linkend="SecRemoteLogService"/>.</para> + + </sect1> + +</chapter> Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch50-husky-testing.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch05-husky-testing.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch50-husky-testing.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch50-husky-testing.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -0,0 +1,29 @@ +<!-- + $Id$ +--> +<chapter xml:id="ChapHuskyTesting"> + + <title>Husky OSGi 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/ch60-provided-bundles.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch06-provided-bundles.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch60-provided-bundles.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch60-provided-bundles.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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/LogListe... - Subscribes to LogEntry objects from the LogReaderService</listitem> + <listitem><ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReade... - 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.p... + Compendium Services</ulink>. JBoss OSGi currently uses the <ulink url="http://felix.apache.org/site/apache-felix-log-service.html"... 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/LogReade... that remotely + communicates with a server side <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogListe...;. + </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/LogListe... + with the <ulink url="http://www.osgi.org/javadoc/r4v41/org/osgi/service/log/LogReade...;. 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/MBeanS...;. 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/MBeanS... + + <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/ch70-provided-examples.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch07-provided-examples.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch70-provided-examples.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch70-provided-examples.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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@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@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/HttpSer...;. + </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/LogServi...;. + + </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/MBeanS...;. + </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/ch80-references.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch08-references.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch80-references.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch80-references.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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&quo... + <listitem><ulink url="http://fisheye.jboss.com/browse/JBoss OSGi">Fisheye</ulink></listitem> + <listitem><ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... Forum</ulink></listitem> + <listitem><ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... Forum</ulink></listitem> + </itemizedlist> + + <para><emphasis role="bold">Authors</emphasis></para> + + <itemizedlist> + <listitem><ulink url="email:thomas.diesler@jboss.com">Thomas Diesler</ulink></listitem> + </itemizedlist> + +</chapter> Copied: projects/jboss-osgi/trunk/docbook/en/modules/ch90-getting-support.xml (from rev 89708, projects/jboss-osgi/trunk/docbook/en/modules/ch09-getting-support.xml) =================================================================== --- projects/jboss-osgi/trunk/docbook/en/modules/ch90-getting-support.xml (rev 0) +++ projects/jboss-osgi/trunk/docbook/en/modules/ch90-getting-support.xml 2009-06-03 06:55:36 UTC (rev 89711) @@ -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&amp;op=viewforum&... 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/docbook/src/main/graphics/jbossosgi-runtime.odp =================================================================== (Binary files differ)