keith thompson

In Darkstar, managers provide many of the application level APIs. By creating a new manager one can extend the API set with functions that application could not otherwise implement. Underneath the managers, not directly visible to the application, are corresponding services. Services provide the functions needed by their managers and have access to the other services in Darkstar that applications do not have access to.

The example manager described below will be built on a service which will use the DataService to provide the desired functionality.

A Darkstar service must implement the com.sun.sgs.service.Service interface and have a specific constructor. Ignoring Javadoc, import and package statements, the class declaration and constructor look like this:

public class ObjectAccessService implements Service {
    private final DataService dataService;

    public ObjectAccessService(Properties properties,
                               ComponentRegistry systemRegistry,
                               TransactionProxy proxy) {
        dataService = proxy.getService(DataService.class);

The three arguments to the constructor are the properties, system component registry, and the transaction proxy. The example service does not require any properties or system components but it does require the data service which is accessed through the transaction proxy. The two new service methods, createReferenceForId() and nextObjectId() call through to the data service and provide the functions needed by the manager:

The three methods defined by the Service interface, getName(), ready(), and shutdown() are described in Service's documentation and for this service require fairly straightforward implementations:

    public boolean shutdown() {
        return true;
    }
The manager does not need to implement any particular interface and in this case the implementation is even more compact than the service:

public class ObjectAccessManager {
    private final ObjectAccessService service;

    public ObjectAccessManager(ObjectAccessService service) {
        this.service = service;
    }

When a manager is created it is passed a reference to its backing service, in this case the ObjectAccessService. The two new calls available to the application are createReferenceForId() and nextObjectId(). Both methods call directly to the underlying service (and then onto the data service):

    public ManagedReference<?> createReferenceForId(BigInteger id) {
        return service.createReferenceForId(id);
   }

   public BigInteger nextObjectId(BigInteger objectId) {
       return service.nextObjectId(objectId);
   }
Note that since both methods follow a direct path to the data service, their definitions can taken from the DataService interface.

In order to make the new manager available to the application, both it and its service needs to be installed in the Darkstar server. This is done by adding the following two items to the server's configuration file:

com.sun.sgs.services=mypackage.ObjectAccessService
com.sun.sgs.managers=mypackage.ObjectAccessManager

Obviously the manager and server classes need to be in the class-path of the server.

With the manager installed it is a simple matter for the application to access it:

ObjectAccessManager accessManger = AppContext.getManager(ObjectAccessManager.class);

Though this is an extremely simple example, it does provide a means to iterate over the objects in the system, by their identifier, and given an identifier, get the object. It also demonstrates the basic manager-service operation in Darkstar.