Designing an API

Our first task is to design. For this we need to have requirements. In this case our underlying goal is to learn distributed OSGi so we want to keep our code small and simple. For this tutorial we’ve chosen a Chat service. In the end we want to be able to send messages to all members in a group. The group is then defined as all users on the computers that are participating in a cluster. To keep it really simple, we assume that we’ve only got one chat user per framework.

So we’ve got two requirements:

• Identify a user
• Send a message to a given user
• Allow the receiver to respond

To identify a user we can use a service property and to send a message we can use a service interface. To be able to respond to a message, we must know the sender. This seems to call for a Message object.

After this long and elaborate process we come up with the following design.

The first class is the message since we need to be able to pass the text and the sender. We use a DTO as base class because this makes debugging less painful. DTO’s automatically have a good toString() method that shows the contents instead of gibberish.

package osgi.enroute.examples.chat.api;
import org.osgi.dto.DTO;

public class Message extends DTO {
	public String from;
	public String to;
	public String text;
}

(Tip: If you copy this without the package, then select your package in Bndtools, and then paste it then Eclipse will create a Java file with the right package and content.)

The second part is an interface for our Chat service.

package osgi.enroute.examples.chat.api;

import org.osgi.annotation.versioning.ProviderType;

@ProviderType
public interface Chat {
	String USER_NAME = "user.name";

	boolean send(Message message) throws Exception;
}

Steps

• In your new workspace create a new Bndtools project com.example.chat.api. (Use a proper name for you, in the example code we use osgi.enroute.examples.chat as prefix but don’t use that one.)
• Create the Message.java and Chat.java sources in the osgi.enroute.examples.chat.api package.
• Double click on the bnd.bnd file and select the Content tab. Make sure the API package is exported. The only import should be org.osgi.dto.