Collaborative Service Definitions for OSGi

Introduction

The Collaborative Service Definitions (CSD) is an effort to share more service definitions. The OSGi Service Compendium specifies a large number of thoroughly specified services that have been proven with a reference implementation and can be tested with a test suite. However, the µService programming model of OSGi is not just useful with compendium services, any project benefits by building around µServices, and many projects do. Many of the services developed in projects have their definition inside the projects and are not shared with the world. This site attempts to collect those service definitions to allow different projects to share them. Service definitions on this site can be used in projects. Any services that become highly popular will be submitted to the OSGi for formal specification but this is not a requirement.

Using the CSDs

If you want to use a CSD you can search the repository. Each CSD has its own page that introduces the purpose of the CSD and provides a link to the JAR containing the Java API. You can use this JAR with your favorite build tool or IDE, appropriate URLs are provided. The CSD also links known implementations.

Versioning

CSDs evolve over time. To handle their evolution, they are versioned according to the standard OSGi versioning policy. That is, providers of such a service must ensure to import on the minor version ([1.1,1.2)). Clients of such a service must import on the major version ([1,2)). Though backward compatibility is important it is in the nature of CSDs that they will evolve and sometimes in backward incompatible ways. Not properly importing these CSDs will break your code in the future.

Adding a CSD

Adding a CSD is open for anybody, you do not have to be an Apache Felix submitter. It all starts with a service that you've found useful. Though we love lots of CSDs we want them to be high quality and that starts with at least one implementation. Also discuss the idea with some other people to find out how popular your service will be. Without experience of using a service you will just plain get it wrong. If you have a CSD, you can start by putting it in the org.apache.felix.service namespace. Look at the existing list and pick a name. Write your CSD as Java code. You're allowed to use Java 5 and 6 but realize that the lower the Java version the more people can use it; embedded is still mostly at 1.4. When you write your code the use the following guidelines:

• Write your introduction as Javadoc in package-info.java. Explain why is it necessary, what abstraction does it provide, what responsibilities it provides, for who it is, etc. This introduction is your sales talk for other people to use that service and later for people to find implementations for that service. Do not make it too long but make sure it is readable and clearly defines the responsibilities of the service.
• Write your interfaces and classes. This code must be very well documented, look for the OSGi Compendium services as good examples. Create proper Javadoc and for each method ask yourself if you answered all potential questions when somebody out of nowhere lands on that method description.
• Define the names type of the service properties as constants (the Definition utility is very handy for this).
• Clearly define the PID(s) and their properties for the configuration of the services using Configuration Admin. Realize this is public API.
• Make your service specification cohesive, do not mix concepts in a single package. For example, factory, builder, and specification classes are meta to domain objects, it is usually better to separate them into separate packages.
• Optionally provide a Definition class for your service in the org.apache.felix.servce.<...>.spec package. Definition classes allow type safe registration and searching of services and are a convenient place to define constants for service and configuration properties.
• Mark the concurrency aspects with the proper Javadoc annotations developed by Brian Goetz. ###link###

While doing all this, remember that services work so well because they allow you to maximize cohesion and allow you to minimize coupling, they do not automatically provide those good qualities. Therefore think deep if the service is really about a single subject/topic. A good check is the one line Javadoc introduction for the service, does it contain "and"? If so, not a good sign and you might want to split the service. Couplings are external dependencies. Every non-java package you use increases the complexity of your service. Do you really need that coupling? Can you work around it. Please realize the trade off here, couplings are not bad by definition but they cost and you have to make the trade off if that benefit is worth the cost.

Provide examples. You can place any example snippets in:

org.apache.felix.snippets.<...>

All your CSD packages must be versioned and that version must be rigidly maintained. You must specify the version in the packageinfo file. This file must contain:

 version 1.0.0

Where 1.0 is the appropriate version. Any (and we mean any) change to the package must result in a version change. Changes that do not affect clients or implementers can increment the micro version. Changes that affect the implementer only (and that is almost any change) must increment the minor part. Changes that affect the clients in a non-backward compatible way must increment the major part. Good versioning is crucial for CSDs to succeed.

Once you're happy with the service package submit it as a patch when you're not a committer (by attaching it to an issue using the Felix issue tracker) or commit it. The patch or commit will be reviewed and when accepted will be made available on the CSD for OSGi website. Any new versions you want to release to this service require a repeat of this process.

The documentation of your CSD is generated from the Javadoc and then placed on the website.

You can send any question to ### separate mailing list??? ###