Creating a service

A Manager or Worker expects an IServiceManager to generate services. Each service is identified by a service type (string). Here is how the skeleton manager adds a service:

pluginManager().add(ServiceManager.class, false);
IServiceManager sm
    = (IServiceManager) (pluginManager().lookup(IServiceManager.class)[0]);
sm.add("admin", new AdminServiceProvider(), null, false);

The ServiceManager is an implementation of IServiceManager and is a utility that comes with Beatrix. It is itself a plugin manager, and so an AdminServiceProvider is added to it under the name admin, its service type. The AdminServiceProvider is an ISimpleServiceProvider plugin, which is one of the things the ServiceManager implementation expects. By being added with the name admin, any service requests for the admin service will be passed by the ServiceManager to the AdminServiceProvider.

So a ServiceManager expects either an IServiceProvider or an ISimpleServiceProvider to be plugged into it. The ISimpleServiceProvider looks like this:

public interface ISimpleServiceProvider
{
    /**
     * Create a facet collection for this service label.
     * Called once for each service bind request.
     * @param service_type  Service label
     * @param args  Arbitrary service-specific property argument as contained
     *     in the client's warrant.
     */
    public IFacetCollection createFacetCollection(String service_type, Property args);
    
    /**
     * See if this service is intended for the service's administrator.
     * If so, Beatrix will add its own admin-specific facets.
     * @return True if this service is an admin service.
     */
    public boolean isAdminProvider();
}

The IServiceProvider allows extra information through, so the facet collection can act more intelligently:

public interface IServiceProvider
{
    /**
     * Create a facet collection for this service label.
     * Called once for each service bind request.
     * @param session        Session for which this facet collection was created
     * @param service_type   Service label
     * @param args           Arbitrary service-specific property argument
     *     as pulled out of the client's warrant.
     * @param ap_properties  Properties set by the access point
     */
    public IFacetCollection createFacetCollection(IService session,
                                                  String service_type,
                                                  Property args,
                                                  PropertySet ap_properties);
    
    /**
     * See if this service is intended for the service's administrator.
     * If so, Beatrix will add its own admin-specific facets.
     * @return True if this service is an admin service.
     */
    public boolean isAdminProvider();
}

If isAdminProvider() returns true then the ServiceManager will add its own facets--see Section , next.

A service session (IService) is simply a collection of facets which live and die together. In creating a facet collection the class FacetCollection in package org.jtrix.project.libjtrix.netlet is often helpful. In all cases, the ServiceManager may add its own standard facets to those returned by the service provider plugin, as described in the next section.

A word about sequence: by the time the ServiceManager is called the access point netlet will already be running. That means that the access point is there when the ServiceManager calls the service provider plugin implementing either of the above interfaces.

Look back at Section  to see how the manager's AdminServiceProvider is implemented, and Section  for the worker's SkeletonServiceProvider.