Guidelines for designing Java API for use in the OSGi environment

There is no single best way to design a Java API for use with the OSGi environment. But here is some advice.

Interface-based API design

A good practice is to use interfaces to allow alternative implementations of the interfaces and to limit the use of static methods to a single factory method (or very limited number) to generate a root object from which all other interactions are via interfaces. In a design like this, the root object can be registered as a service in the OSGi service registry and the static factory method can then be reimplemented, when deployed in an OSGi environment, to obtain the root object from the OSGi service registry. This allows replacement implementations if the API. This is the model that was used for JSRs 232 and 246 to co-design the OMA DMT API and is also used by the OSGi XML Parser Service specification to access parser implementations.

Sometimes there can be a religious issue between proponents of interface-based or (final) class-based design. The OSGi environment is mostly predicated on the interface-based design model which separates design from implementation thus allowing many implementors of the API. The interface-based design is a more SOA model of API design.