The SymbolicName of a bundle is the only mandatory header that an OSGi bundle must contain. This header supports a directive to indicate if the bundle should be treated as a singleton, or that only one bundle of this name should exist in the framework:

Bundle-SymbolicName: com.packt.osgi.starter;singleton:=true

Along with Bundle-SymbolicName, this attribute uniquely identifies a bundle in the framework. Additional attention needs to be paid to OSGi versioning as the OSGi environment will pay strict attention to version requirements as defined by the bundle's import and export packages.

The generally adhered practice for versioning is as follows:

Major.Minor.Micro.Qualifier

A bundle declares its dependencies through this header. The semantics surrounding the version attribute merits additional attention; the use of (' and ') denotes exclusive values, and [' and '] denotes inclusive values. These braces are used to denote version ranges. There are five cases we must examine:

This header is used to tell the framework if any packages are being provided by this bundle to the environment. Package names should be fully qualified and include a version attribute. When the version attribute is not provided, the version is defaulted to 0.0.0.

Export-Package: com.packt.util, com.packt.osgi;version="1.0"

Now that we have a deeper understanding of bundles, let's look closer at their life cycle.

Bundles came into existence in an OSGi framework in the installed state. A bundle in this state cannot be immediately started, as the preceding diagram depicts that there is no direct transition from the installed state to the starting state. An installed bundle is also not active. There are three possible transitions: the bundle may become resolved, uninstalled, or refreshed.

Having a bundle installed to the OSGi framework does not mean it is ready to be used; next we must resolve its dependencies.

Entering the resolved state requires the framework to ensure that all the dependencies of a bundle have been met. Upon having its dependencies ensured, the bundle is now a candidate to be transitioned to the starting state. A resolved bundle may be refreshed, transitioning the bundle back to the installed state. A resolved bundle may also be transitioned to the uninstalled state. A resolved bundle is not active; however, it is ready to be activated.

A resolved bundle may be started. The starting state is transitory; the framework is initializing the resolved bundle into a running active state. In fact, the transition from the starting to active state is implicit.

The bundle is fully resolved, providing and consuming services in the OSGi environment. To perform any more transitions on an active bundle, it must first be stopped.

Bundle updates occur when the framework is instructed to re-evaluate a bundle's dependencies; this action is synonymous with refreshing a bundle. When this action occurs, all of the wiring to and from the bundle is broken, so care must be taken before refreshing to avoid starting a bundle storm (one bundle refreshing causes a domino effect of other bundles refreshing).

The location option allows you to update the bundle via its predefined updated location or to specify a new location to find bundle updates.

Stopping a bundle transitions it from the active to the resolved state. The bundle can be restarted while it remains in the resolved state.

Uninstalling a bundle transitions an installed or resolved bundle out of the OSGi environment; however, the bundle is not removed from the environment! Why is this? While the bundle is no longer available for use, references to the bundle may still exist and used for introspection.

To help leverage these states in your bundles, the OSGi specification provides a hook into your bundle state via the Activator interface.

A bundle may optionally declare an Activator class implementing the org.osgi.framework.BundleActivator interface. This class must be referenced in the bundle manifest file via the BundleActivator header. Implementing the activator allows the bundle developer to specify actions to be performed upon starting or stopping a bundle. Generally, such operations include gaining access to or freeing resources, and registering and unregistering services.

The entry in manifest.mf will appear as follows:

Bundle-Activator: com.packt.osgi.starter.sample.Activator

When building with maven-bundle-plugin, the following configuration instruction is added:

<Bundle-Activator>
com.packt.osgi.starter.sample.Activator
</Bundle-Activator>

The process can be seen in the following screenshot:

These Service Hooks are not intended for regular bundle developers, they are there to facilitate things like distributed OSGi. Service Hooks are not to be confused with the service engine publish, find, and bind methods.

A common usage scenario for a Service Hook is in an OSGi system where all communication is normally tunneled through services; this makes it a very interesting place for a handler to intercept the service communications. The hooks allow you to install handlers that can help facilitate things like proxying, security, authentication, and other functions more or less like interceptors.

This behavior will be completely transparent to the consumer of the service that will only be interacting with the OSGi service registry.

To proxy an existing service for a specific bundle, we would be required to perform the following steps:

Properties here are very simple; we really are only talking about the same interface and potential filters necessary. When these criteria are met, a proxy can pose as the original service and add additional work to the registration.

OSGi Service Platform Release 4 Version 4.2 specifications introduced the Blueprint Container specification.

This specification describes how declarative programming and dependency injection is done in an OSGi container. There are two separate implementations of the Blueprint specification, one from the Apache Foundation—Apache Aries Blueprint—as well as one from the Eclipse Foundation—Eclipse Gemini. The examples in this book and the demonstration code were tested using the Apache Aries version.

Blueprint is built around an OSGi extender pattern. Once a bundle has resolved its dependencies, it is up to the Blueprint extender to do the following:

A Blueprint file's basic building blocks are the beans, shown as follows:

Beans can also have properties; these properties can be references or values, as shown in the following screenshot:

A Blueprint Container also provides a model for interaction with the OSGi service registry allowing you to define beans that can then be exported.

As seen from earlier examples, services are exported and found via their interface class.

Once we have a service that we want to consume, we can do so from another bundle by referencing it across the service registry with a reference tag, as follows:

These are the basic building blocks in Blueprint; the specification also provides for namespace handlers so that developers can extend the container with a specific behavior for named beans. This is used quite extensively in projects such as Apache Camel, Apache CXF, and of course Apache Aries.

Utilizing the namespace handler techniques, the container is enriched with web service wiring, context resolution, configuration admin integration, and property injection.

One of the most powerful of all services in the OSGi environment is the Configuration Admin service. It is a "merge" between the simple paradigm of reading configuration data at startup time combined with the fact that the said data can and will change during an application's life cycle. In a fully dynamic environment, your configuration can change at any time and you're expected to react to these changes; the Configuration Admin API classes allow you to do exactly this; your bundles will be notified of new, updated, and removed configuration data.

This also allows for some very useful patterns you can build on top of org.osgi.service.cm.Managed ServiceFactories. Apache Felix provides configuration interfaces via fileinstall as well as the webconsole.

A whiteboard pattern is a very well documented pattern that has a detailed description on the OSGi forum, http://www.osgi.org/wiki/uploads/Links/whiteboard.pdf. It is somewhat similar to an extender pattern but relies on the OSGi service registry instead of raw bundles.

Idea

Java has, since 1.0, had an event platform. These events unfortunately could lead to fairly cumbersome development cycles with more than 130 events and adapters available already in Java 1.3. The whiteboard pattern provides events in a simple manner without forcing a listener pattern to be implemented. This is done relying on the OSGi service registry for informational messages and further processing.

Implementation

A whiteboard pattern in its simplest form is implemented via BundleActivator and the registration of a ServiceTracker object at http://www.osgi.org/javadoc/r4v42/org/osgi/util/tracker/ServiceTracker.html.

ServiceTracker gives us an implementation that correctly handles all the details of listening to ServiceEvents and getting and ungetting services. It is also a thread-safe class so it will aid bundle developers in what otherwise would be a fairly cumbersome process involving quite a bit of manual checking of services and registrations.

The whiteboard service tracker bundle subscribes to service registration information, as shown in the following screenshot:

Here we are registering ServiceTracker on a bundle context, we give it an HttpServlet interface to match against and by providing a null as the last argument we are saying that we want to be notified of every single event.

With our listener installed, we are now ready to start looking for these services being added, removed, suspended, and so on. If we say that a servlet example would be deployed in blueprint for the sake of argument, that deployment would look something like the following screenshot:

It would now be up to our ServiceTracker bundle to grab this service, and publish this in a servlet container under the path /myservlet.

As you can see, this is a very graceful, not to mention useful, "Factory" instantiation pattern that will allow for full dynamism, thanks to the nature of OSGi bundles and the service registry.

The OSGi extender pattern is one of the most used and implemented strategies for framework enhancement. It is a pattern that models itself towards extensive enhancement of deployments and is used to provide EE behavior in the core of many of today's most advanced Java containers. An extender pattern allows the enhancing of bundles with a custom life cycle that will react as bundles come and go. Prominent implementations of the extender pattern are Apache Aries Blueprint and Spring Dynamic Modules; they both rely on this pattern to control their application participants.

Implementation

The OSGi life cycle allows a bundle, very much like the activator, to participate and listen to events regarding the installation, update, and removal of other bundles. This life cycle is dynamic in nature. If we were to just gather the event information, we'd do so utilizing a normal org.osgi.framework.BundleListener interface. Refer to http://www.osgi.org/javadoc/r4v43/core/org/osgi/framework/BundleListener.html.

The regular BundleListener is an asynchronous ordered implementation that cannot be called concurrently; it is up to the framework to call our BundleListener interface and dispatch information to us. As seen from this description, the BundleListener interface lends itself to logging and informational purposes but there is also org.osgi.framework.SynchronousBundleListener. Refer to http://www.osgi.org/javadoc/r4v43/core/org/osgi/framework/SynchronousBundleListener.html.

This listener actually allows us to take an action on these events, as seen in JavaDocs for this class. Unlike normal BundleListener objects, SynchronousBundleListeners are synchronously called during bundle life cycle processing.

The bundle life cycle processing will not proceed until all SynchronousBundleListeners have completed. SynchronousBundleListener objects will be called prior to BundleListener objects. The following diagram shows the extender pattern:

Armed with this class, we suddenly have a fairly powerful mechanism for building completely new flows for our bundles. If we go back to the Apache Aries Blueprint mentioned earlier, in essence it is really a listener, and when our bundle goes active, it will look for files in OSGI-INF/blueprint ending in .xml.

The synchronous invocation gives us the ability to do things before the actual event has passed. So we can perform initialization, register services, evaluate files, check for resources, and manipulate bundle information so that we can fully take control of the execution environment.

Depicted on the left, the extender bundle that is controlling the flow of information is going to utilize org.osgi.framework.BundleEvent as it receives and looks for bundles containing Type A information. Once it finds a matching bundle, the extender has control of the bundle providing the event, so it can instantiate classes, set up application contexts, and register further metadata and information before handing back control of the event to the framework.