JBoss.orgCommunity Documentation

Chapter 8. Provided Examples

8.1. Building the Examples
8.2. Simple Example
8.3. SAX/DOM Parser Service Example
8.4. JAXB Service Example
8.5. JMX Service Example
8.6. JNDI Service Example
8.7. HttpService Example
8.8. WebApp Example
8.9. Microcontainer Service Example
8.10. Blueprint Container Example

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 Maven Build Process and Hudson QA Environment.

The examples can be either run against an embedded OSGi runtime or against a remote OSGi runtime. Here is how you build and run the against the embedded runtime.

    [tdiesler@tddell example]$ mvn test
     
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running org.jboss.test.osgi.example.webapp.WebAppTestCase
    Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 7.202 sec
    Running org.jboss.test.osgi.example.blueprint.BlueprintTestCase
    Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 7.447 sec
    Running org.jboss.test.osgi.example.xml.jaxb.JAXBTestCase
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.722 sec
    Running org.jboss.test.osgi.example.microcontainer.MicrocontainerTestCase
    Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.444 sec
    Running org.jboss.test.osgi.example.xml.parser.SAXParserTestCase
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.452 sec
    Running org.jboss.test.osgi.example.http.HttpServiceTestCase
    Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.562 sec
    Running org.jboss.test.osgi.example.xml.parser.DOMParserTestCase
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.032 sec
    Running org.jboss.test.osgi.example.jndi.JNDITestCase
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.836 sec
    Running org.jboss.test.osgi.example.jmx.JMXTestCase
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.058 sec
    Running org.jboss.test.osgi.example.simple.SimpleTestCase
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.772 sec
    Running org.jboss.test.osgi.example.simple.SimpleHuskyTestCase
    Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.262 sec
    
    Tests run: 21, Failures: 0, Errors: 0, Skipped: 0
    
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESSFUL
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 49 seconds
    [INFO] Finished at: Tue Oct 13 13:04:20 CEST 2009
    [INFO] Final Memory: 25M/47M
    [INFO] ------------------------------------------------------------------------
    

To run the examples against a remote OSGi Runtime, you need to provide the target container that the runtime should connect to. This can be done with the target.container system property.

    mvn -Dtarget.container=runtime test
    

Suported target container values are:

  • runtime
  • jboss501
  • jboss510
  • jboss520
  • jboss600

To run the examples against a different OSGi Framework, you need to define the framework system property.

    mvn -Dframework=felix test
    

Suported framework values are:

  • jbossmc
  • equinox
  • felix

The simple example is covered in: Writing Test Cases

The example-xml-parser.jar bundle gets a DocumentBuilderFactory/SAXParserFactory respectivly and unmarshalls an XML document using that parser.



      ServiceReference sref = context.getServiceReference(DocumentBuilderFactory.class.getName());
      if (sref == null)
         throw new IllegalStateException("DocumentBuilderFactory not available");
      
      DocumentBuilderFactory factory = (DocumentBuilderFactory)context.getService(sref);
      factory.setValidating(false);
      
      DocumentBuilder domBuilder = factory.newDocumentBuilder();
      URL resURL = context.getBundle().getResource("example-xml-parser.xml");
      Document dom = domBuilder.parse(resURL.openStream());
      assertNotNull("Document not null", dom);
    


      ServiceReference sref = context.getServiceReference(SAXParserFactory.class.getName());
      if (sref == null)
         throw new IllegalStateException("SAXParserFactory not available");
      
      SAXParserFactory factory = (SAXParserFactory)context.getService(sref);
      factory.setValidating(false);
      
      SAXParser saxParser = factory.newSAXParser();
      URL resURL = context.getBundle().getResource("example-xml-parser.xml");
      
      SAXHandler saxHandler = new SAXHandler();
      saxParser.parse(resURL.openStream(), saxHandler);
      assertEquals("content", saxHandler.getContent());
    

The example-xml-jaxb.jar bundle gets the JAXBContext from the JAXBService and unmarshalls an XML document using JAXB



      ServiceReference sref = context.getServiceReference(JAXBService.class.getName());
      if (sref == null)
         throw new IllegalStateException("JAXBService not available");
      
      JAXBService service = (JAXBService)context.getService(sref);
      JAXBContext jaxbContext = service.newJAXBContext(getClass().getPackage().getName());
      Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
      
      URL resURL = context.getBundle().getResource("booking.xml");
      JAXBElement rootElement = unmarshaller.unmarshal(resURL.openStream());
      assertNotNull("root element not null", rootElement);
    

The example-jmx.jar bundle tracks the MBeanServer service and registers a pojo with JMX. It then verifies the JMX access.



    public class FooServiceActivator implements BundleActivator
    {
       public void start(BundleContext context)
       {
          ServiceTracker tracker = new ServiceTracker(context, MBeanServer.class.getName(), null)
          {
             public Object addingService(ServiceReference reference)
             {
                MBeanServer mbeanServer = (MBeanServer)super.addingService(reference);
                registerMBean(mbeanServer);
                return mbeanServer;
             }
    
             @Override
             public void removedService(ServiceReference reference, Object service)
             {
                unregisterMBean((MBeanServer)service);
                super.removedService(reference, service);
             }
          };
          tracker.open();
       }
    
       public void stop(BundleContext context)
       {
          ServiceReference sref = context.getServiceReference(MBeanServer.class.getName());
          if (sref != null)
          {
             MBeanServer mbeanServer = (MBeanServer)context.getService(sref);
             unregisterMBean(mbeanServer);
          }
       }
       ...
    }
    


     public void testMBeanAccess() throws Exception
     {
        FooMBean foo = (FooMBean)MBeanProxy.get(FooMBean.class, MBEAN_NAME, runtime.getMBeanServer());
        assertEquals("hello", foo.echo("hello"));
     }
    

The example-jndi.jar bundle gets the InitialContext service and registers a string with JNDI. It then verifies the JNDI access.



    ServiceReference sref = context.getServiceReference(InitialContext.class.getName());
    if (sref == null)
       throw new IllegalStateException("Cannot access the InitialContext");
    
    InitialContext iniContext = (InitialContext)context.getService(sref);
    iniCtx.createSubcontext("test").bind("Foo", new String("Bar"));
    


     public void testJNDIAccess() throws Exception
     {
        InitialContext iniCtx = runtime.getInitialContext();
        String lookup = (String)iniCtx.lookup("test/Foo");
        assertEquals("JNDI bound String expected", "Bar", lookup);
  
        // Uninstall should unbind the object
        bundle.uninstall();
  
        try
        {
           iniCtx.lookup("test/Foo");
           fail("NameNotFoundException expected");
        }
        catch (NameNotFoundException ex)
        {
           // expected
        }
     }
    

The example-http.jar bundle contains a Service that registeres a servlet and a resource with the HttpService.



      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);
    

The test then verifies that the registered servlet context and the registered resource can be accessed.

The example-webapp.war archive is an OSGi Bundle as well as an Web Application Archive (WAR) at the same time. Similar to HTTP Service Example it registers a servlet and resources with the WebApp container. This is done through a standard web.xml descriptor.



    <web-app xmlns="http://java.sun.com/xml/ns/javaee" ... version="2.5">
    
      <display-name>WebApp Sample</display-name>
    
      <servlet>
        <servlet-name>servlet</servlet-name>
        <servlet-class>org.jboss.test.osgi.example.webapp.bundle.EndpointServlet</servlet-class>
        <init-param>
          <param-name>initProp</param-name>
          <param-value>SomeValue</param-value>
        </init-param>
      </servlet>
    
      <servlet-mapping>
        <servlet-name>servlet</servlet-name>
        <url-pattern>/servlet</url-pattern>
      </servlet-mapping>
    
    </web-app>
    

The associated OSGi manifest looks like this.

    Manifest-Version: 1.0
    Bundle-Name: example-webapp
    Bundle-ManifestVersion: 2
    Bundle-SymbolicName: example-webapp
    Bundle-ClassPath: .,WEB-INF/classes
    Import-Package: org.osgi.service.http,org.ops4j.pax.web.service,javax.servlet,javax.servlet.http
    

The test verifies that we can access the servlet and some resourtces.



     @Test
     public void testResourceAccess() throws Exception
     {
        assertEquals("Hello from Resource", getHttpResponse("/message.txt"));
     }
  
     @Test
     public void testServletAccess() throws Exception
     {
        assertEquals("Hello from Servlet", getHttpResponse("/servlet?test=plain"));
     }
    

The example-microcontainer.jar bundle contains a Service that calls a service from an MC bean and vica versa. The MC bean registeres itself as an MBean after it got the MBeanServer injected.

The test accesses the registered MBean.



    @Test
    public void testServiceRoundTrip() throws Exception
    {
      SomeBeanMBean someBean = MBeanProxy.get(SomeBeanMBean.class, MBEAN_NAME, runtime.getMBeanServer());
      assertEquals("hello", someBean.echo("hello"));
      assertEquals("hello", someBean.callSomeService("hello"));
    }
    

The example-blueprint.jar bundle contains a number of components that are wired together and registerd as OSGi service through the Blueprint Container Service.

The example uses this simple blueprint descriptor



    <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" ...>
      
      <bean id="beanA" class="org.jboss.test.osgi.example.blueprint.bundle.BeanA">
        <property name="mbeanServer" ref="mbeanService"/>
      </bean>
      
      <service id="serviceA" ref="beanA" interface="org.jboss.test.osgi.example.blueprint.bundle.ServiceA">
      </service>
      
      <service id="serviceB" interface="org.jboss.test.osgi.example.blueprint.bundle.ServiceB">
        <bean class="org.jboss.test.osgi.example.blueprint.bundle.BeanB">
           <property name="beanA" ref="beanA"/>
        </bean>
      </service>
      
      <reference id="mbeanService" interface="javax.management.MBeanServer"/>
    
    </blueprint>
    

The Blueprint Container registers two services ServiceA and ServiceB. ServiceA is backed up by BeanA, ServiceB is backed up by the anonymous BeanB. BeanA is injected into BeanB and the MBeanServer gets injected into BeanA. Both beans are plain POJOs. There is no BundleActivator neccessary to register the services.

The example test verifies the correct wiring like this



     @Test
     public void testServiceA() throws Exception
     {
        ServiceReference sref = context.getServiceReference(ServiceA.class.getName());
        assertNotNull("ServiceA not null", sref);
        
        ServiceA service = (ServiceA)context.getService(sref);
        MBeanServer mbeanServer = service.getMbeanServer();
        assertNotNull("MBeanServer not null", mbeanServer);
     }
    


     @Test
     public void testServiceB() throws Exception
     {
        ServiceReference sref = context.getServiceReference(ServiceB.class.getName());
        assertNotNull("ServiceB not null", sref);
        
        ServiceB service = (ServiceB)context.getService(sref);
        BeanA beanA = service.getBeanA();
        assertNotNull("BeanA not null", beanA);
     }