Server-side Bundle Types: 3 Flavors To Choose From

As we have developed ZipTie we have distilled several patterns out for server-side OSGi bundles. This page will document and describe the three types. If you have any questions about which one you should use, please ask in the development mailing list, forums, or IRC channel.

First, a table:

Bundle Type	Purpose (brief)
Library Bundle	A bundle which wraps an existing library (for example, log4j) or creates a standalone server (for example, FTP or JNDI). May have a bundle activator. May export packages if it wraps a library. Never exports internal (non-thirdparty) packages.
Standard/Service Bundle	May be a Library Bundle and additionally may export internal packages, may register an OSGi Service.
Remote Bundle	Is a Service Bundle that registers an OSGi Service, and has a WSDL file and web service delegate (see below).

Library Bundle

A Library Bundle is an OSGi bundle that does possibly two things (one, the other, or both):

• Wraps a third-party library or libraries. One example is the org.ziptie.jdbc bundle which contains a number of JDBC drivers for different databases. In this case it exports the packages from these third-party libraries that it believes other bundles will need.
• Starts a standalone server. Examples are org.ziptie.net.ftp and org.ziptie.server.jnpserver.

A Library Bundle does NOT export any internal packages whatsoever.

Standard/Service Bundle

A Standard/Service Bundle is an OSGi bundle that may be a Library Bundle but additionally may do possibly two things (one, the other, or both):

• Exports internal packages for use by other bundles.
• Offers an OSGi registered Service. This is typically the case when a singleton of some sort is needed. However, there are alternatives to registering an OSGi Service such as binding a reference into JNDI.

If the internal packages that you are exporting are just wrappers around a third-party library you should examine their necessity. Unless your intention is to restrict what can be done with a library, wrapping a third-party API is almost always a bad idea. In ZipTie we don't try to protect programmers from themselves by not giving them sharp objects. If your intention is to add value on top of a third-party library, we recommend writing "helper classes". In ZipTie we call helpers "Elf's", for example ZAxisElf is used to assist in interacting with Axis. See ZipTie Elves^?.

Services are an important abstraction in OSGi. They allow loose coupling between bundles when one bundle offers a "service" to other bundles. Note that sharing (exporting) classes is not the same as providing a "service". A "service" is typically a singleton whose lifecycle is managed by the bundle that contains it. In fact, a bundle that creates a singleton is obligated to manage it's lifecycle. Rather than simply exporting a factory method or accessor by which other bundles can get a reference to the singleton, as you might do in a typical application, access to the singleton should be provided through an OSGi Service. Compared to a standard application OSGi provides a means by which bundles can be uninstalled, upgraded, and reinstalled without stopping the application.

Therefore, bundles that depend on a singleton service provided by another bundle are discouraged from holding long term references to that singleton because the bundle that contains it may be upgraded while the server is running. If the bundle always obtains a reference to the service singleton through an OSGi Service Tracker, it is guaranteed to get the latest running version of that service.

Understanding this contract is key to implementing a service that can be undeployed and redeployed at runtime. When a bundle is "stopped" (deactivated) before uninstallation it should unregister the service, and should "stop" the singleton in such a way that continued invocations against it by classes holding references result in exceptions being thrown. The bundle will then be uninstalled, replaced, and restarted at which point the bundle runs through it's regular activation by creating the singleton (again) and registering it as a Service. This of course is only the contract from the perspective of the service-providing bundle. Clients of the service must be similarly robust in handling exceptions that might result from a service stopping in the middle of their operation.

Remote Bundle

A Remote Bundle is an OSGi bundle that must be a Service Bundle but additionally exposes a remote (SOAP) API. A Remote Bundle must register an OSGi Service because a registered service is part of the ZipTie Web Service Delegate pattern documented here^?. The registered service may also be used by other bundles within the server but not necessarily so.

If you are not providing a remote service that the ZipTie team has agreed is necessary to our client or external clients, you shouldn't be creating one.

Summary

Server-side Bundle Types
	Library	Standard/Service	Remote
Wraps Library	may	may	may
Start Standalone Server	may	may	may
Exports Internal Classes	no	may	may
Registers OSGi service	no	may	MUST
Defines Remote API	no	no	MUST

Related Pages

Web Service Delegate Pattern^?
Contributing a Web Service
ZipTie Elf Pattern^?