SpringSource dm Server™ Programmer Guide

The SpringSource dm Server is built on top of the following core technologies:

Note, however, that the SpringSource dm Server isn't just a combination of these technologies. Rather, it integrates and extends these technologies to provide many features essential for developing, deploying, and managing today's enterprise Java applications.

While many applications deployed in the SpringSource dm Server will take advantage of OSGi capabilities, not all applications need such sophistication. For example, development teams may initially choose to continue packaging existing web applications as standard WAR files and then gradually migrate toward a fully OSGi-based packaging and deployment model. The SpringSource dm Server makes such migrations easy for developers by supporting multiple packaging and deployment formats. These formats and migration strategies are discussed in greater detail in Chapter 5, Migrating to OSGi and Chapter 6, Case study: Migrating the Form Tags sample application.

Prior to the release of the SpringSource dm Server, developing and deploying OSGi applications involved inherent complexity such as:

Furthermore, since standard OSGi does not define a notion of an application as a set of bundles, you cannot deploy or undeploy an application and its constituent bundles as a single unit.

The SpringSource dm Server introduces a number of features to solve these issues:

Identifying why an application won't deploy or which particular library dependencies are unsatisfied is the cause of many headaches! Similarly, production time errors that don't identify the root cause are all too familiar to Java developers. The dm Server was designed from the ground up to enable tracing and First Failure Data Capture (FFDC) that empower developers with precise information at the point of failure to fix the problem quickly.

At its core, the SpringSource dm Server is an OSGi container. Thus any OSGi-compliant bundle can be deployed directly on the dm Server unmodified. You'll typically deploy an application as a single bundle or a set of stand-alone bundles if you'd like to publish or consume services globally within the container via the OSGi Service Registry.

For Web Application Archives (WAR), the SpringSource dm Server provides support for the following three formats.

Each of these formats plays a distinct role in the incremental migration path from a standard Java EE WAR to an OSGi-ified web application.

Shared Libraries WAR

If you have experience with developing and packaging web applications using the standard WAR format, you're certainly familiar with the pains of library bloat. So, unless you're installing shared libraries in a common library folder for your Servlet container, you have to pack all JARs required by your web application in /WEB-INF/lib . Prior to the release of the SpringSource dm Server, such library bloat has essentially been the norm for web applications, but now there is a better solution! The Shared Libraries WAR format reduces your application's deployment footprint and eradicates library bloat by allowing you to declare dependencies on libraries via standard OSGi manifest headers such as Import-Package and Require-Bundle . The dm Server provides additional support for simplifying dependency management via the Import-Library and Import-Bundle manifest headers which are essentially macros that get expanded into OSGi-compliant Import-Package statements.

	Tip
	For detailed information on which libraries are already available, check out the SpringSource Enterprise Bundle Repository"> .

Above and beyond WAR-based deployment formats, the SpringSource dm Server introduces a deployment and packaging option for OSGi-compliant web applications, the Web Module format. Web modules have a structure similar to a Shared Services WAR and can therefore take full advantage of all three WAR deployment formats. In addition, web modules benefit from reduced configuration for Spring MVC based applications via new OSGi manifest headers such as Web-DispatcherServletUrlPatterns and Web-FilterMappings. For further details on these and other Web-* manifest headers, please consult the section called “Web Module Manifest Headers”.

If you're building a Spring MVC based web application as a web module, you won't need to worry about configuring a root WebApplicationContext or an ApplicationContext for your DispatcherServlet. Based on metadata in your web module's /META-INF/MANIFEST.MF, the dm Server will auto-generate an appropriately configured web.xml for you on-the-fly, and your application will use the ApplicationContext created for your web module by Spring-DM. Future releases of the dm Server will add additional support to simplify configuration of Spring Web Flow based web applications as well.

A PAR is a standard JAR which contains all of the modules of your application (e.g., service, domain, and infrastructure bundles as well as a WAR or web module for web applications) in a single deployment unit. This allows you to deploy, refresh, and undeploy your entire application as a single entity. If you are familiar with Java EE, it is worth noting that a PAR can be considered a replacement for an EAR (Enterprise Archive) within the context of an OSGi container. As an added bonus, modules within a PAR can be refreshed independently and on-the-fly, for example via the SpringSource dm Server Tool Suite (see Chapter 7, Tooling).

Many of the benefits of the PAR format are due to the underlying OSGi infrastructure, including:

Furthermore, PARs scope the modules of your application within the dm Server. Scoping provides both a physical and logical application boundary, effectively shielding the internals of your application from other PARs deployed within the dm Server. This means your application doesn't have to worry about clashing with other running applications (e.g., in the OSGi Service Registry). You get support for load-time weaving, classpath scanning, context class loading, etc., and the dm Server does the heavy lifting for you to make all this work seamlessly in an OSGi environment. If you want to take full advantage of all that the SpringSource dm Server and OSGi have to offer, packaging and deploying your applications as a PAR is a good choice, although plans are an even better one, as described in the next section.

OSGi != multiple JARs

Note that while physically separated modules can, in theory, be implemented simply using multiple JARs, complex versioning requirements often make this impractical. For example, consider the situation depicted in the diagram below. Bundle A depends on version 1.0.0 of bundle B and version 2.0.0 of bundle C. Bundle B depends on version 1.0.0 of bundle C. Suppose that versions 1.0.0 and 2.0.0 of bundle C are neither backward nor forward compatible. Traditional monolithic applications cannot handle such situations: either bundle A or bundle B would need reworking which undermines truly independent development. OSGi's versioning scheme enables this scenario to be implemented in a robust manner. If it is desirable to rework the application to share a single version of C, then this can be planned in and is not forced.

A plan is similar to a PAR in that it encapsulates all of the artifacts of your application in a single deployment unit. The main difference, however, is that a plan is simply an XML file that lists the artifacts of your application; a PAR, by contrast, is an actual JAR file that physically contains the artifacts. Just like a PAR, you deploy, refresh, and undeploy a plan as a single entity. SpringSource highly recommends the use of plans for creating applications.

When you create a plan, you can specify that the included bundles and services are in a scope that isolates them from the rest of SpringSource dm Server and its deployments. This scoping ensures that the bundles wire to each other and see each other's services in preference to services from outside the scope. Scoping also prevents application code from leaking into the global scope or scope of another application. In addition, a plan can link the lifecycle of a group of bundles together atomically, which ensures that install, start, stop, and uninstall events on a single artifact in the plan are escalated to all artifacts in the plan. You can, however, disable both of these features by simply updating an attribute in the plan.

The general benefits of using plans are similar to those of using PARs; see PAR for details. Plans offer added benefits, however, such as the ability to control the deployment order of your application: the order in which you list artifacts in the plan's XML file is the order in which dm Server deploys them. Additionally, because plans specify the artifacts that make up an application by reference, it is easier to share content between plans as well as update individual parts of a plan without having to physically repackage (re-JAR) it.

An OSGi application is packaged as a JAR file, with extension .par. A PAR artifact offers several benefits:

A PAR includes one or more application bundles and its manifest specifies the following manifest headers:

The following code shows an example MANIFEST.MF in a PAR file:

Application-SymbolicName: com.example.shop
Application-Version: 1.0
Application-Name: Online Shop
Application-Description: Example.com's Online Shopping Application
			

A module offers OSGi-oriented packaging that supports specific application personalities. In this release, the only supported application personality is "Web ".

The most common type of application deployed in the SpringSource dm Server is, not surprisingly, the web application. The dm Server, therefore, supports the concept of a Web Module. A Web module is an OSGi bundle whose manifest includes directives to support various options pertinent to a web application.

Web modules have the following advantages over standard Java EE WAR files:

Web modules are standard OSGi bundles with the following characteristics:

Note

For Web Modules, the SpringSource dm Server introspects the contents of the deployed artifact and automatically adds /MODULE-INF/WEB-INF/classes (if present) to the Bundle-ClassPath. Similarly, if there are any JARs present in /MODULE-INF/WEB-INF/lib, each JAR will be added to the Bundle-ClassPath. For WARs, the dm Server performs the same logic for /WEB-INF/classes and any JARs present in /WEB-INF/lib.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName: org.springframework.showcase.formtags
Bundle-Version: 2.0.8
Bundle-Name: Spring Form Tags - Sample Web Application
Bundle-Description: Sample web application which demonstrates the use of Spring 2.0's
 custom form tag library
Import-Package: org.springframework.osgi.web.context,
 org.springframework.osgi.web.servlet,
 org.springframework.showcase.formtags.domain;version="2.0.8",
 org.springframework.showcase.formtags.service;version="2.0.8",
 org.springframework.showcase.formtags.validation;version="2.0.8",
 org.springframework.showcase.formtags.web;version="2.0.8"
Import-Library: org.springframework.spring;version="2.5.4"
Module-Type: Web
Web-ContextPath: formtags
Web-DispatcherServletUrlPatterns: *.htm
Web-FilterMappings: securityFilter;url-patterns:="*.htm,*.jsp",
Web-AccessLog: enabled="true";format="%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""
 imageFilter;url-patterns:="/image/*"

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName: formtags-web
Bundle-Version: 2.0.8
Import-Package: org.springframework.showcase.formtags.domain;version="
 2.0.8",org.springframework.showcase.formtags.service;version="2.0.8",
 org.springframework.showcase.formtags.validation;version="2.0.8",org.
 osgi.framework,org.springframework.osgi.context
Import-Library: org.springframework.spring;version="2.5.4"
Module-Type: Web
Web-ContextPath: formTagsParWithWebModuleAndWebXmlFragment
Web-DispatcherServletUrlPatterns: *.htm

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="2.5"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <display-name>Spring Form Tags - Sample Web Application</display-name>

    <description>
        Sample web application which demonstrates the use of Spring 2.0's
        custom form tag library
    </description>

    <filter>
        <filter-name>imageFilter</filter-name>
        <filter-class>com.example.filter.ImageFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>imageFilter</filter-name>
        <url-pattern>/images/*</url-pattern>
    </filter-mapping>

    <session-config>
        <session-timeout>5</session-timeout>
    </session-config>

    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
        <welcome-file>index.htm</welcome-file>
    </welcome-file-list>

</web-app>

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="2.5"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <servlet>
        <servlet-name>formtags-web-DispatcherServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
        <init-param>
            <param-name>contextAttribute</param-name>
            <param-value>formtags-web-ApplicationContext</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>formtags-web-DispatcherServlet</servlet-name>
        <url-pattern>*.htm</url-pattern>
    </servlet-mapping>

    <display-name>Spring Form Tags - Sample Web Application</display-name>

    <description>
        Sample web application which demonstrates the use of Spring 2.0's
        custom form tag library
    </description>

    <filter>
        <filter-name>imageFilter</filter-name>
        <filter-class>com.example.filter.ImageFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>imageFilter</filter-name>
        <url-pattern>/images/*</url-pattern>
    </filter-mapping>

    <session-config>
        <session-timeout>5</session-timeout>
    </session-config>

    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
        <welcome-file>index.htm</welcome-file>
    </welcome-file-list>

</web-app>

When packaging WARs for deployment on the SpringSource dm Server, the following should serve as general guidelines.

Plans are XML files that have a .plan file extension, such as myapplication.plan. The structure of the XML file is simple: the root element is <plan> with attributes specifying the name of the plan, the version, atomicity, and scoping. Then, for each artifact that makes up your application, you add a <artifact> element, using its attributes to specify the type of artifact and its name and version. The following is a simple example of a plan's XML file:

<?xml version="1.0" encoding="UTF-8"?>
<plan name="multi-artifact.plan" version="1.0.0" scoped="true" atomic="true"
        xmlns="http://www.springsource.org/schema/dm-server/plan"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="
            http://www.springsource.org/schema/dm-server/plan 
            http://www.springsource.org/schema/dm-server/plan/springsource-dm-server-plan.xsd">

    <artifact type="bundle" name="simple.bundle.one" version="[1.0.0, 2.0.0)"/>
    <artifact type="bundle" name="simple.bundle.two" version="[2.0.0, 3.1.0)"/>
</plan>

In the preceding example, the name of the plan is multi-artifact.plan and its version is 1.0.0. The plan is both scoped and atomic. The plan contains two artifacts, both of which are bundles.

The following table describes the attributes of the <plan> element.

The following table describes the attributes of the <artifact> element.

Because a plan is a list of artifacts, rather than a physical file that contains the artifacts, there are a few additional steps you must perform before you deploy it to .

All deployment artifacts supported by the Web personality (i.e., all WAR variants and Web Modules) will have the following packages automatically added to their bundle manifest via the appropriate Import-Package statements.

In addition, to ensure compatibility for existing, standard Java EE WARs, the dm Server automatically imports all packages exported by the OSGi system bundle, excluding any packages which begin with "org.eclipse" or "com.springsource". The resulting set of filtered system bundle exports will be automatically imported for all WAR variants but not for Web Modules; however, for all web deployment artifacts it is recommended that all known dependencies be explicitly specified in MANIFEST.MF via the appropriate Import-Package statements.

	System Bundle Package Exports
	For further details on which packages are exported by the OSGi system bundle, consult the server.profile file located in the SERVER_HOME/lib directory which corresponds to the version of the JVM on which the dm Server is running (e.g., java5-server.profile or java6-server.profile).

A bundle in an application can declare a dependency on a library by using the SpringSource dm Server-specific Import-Library header. This header specifies a comma-separated list of library symbolic names and version ranges that determine which libraries are imported. By default a dependency on a library is mandatory but this can be controlled through use of the resolution directive in exactly the same way as it can with Import-Package.

Import-Library: org.springframework.spring;version="[2.5.4, 3.0)",
 org.aspectj;version="[1.6.0,1.6.0]";resolution:="optional"
            

This example Import-Library header declares a mandatory dependency on the Spring library at a version from 2.5.4 inclusive to 3.0 exclusive. It also declares an optional dependency on the AspectJ library at exactly 1.6.0.

A bundle in an application can declare a dependency on a bundle by using the SpringSource dm Server-specific Import-Bundle header. The header specifies a comma-separated list of bundle symbolic names, version ranges, and scope declarmations that determine which bundles are imported and the scope of their dependency. By default a dependency on a bundle is mandatory but this can be controlled through use of the resolution directive in exactly the same way as it can with Import-Package.

Import-Bundle: com.springsource.org.apache.commons.dbcp;version="[1.2.2.osgi, 1.2.2.osgi]"
           

This example Import-Bundle header declares a mandatory dependency on the Apache Commons DBCP bundle at exactly 1.2.2.osgi.

When working with a scoped application, such as a PAR file or a plan, you might run into a situation where one of the bundles in the application (call it bundleA) depends on another bundle (bundleB) that performs a runtime task (such as class generation) that a third bundle (bundleC) might need to know about, although bundleC does not explicitly depend on bundleB.

For example, Hibernate uses CGLIB (code generation library) at runtime to generate proxies for persistent classes. Assume that a domain bundle in your application uses Hibernate for its persistent objects, and thus its Import-Bundle manifest header includes the Hibernate bundle. Further assume that a separate Web bundle uses reflection in its data-binding code, and thus needs to reflect on the persistent classes generated by Hibernate at runtime. The Web bundle now has an indirect dependency on the Hibernate bundle because of these dynamically generated classes, although the Web bundle does not typically care about the details of how these classes are persisted. One way to solve this dependency problem is to explicitly add the Hibernate bundle to the Import-Bundle header of the Web bundle; however, this type of explicit-specified dependency breaks the modularity of the application and is not a programming best practice.

A better way to solve this problem is to specify that itself dynamically import the bundle (Hibernate in the example above) to all bundles in the application at runtime. You do this by adding the import-scope:=application directive to the Import-Bundle header of the bundle that has the direct dependency (the domain bundle in our example). At runtime, although the Web bundle does not explicitly import the Hibernate bundle, implicitly imports it and thus its classes are available to the Web module. This mechanism allows you to declare the dependencies you need to make your application run, without having to make changes to your application that might limit its flexibility.

The following example shows how to use the import-scope directive with the Import-Bundle header:

Import-Bundle: com.springsource.org.hibernate;version="[3.2.6.ga,3.2.6.ga]";import-scope:=application

You can also set the import-scope directive to the (default) value bundle; in this case, the scope of the bundle is just the bundle itself and thus does not perform any implicit importing into other bundles of the application.

Note that use of the import-scope:=application directive of the Import-Bundle header only makes sense when the bundle is part of a scoped application (PAR or plan); if the bundle is not part of a scoped application, then this directive has no effect.

Finally, because import-scope:=application implicitly adds a bundle import to each bundle of the PAR or plan, the impact of subsequently refreshing the imported bundle is, in general, broader than it would have been if you had not used import-scope:=application. This may well affect the performance of refresh.

Libraries are defined in a simple text file, typically with a .libd suffix. This file identifies the library and lists all of its constituent bundles. For example, the following is the library definition for Spring 2.5.4:

Library-SymbolicName: org.springframework.spring
Library-Version: 2.5.4
Library-Name: Spring Framework
Import-Bundle: org.springframework.core;version="[2.5.4,2.5.5)",
 org.springframework.beans;version="[2.5.4,2.5.5)",
 org.springframework.context;version="[2.5.4,2.5.5)",
 org.springframework.aop;version="[2.5.4,2.5.5)",
 org.springframework.web;version="[2.5.4,2.5.5)", 
 org.springframework.web.servlet;version="[2.5.4,2.5.5)",
 org.springframework.jdbc;version="[2.5.4,2.5.5)",
 org.springframework.orm;version="[2.5.4,2.5.5)",
 org.springframework.transaction;version="[2.5.4,2.5.5)",
 org.springframework.context.support;version="[2.5.4,2.5.5)",
 org.springframework.aspects;version="[2.5.4,2.5.5)",
 com.springsource.org.aopalliance;version="1.0"
			    

The following table lists all of the headers that may be used in a library definition:

Rather than encouraging the packaging of all an application's dependencies within the application itself, SpringSource dm Server uses a local provisioning repository of bundles and libraries upon which an application can depend. When the SpringSource dm Server encounters an application with a particular dependency, it will automatically provide, from its provisioning repository, the appropriate bundle or library.

Making a dependency available for provisioning is simply a matter of copying it to the appropriate location in the dm Server's local provisioning repository. By default this is SERVER_HOME/repository/bundles/usr for bundles, and SERVER_HOME/repository/libraries/usr for libraries. A more detailed discussion of the provisioning repository can be found in the User Guide.

If you do not wish to take advantage of the SpringSource dm Server's built-in support for per-application trace, it is possible to force your application to utilise vanilla Log4J rather than the SLF4J-based implementation that is provided in the SpringSource dm Server. This can be achieved by specifying the bundle symbolic name of the vanilla Log4J bundle when importing the Log4J package in your application's manifests. E.g.:

Import-Package: org.apache.log4j;bundle-symbolic-name="com.springsource.org.apache.log4j"
                

If you are not yet familiar with OSGi or simply want to deploy an existing web application on the SpringSource dm Server, you can deploy a standard WAR and leverage the dm Server with a minimal learning curve. In fact reading the SpringSource dm Server User Guide is pretty much all that you need to do to get started. Furthermore, you will gain familiarity with the SpringSource dm Server, while preparing to take advantage of the other formats.

The Shared Libraries WAR format is the first step to reaping the benefits of OSGi. In this phase, you dip your toes into OSGi-based dependency management by removing JAR files from the WAR and declaring dependencies on corresponding OSGi bundles.

In this phase, you take the next step toward a fully OSGi-based architecture by separating your web artifacts (e.g., Servlets, Controllers, etc.) from the services they depend on.

The final step in migrating a WAR is to convert it to a Web Module. As mentioned in the section called “Web Modules”, this format has a structure similar to that of a Shared Services WAR and adds additional benefits of reduced configuration for Spring MVC based applications via new OSGi manifest headers.

The following diagram graphically depicts the migration path from a Standard WAR to a Web Module. As you can see, the libraries (libs) move from within the deployment artifact to the Bundle Repository. Similarly, the services move from within the WAR to external bundles and are accessed via the OSGi Service Registry. In addition, the overall footprint of the deployment artifact decreases as you move towards a Web Module.

When migrating an existing application to the PAR packaging and deployment format or a plan, you consider modularity as the prime objective. Following the ideas discussed in Section 3.3, “A guide to forming bundles”, you refactor the application into multiple bundles. You may start conservatively with a small number of bundles and then further refactor those bundles.

If the original code is crafted following good software practices such as separation of concerns and use of well-defined interfaces, migration may involve modifying only configuration and packaging. In other words, your Java sources will remain unchanged. Even configuration is likely to change only slightly.

For example, the following diagram depicts a typical web application that has been refactored and packaged as a PAR. The blue elements within the Application box constitute the bundles of the application. Each of these bundles imports types from other bundles within the PAR using Import-Package. The green elements in the left column represent libraries installed on the dm Server. The PAR's bundles reference these libraries using Import-Library. The purple element in the left column represents a bundle within the dm Server's bundle repository which is imported by the DAO bundle using Import-Bundle. In contrast to a traditional, monolithic WAR deployment, the PAR format provides both a logical and physical application boundary and simultaneously allows the application to benefit from both the OSGi container and the SpringSource dm Server.

Once you have refactored your existing application into separate OSGi bundles, you then must decide whether to package the bundles into a single PAR file or create a plan that lists the bundles by reference. As described in more detail in preceding sections of this guides, PARs and plans have similar benefits, such as:

Plans, the method most recommended by SpringSource to create your application, has the following added benefits:

The main benefit of PARS is that, because they physically contain all the required artifacts, you know exactly what bundles are deployed when you deploy the PAR file, in contrast to plans that allow content to be substituted or lost.

For details about creating plans and PARs, see Section 4.3, “Creating Plans” and Section 4.2, “Creating PARs, Web Modules, and WARs”, respectively.

The responsibility of the first bundle (formtags-shared-services-service) is to provide the API of the formtags service. This includes both the domain and the service API. In the same way that imports are defined in the /META-INF/MANIFEST.MF, so are exports. The following is the /META-INF/MANIFEST.MF listing from the service bundle.

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.0
Created-By: 1.5.0_13-119 (Apple Inc.)
Bundle-ManifestVersion: 2
Bundle-Name: FormTags Service (and implementation)
Bundle-SymbolicName: org.springframework.showcase.formtags.service-sha
 red-services
Bundle-Vendor: SpringSource Inc.  
Export-Package: org.springframework.showcase.formtags.service,org.spri
 ngframework.showcase.formtags.domain
Import-Library: org.springframework.spring;version="[2.5.4,3.0.0)"
Bundle-Version: 1.0.0.BUILD-20080509155958

The symbolic name of this bundle is org.springframework.showcase.formtags.service-shared-services. Note that the name of the bundle typically describes the package that the bundle primarily exports. If you take a look at the repository/bundles/ext in the dm Server directory, you'll see that names are almost always indicative of the contents of the bundle. For this example, however, we have also appended "-shared-services" in order to avoid possible clashes with other bundle symbolic names. You will see later that the PAR also contains a service bundle.

	Note
	In OSGi, the combination of Bundle-SymbolicName and Bundle-Version is used to uniquely identify a bundle within the OSGi container. Furthermore, when you deploy a bundle to the SpringSource dm Server, for example via the pickup directory, a bundle's filename is also used to uniquely identify it for the purpose of supporting hot deployment via the file system.

As well as exporting types (i.e. the domain classes and service API), the service bundle also publishes an implementation of the UserManager. The actual implementation is StubUserManager; however, that should remain an implementation detail of this bundle.

The fact that this bundle publishes a service is not captured in the /META-INF/MANIFEST.MF, as it is a Spring-DM concept. The following image is of src/main/resources/spring.

As you can see there are two Spring configuration files: module-context.xml and osgi-context.xml.

	Tip
	These names are abitrary; however, they follow an informal convention: module-context.xml typically bootstraps the Spring context (usually delegating to smaller fine grained context files inside another directory), whilst osgi-context.xml contains all the OSGi service exports and references.

The following is a listing of module-context.xml.

<?xml version="1.0" encoding="UTF-8"?>
	
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

    <bean id="userManager"
        class="org.springframework.showcase.formtags.service.internal.StubUserManager"/>

</beans>

As you can see, this simply defines a bean called userManager. The following is a listing of osgi-context.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans
    xmlns="http://www.springframework.org/schema/osgi"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:beans="http://www.springframework.org/schema/beans"
    xsi:schemaLocation="http://www.springframework.org/schema/osgi  
        http://www.springframework.org/schema/osgi/spring-osgi.xsd
        http://www.springframework.org/schema/beans   
        http://www.springframework.org/schema/beans/spring-beans.xsd">

    <service ref="userManager"
        interface="org.springframework.showcase.formtags.service.UserManager"/>
               
</beans:beans>

This single bean definition exports the userManager defined in module-context.xml to the OSGi service registry and makes it available under the public org.springframework.showcase.formtags.service.UserManager API.

The service bundle should now be ready to deploy on the dm Server. So copy /dist/formtags-shared-services-services* to the SERVER_HOME/pickup directory. Output similar to the following should appear in the dm Server's console:

	Note
	The console output has been reformatted to fit this document.

[2008-05-13 13:25:49.415] fs-watcher
    <SPDE0010I> Deployment of 'formtags-shared-services-service-1.0.0.RELEASE.jar' version '0' completed.

The WAR file now needs to access the types and service exported by the service bundle. The following listing is the WAR's /META-INF/MANIFEST.MF which imports the types exported by the service bundle. The Import-Bundle statement has also been extended to import org.springframework.osgi.core, which is necessary in order to load an OSGi-enabled WebApplicationContext.

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.0
Created-By: 1.5.0_13-119 (Apple Inc.)
Bundle-ManifestVersion: 2
Bundle-SymbolicName: org.springframework.showcase.formtags.web-shared-
 services
Bundle-Vendor: SpringSource Inc.
Import-Package: org.springframework.showcase.formtags.domain,org.sprin
 gframework.showcase.formtags.service
Import-Library: org.springframework.spring;version="[2.5.4,3.0.0)"
Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1
 .1.2",org.springframework.osgi.core

In addition to importing the exported types of the service bundle, the WAR must also obtain a reference to the UserManager published by the service bundle. The following image shows the directory structure of the Shared Services WAR.

As you can see in the above image, the Form Tags Shared Services WAR's /WEB-INF/web.xml directory contains a standard web.xml deployment descriptor, applicationContext.xml which defines the configuration for the root WebApplicationContext, and formtags-servlet.xml which defines the configuration specific to the configured formtags DispatcherServlet.

As is typical for Spring MVC based web applications, you configure a ContextLoaderListener in web.xml to load your root WebApplicationContext; however, to enable your WebApplicationContext to be able to reference services from the OSGi Service Registry, you must explicitly set the contextClass Servlet context parameter to the fully qualified class name of a ConfigurableWebApplicationContext which is OSGi-enabled. When deploying Shared Services WARs to the SpringSource dm Server, you should use com.springsource.server.web.dm.ServerOsgiBundleXmlWebApplicationContext. This will then enable the use of Spring-DM's <reference ... /> within your root WebApplicationContext (i.e., in applicationContext.xml). The following listing is an excerpt from /WEB-INF/web.xml.

    <context-param>
        <param-name>contextClass</param-name>
        <param-value>com.springsource.server.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value>
    </context-param>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

The Form Tags Shared Services WAR contains a /WEB-INF/applicationContext.xml file which is the default configuration location used to create the root WebApplicationContext for Spring MVC's ContextLoaderListener.

Note

As already mentioned, in the OSGi world, bundle configuration takes place in the root /META-INF/ directory. Typically Spring-DM powered configuration files will live there as well (e.g., in /META-INF/spring/*.xml). In a WAR, however, the root WebApplicationContext loaded by ContextLoaderListener and the DispatcherServlet's application context typically live in /WEB-INF/. In contrast, the construction of Spring ApplicationContexts is addressed slightly differently in the context of a SpringSource dm Server-based web module, as you will see later.

The following is the listing of the WAR's /WEB-INF/applicationContext.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans
   xmlns="http://www.springframework.org/schema/osgi"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:beans="http://www.springframework.org/schema/beans"
   xsi:schemaLocation="http://www.springframework.org/schema/osgi  
       http://www.springframework.org/schema/osgi/spring-osgi.xsd
       http://www.springframework.org/schema/beans   
       http://www.springframework.org/schema/beans/spring-beans.xsd">

    <reference id="userManager"
        interface="org.springframework.showcase.formtags.service.UserManager"/>
               
</beans:beans>

The single bean declaration is retrieving a service that implements the org.springframework.showcase.formtags.service.UserManager API from the OSGi Service Registry.

	Tip
	You might have been expecting a reference to the service bundle, but that isn't how OSGi works. OSGi provides a service registry, and this bean definition is accessing a service in that registry that meets the specified restriction (i.e. implements the specified interface). This leads to a very loosely coupled programming model: the WAR really doesn't care where the implementation comes from.

	Tip
	What happens if there is no service at runtime? What if there are multiple services that match the criteria? Spring-DM provides a lot of configuration options, including whether or not the reference is mandatory, how long to wait for a service reference, etc. Please consult the Spring Dynamic Modules for OSGi home page for further information.

One of the benefits of programming to interfaces is that you are decoupled from the actual implementation; Spring-DM provides a proxy. This has enormous benefits including the ability to dynamically refresh individual bundles without cascading that refresh to unrelated bundles.

To deploy the WAR, copy /dist/formtags-shared-services-war* to the SERVER_HOME/pickup directory. You should then see console output similar to the following:

	Note
	The console output has been reformatted to fit this document.

[2008-05-13 13:26:37.995] fs-watcher
    <SPSC1000I> Creating web application '/formtags-shared-services-war-1.0.0.RELEASE'.
[2008-05-13 13:26:37.998] async-delivery-thread-1
    <SPSC1001I> Starting web application '/formtags-shared-services-war-1.0.0.RELEASE'.
[2008-05-13 13:26:38.394] fs-watcher
    <SPDE0010I> Deployment of 'formtags-shared-services-war-1.0.0.RELEASE.war' version '0' completed.

Achieving the appropriate level of granularity for your OSGi application is more of an art than a science. It helps to look at the different requirements:

Ultimately the right level of granularity will depend upon your particular application and team.

	Note
	This topic will be revisited in greater detail later in the Programmer Guide in a chapter covering how to build a PAR from scratch.

The service bundle is identical (except for the Bundle-SymbolicName) to that in the shared-services variation of the sample. The PAR has also separated out the domain classes into their own bundle. When layering by technical considerations, it is again somewhat of an unofficial convention to have a .domain bundle.

A web module is a SpringSource dm Server construct which is both a web tier artifact and a valid OSGi bundle.

The following image is of the exploded web module JAR (located inside the distributable /dist/formtags-par.*.jar).

As you can see, at its core, a web module follows the conventions for an OSGi bundle: the root of the bundle contains the META-INF folder as well as compiled Java classes and class-path resources. In addition, the web module contains a MODULE-INF folder in the root of the bundle, which serves as the root for the ServletContext for the deployed web application. The MODULE-INF folder is therefore analogous to the root of a standard WAR file. Note that there is no web.xml deployment descriptor present in the /MODULE-INF/WEB-INF folder, since the dm Server will automatically generate an appropriate web.xml based on web manifest headers. Because a web module is an OSGi artifact, it follows that information about the bundle should be in the /META-INF/MANIFEST.MF. In addition, in order to differentiate a web module from any other type of bundle, you need to specify the Module-Type manifest header and set its value to Web. Without this manifest header, the dm Server's deployment infrastructure would simply deploy a web module as a standard bundle. The following is the /META-INF/MANIFEST.MF for the Form Tags web module.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: FormTags Web Module
Bundle-SymbolicName: org.springframework.showcase.formtags.web-par
Bundle-Vendor: SpringSource Inc.  
Import-Package: org.springframework.showcase.formtags.domain,
 org.springframework.showcase.formtags.service
Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1.1.2"
Import-Library: org.springframework.spring;version="[2.5.4,3.0.0)"
Module-Type: Web
Web-ContextPath: formtags-par

Contrast this to the original web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
     xmlns="http://java.sun.com/xml/ns/j2ee"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="
         http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <servlet>
        <servlet-name>formtags</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>formtags</servlet-name>
        <url-pattern>*.htm</url-pattern>
    </servlet-mapping>

    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>

    <jsp-config>
        <taglib>
            <taglib-uri>http://java.sun.com/jsp/jstl/core</taglib-uri>
            <taglib-location>/WEB-INF/tld/c.tld</taglib-location>
        </taglib>
        <taglib>
            <taglib-uri>http://java.sun.com/jsp/jstl/fmt</taglib-uri>
            <taglib-location>/WEB-INF/tld/fmt.tld</taglib-location>
        </taglib>
    </jsp-config>

</web-app>

The same instructions are specified in the /META-INF/MANIFEST.MF, but they are much more concise. Please read the section called “Web Module Manifest Headers” for detailed information on the requirements of a web module's /META-INF/MANIFEST.MF and supported manifest headers.

	Tip
	The <jsp-config... fragments are not needed by modern day Servlet containers, but they are left in the above listing for consistency with the original web.xml from the Standard WAR sample.

Notice that there are no configuration options in the /META-INF/MANIFEST.MF to indicate the location of the Spring configuration files. This is because, by default, a single WebApplicationContext will be created from all the Spring configuration files in /META-INF/spring/*.xml. This shouldn't be surprising as this is normal behavior for any Spring-DM powered bundle.

Finally we need to construct the PAR itself. The following are the contents of the exploded PAR.

You can see that the PAR itself doesn't contain any resources or Java classes: it simply packages together a related set of bundles as a single, logical unit.

The PAR does however, contain its own /META-INF/MANIFEST.MF.

Manifest-Version: 1.0
Application-SymbolicName: org.springframework.showcase.formtags-par
Application-Version: 1.0.0
Application-Name: FormTags Showcase Application (PAR)

For more information on the contents of the PAR's /META-INF/MANIFEST.MF, please consult Chapter 4, Developing Applications.

You can now deploy the PAR on the dm Server, for example by copying /dist/formtags-par*.par to the dm Server's pickup directory. You should then see console output similar to the following:

	Note
	The console output has been reformatted to fit this document.

[2008-05-13 13:28:57.309] fs-watcher
    <SPSC1000I> Creating web application '/formtags-par'.
[2008-05-13 13:28:57.539] async-delivery-thread-1
    <SPSC1001I> Starting web application '/formtags-par'.
[2008-05-13 13:28:58.016] fs-watcher
    <SPDE0010I> Deployment of 'formtags-par' version '1.0.0.RELEASE' completed.

Navigate to http://localhost:8080/formtags-par to see the welcome page.

	Tip
	Note that the web application's context path is explicitly defined via the Web-ContextPath manifest header in /META-INF/MANIFEST.MF of the web module within the PAR.

There are two New Project Wizards available within Eclipse that allow for creating new OSGi bundle and PAR projects. The projects created by the wizards are deployable to the integrated dm Server instance without requiring any additional steps.

Those wizards create the required MANIFEST.MF file and appropriate manifest headers.

To migrate an existing Java Project to be used with the dm Server, the Tools provide a migration action that adds the required meta data to the project. The migration will not change your project's source layout.

Use the context menu action of a project in the Package or Project Explorer and select "Spring Tools → Convert to OSGi bundle project".

While working with OSGi bundles, one of the most interesting and challenging aspects is defining the package, bundle, and library imports in the manifest and then keeping this in sync with your compile classpath either in Ant and Maven or Eclipse. In most cases you would typically be required to manually set up the Eclipse classpath. Ultimately, the Eclipse compile classpath is still different from the bundle runtime classpath, as normally an entire JAR file is being made available on the Eclipse classpath but not necessarily at runtime due to the explicit visibility rules defined in Import-Package headers.

The Tools address this problem by providing an Eclipse classpath container that uses an SpringSource dm Server-specific dependency resolution mechanism. This classpath container makes resolved dependencies available on the project's classpath but allows only access to those package that are imported explicitly (e.g., via Import-Package) or implicitly by using Import-Library or Import-Bundle.

To use the automatic dependency resolution, an OSGi bundle or PAR project needs to be targeted to a configured SpringSource dm Server instance. This can be done from the project's preferences by selecting the runtime on the "Targeted Runtimes" preference page.

	Note
	In most scenarios it is sufficient to target the PAR project to a runtime. The nested bundles will then automatically inherit this setting.

After targeting the project or PAR you will see a "Bundle Dependencies" classpath container in your Java project. It is now safe to remove any manually configured classpath entries.

The classpath container will automatically attach Java source code to the classpath entries by looking for source JARs next to the binary JARs in the SpringSource dm Server's repository. You can also manually override the source code attachment by using the properties dialog on a single JAR entry. This manual attachment will always override the convention-based attachment.

The Tools provide a Bundle Manifest Editor that assists the developer to create and edit MANIFEST.MF files. The editor understands the SpringSource dm Server specific headers like Import-Library and Import-Bundle and provides content assist features while editing source code. Furthermore a Eclipse Form-based UI is also available.

To open the Bundle Manifest Editor right click a MANIFEST.MF file and select "Bundle Manifest Editor" from the "Open With" menu.

	Note
	Please note that the SpringSource dm Server specific manifest headers appear in green color to distinguish them from those headers defined in the OSGi specification. This also makes navigating much easier.

The content assist proposals in the source tab as well as in the UI-based tabs are resolved from the bundle and library repository of an installed and configured SpringSource dm Server. Therefore it is important to target the project or PAR to a specific dm Server instance to indicate to the tooling which bundle repository to use.

	Note
	If a OSGi bundle project is not targeted to a dm Server instance, either directory or indirectly via a PAR project's targetting, the manifest editor will not be able to provide content assist for importing packages, bundles, and libraries.

The Dependencies tab of the Bundle Manifest Editor enables the user to easily download and install bundles and libraries from the SpringSource Enterprise Bundle Repository"> by using the "Download..." buttons next to the "Import Bundle" and "Import Library" sections.

Hibernate uses CGLIB to dynamically create subclasses of your entity types at runtime. To guarantee that Hibernate and CGLIB can correctly see the types, you must add an Import-Library or Import-Bundle for the Hibernate library or bundle into any bundle that uses Hibernate directly.

Additionally, if other bundles in your application contain types to be persisted by Hibernate, then be sure to specify the import-scope directive of the Import-Bundle header in the bundle that uses Hibernate directly. The import-scope directive tells to implicitly import the bundle into all other bundles that make up the application; this ensures that bundles that indirectly depend on the generated Hibernate classes have access to them, but you do not have to explicitly update their Import-Bundle header, ensuring modularity. For example:

Import-Bundle: com.springsource.org.hibernate;version="[3.2.6.ga,3.2.6.ga]";import-scope:=application

The import-scope directive works only for the bundles in a scoped application (PARs or plans.)