Each application module should be packaged as an OSGi bundle. A bundle is essentially a jar file with a META-INF/MANIFEST.MF file containing a series of headers recognized by the OSGi Service Platform. See the OSGi Service Platform Core Specification section 3.2 for details. Some OSGi implementations may support exploded jar files, but the format remains the same.

The Spring extender recognizes a bundle as "Spring-powered" and will create an associated application context when the bundle is started and one or both of the following conditions is true:

In addition, if the optional SpringExtender-Version header is declared in the bundle manifest, then the extender will only recognize bundles where the specified version constraints are satisfied by the version of the extender bundle (Bundle-Version). The value of the SpringExtender-Version header must follow the syntax for a version range as specified in section 3.2.5 of the OSGi Service Platform Core Specification.

In the absence of the Spring-Context header the extender expects every ".xml" file in the META-INF/spring folder to be a valid Spring configuration file, and all directives (see below) take on their default values.

Tip

An application context is constructed from this set of files. A suggested practice is to split the application context configuration into at least two files, named by convention modulename-context.xml and modulename-osgi-context.xml. The modulename-context.xml file contains regular bean definitions independent of any knowledge of OSGi. The modulename-osgi-context.xml file contains the bean definitions for importing and exporting OSGi services. It may (but is not required to) use the Spring Dynamic Modules OSGi schema as the top-level namespace instead of the Spring 'beans' namespace.

The Spring-Context manifest header may be used to specify an alternate set of configuration files. The resource paths are treated as relative resource paths and resolve to entries defined in the bundle and the set of attached fragments. When the Spring-Context header defines at least one configuration file location, any files in META-INF/spring are ignored unless directly referenced from the Spring-Context header.

The syntax for the Spring-Context header value is:

Spring-Context-Value ::= context ( ',' context ) *
context ::= path ( ';' path ) * (';' directive) *

This syntax is consistent with the OSGi Service Platform common header syntax defined in section 3.2.3 of the OSGi Service Platform Core Specification.

For example, the manifest entry:

Spring-Context: config/account-data-context.xml, config/account-security-context.xml

will cause an application context to be instantiated using the configuration found in the files account-data-context.xml and account-security-context.xml in the bundle jar file.

A number of directives are available for use with the Spring-Context header. These directives are:

The table below summarizes the differences between the manifest configuration options in Spring DM and Blueprint Container:

The manifests below are equivalent in terms of settings:

Bundle-SymbolicName: org.example.account.bundle
Spring-Context: config/account-data-context.xml, config/osgi-*.xml;    
 wait-for-dependencies:=true;
 timeout:=10                                                           

	All Spring DM specific attributes are grouped under Spring-Context header.
	Timeout specified in seconds.

Bundle-SymbolicName: org.example.account.bundle;                       
 blueprint.graceperiod:=true;
 blueprint.timeout:=10000                                              
Blueprint-Bundle: config/account-data-context.xml, config/osgi-*.xml   

	Blueprint settings are spread between Bundle-SymbolicName and Blueprint-Bundle.
	Timeout specified in milliseconds.

Aside from bundle-specific configurations, Spring DM allows the core extender generic behaviour be configured. This is useful when embedding Spring DM inside a managed environment or when a bundles-wide functionality is desired. To allow for extensible configuration, the extender relies on OSGi fragments to override its defaults. The extender looks for all XML files under META-INF/spring/extender folder in its bundle space and assembled them into an application context (of type OsgiBundleXmlApplicationContext) that is used internally as its configuration. To override a default setting of the extender, look up the appropriate bean name from the table below, define it in a suitable manner and then attach it as a fragment to the spring-osgi-extender.jar, using:

Fragment-Host: org.springframework.osgi.extender

The following beans are currently recognized by the extender:

From the extenderProperties bean, the following properties are recognized:

	Note
	Since an application context is used, the full power of the Spring IoC container can be used for creating the extender configuration beans

7.3.1. Listening To Extender Events

There are cases when the failure or succesful startup of an application context needs to be acknowledged for logging purposes (for example). For these cases, Spring DM offers a dedicated package org.springframework.osgi.context.event which defines the events that OSGi application contexts can send during their lifecycle. At the moment, the following events are available:

Table 7.4. Spring DM build-in events

Event	Explanation
OsgiBundleContextRefreshedEvent	Published when an OSGi application context has been succesfully initialized or refreshed (e.g. using the refresh() method on the ConfigurableApplicationContext interface). There are no guarantees on how many times this event might be received during the lifecycle of an application context - this is left up to the used implementation.
OsgiBundleContextFailedEvent	Published when an OSGi application context is closed due to a failure. This event can appear any time during the lifecycle of an application context - before, during or after refresh. Usually the cause indicates an error in the configuration - syntax typo, incorrect wiring, missing bean and so forth.
OsgiBundleContextClosedEvent	Published when an OSGi application context is closed after a successful refresh (normally issued a Spring bundle is being stopped).

Parties interested in receiving these events should implement OsgiBundleApplicationContextListener and then publish it as an OSGi service. The Spring DM extender will automatically detect the listener and will send the events to it. By taking advantage of the OSGi service registry, the extender decouples the received from the event publisher and moreover, makes the registration/unregistration process easier. For example, there is nothing special a client should do to unregister the listener - simply stopping the bundle will automatically unregister all its published services (including the listener), an event which will detected by the extender which will remove the listener. Of course, it is also possible for the client to unregister the listener manually during a bundle lifecycle.

	Note
	The Spring DM events semantics are slightly different then Spring's. The OSGi events are not sent to beans inside the causing application context but to other parties (possible beans in other application contexts) interested in monitoring its behaviour.

The Spring Dynamic Modules project provides a number of bundle artifacts that must be installed in your OSGi platform in order for the Spring extender to function correctly:

In addition, the Spring Framework provides a number of bundles that are required to be installed as dependencies. As of release 2.5 of the Spring Framework, the Spring jars included in the Spring distribution are valid OSGi bundles and can be installed directly into an OSGi platform. The minimum required set of bundles is:

In additional the following supporting library bundles are required. OSGi-ready versions of these libraries are shipped with the Spring Dynamic Modules distribution.

Spring 2.0 introduced (among other things) easier XML configuration and extensible XML authoring. The latter gives the ability of creating custom schemas that are discovered automatically (in non-OSGi environment) by the Spring XML infrastructure by including them in the classpath. Spring DM is aware of this process and supports it in OSGi environments so that custom schemas are available to bundles that use them without any extra code or manifest declaration.

All bundles deployed in the OSGi space (whether they are Spring-powered or not) are scanned by Spring DM for custom Spring namespace declaration (by checking the bundle space forMETA-INF/spring.handlers and META-INF/spring.schemas). If these are found, Spring DM will make the schemas and the namespaces available through an OSGi service that will be automatically used by Spring-powered bundles. This mean that if you deploy a bundle that uses a custom schema, all you have to do is deploy the library that provides the namespace parser and the schema. Bundles that embedded inside their classpath libraries that provide custom schemas will use these over those available in the OSGi space. However, the namespaces of the embedded libraries will not shared with other bundles, that is, they will not be seen by any other bundle.

In short, when using Spring DM, custom Spring namespaces are supported transparently without any additional work. Embedded namespace providers will have priority but will not be shared, as opposed to providers deployed as bundles which will be seen (and used) by others.

Refer to the OSGi Service Platform for details of the Import-Package and Export-Package manifest headers. Your bundle will need an Import-Package entry for every external package that the bundle depends on. If your bundle provides types that other bundles need access to, you will need Export-Package entries for every package that should be available from outside of the bundle.

Important

Both Export and Import-Package have a crucial role in defining a bundle class space. If used incorrectly, the bundle might not be able to load certain classes or resources, load incorrect versions or even load multiple versions at the same time which usually result in ClassCastException, NoClassDefFoundError or LinkageError. We strongly recommend that you get familiar with the basics and, at least for starters, use tools (such as Bundlor or BND) for creating proper OSGi manifests.

Many enterprise application libraries assume that all of the types and resources that comprise the application are accessible through the context class loader. While most developers do not use the context class loader, the loader is used heavily by application servers, containers or applications that are multi-threaded.

In OSGi R4, the set of types and resources available through the context class loader is undefined. This means that the OSGi platform does not make a guarantee of the thread context class loader value or in other words, it does not manage it.

Thus code (for example libraries) that performs manual class loading or that generates new classes dynamically can cause problems when executed inside an OSGi environment.

Spring Dynamic Modules guarantees that during the creation of an application context on behalf of a given bundle, all of the types and resources on the bundle's classpath are accessible via the context class loader. Spring Dynamic Modules also allows you to control what is accessible through the context class loader when invoking external services and when servicing requests on exported services. See Chapter 8, The Service Registry for details on this.

Work is underway in the OSGi R5 timeframe to provide standardized support for dealing with generated classes and implicit class path dependencies introduced by third-party libraries. In the interim you may need to rely on workarounds such as the DynamicImport-Package manifest header, or the facilities provided by specific OSGi implementations such as Equinox's buddy mechanism. The Spring Dynamic Modules documentation contains more details on known issues with common enterprise libraries and the workarounds.

Your chosen OSGi platform implementation should be able to provide you with a good deal of information about the current status of the OSGi environment. For example, starting Equinox with the -console argument provides a command-line console through which you can determine which bundles are installed and their states, the packages and services exported by bundles, find out why a bundle has failed to resolve, and drive bundles through the lifecycle. All the OSGi platform tested, provide their own logging, which can be enabled and customized through dedicated settings. For more information, please refer to OSGi platforms documentation.

In addition, Spring itself and the Spring Dynamic Modules bundles contain extensive logging instrumentation that can help you diagnose problems. The recommended approach is to deploy the Simple Logging Facade for Java (slf4j) slf4j-api.jar and slf4j-log4j13.jar bundles (the jar files distributed by the project are valid OSGi bundles). Then you simply need to create a log4j.properties file in the root of your bundle classpath.

Managed, OSGi-aware runtime environments such as dmServer provide additional logging and insight not just for the bundle at hand, but also regarding the application context and the VM among other things.

Note that Spring Dynamic Modules uses commons-logging API internally which means that its logging implementation is fully pluggable. Please see the FAQ and Resources pages for more information on other logging libraries besides log4j.