Click or drag to resize

Service Providers

Services in STK Components are a flexible mechanism for accessing the capabilities of an object. Many parts of the library, most notably AccessConstraint, use services to avoid being coupled to a particular class.

Services

Services are interfaces that are discovered through the IServiceProvider interface. IServiceProvider has just one method: getService. This method allows you to obtain an object that implements a particular service for the service provider. The required service is specified by passing its type to the method. So what exactly is a service?

As mentioned previously, a service is simply another interface. It can be any interface. In fact, it can also be a class or value type, though that is less common. IServiceProvider enables us to discover at run-time whether or not a particular instance implements a required service (interface) and to obtain that service so that we can call methods and access properties on it. In some ways it is similar to a cast. If the same class that implements IServiceProvider also implements ILocationPointService (a commonly-used STK Components service), we could simply cast the IServiceProvider to ILocationPointService and then use the methods and properties on that service interface. However, using getService. is much more flexible, however, by allowing for the case that the requested service interface is not directly implemented on the same class that implements IServiceProvider An example may help to clarify this.

First, let's define a simple service interface:

Java
public static interface IMyService {
    /**
     * A service method.  Services can have any number of methods and properties.
     */
    void doSomeOperation();
}

Now let's write a class that provides the service:

Java
public static class MyServiceProviderClass1 implements IServiceProvider, IMyService {
    /**
     * Implements IServiceProvider.getService.
     */
    @Override
    public final Object getService(Class<?> serviceType) {
        if (serviceType == IMyService.class) {
            return this;
        } else {
            return null;
        }
    }

    /**
     * Implements IMyService.doSomeOperation.
     */
    @Override
    public final void doSomeOperation() {
        System.out.println("Doing some operation!");
    }
}

In this case, we've made MyServiceProviderClass implement both IServiceProvider and IMyService. We might determine that a particular service provider implemented IMyService by using run-time type checking using instanceof, but instead it is better to use the getService. method:

Java
private final void doSomeOperationIfAvailable2(IServiceProvider provider) {
    IMyService service = (IMyService) provider.getService(IMyService.class);
    if (service != null) {
        service.doSomeOperation();
    }
}

The benefit of using the service provider interface is that now MyServiceProviderClass is no longer required to implement IMyService directly in order to provide the service. For example, MyServiceProviderClass could be changed to look like this:

Java
public static class MyServiceProviderClass2 implements IServiceProvider {
    /**
     * Implements IServiceProvider.getService.
     */
    @Override
    public final Object getService(Class<?> serviceType) {
        if (serviceType == IMyService.class) {
            return new ImplementMyService();
        } else {
            return null;
        }
    }
}

/**
 * This class actually implements IMyService for MyServiceProviderClass2.
 */
public static class ImplementMyService implements IMyService {
    /**
     * Implements IMyService.doSomeOperation.
     */
    @Override
    public final void doSomeOperation() {
        System.out.println("Doing some operation!");
    }
}

With this change, code using the service provider interface will still be able to find the IMyService service, unlike the direct type-checking approach.

In STK Components, ExtensibleObjects use this flexibility to support extensions. An ExtensibleObject (such as the commonly used Platform) is very simple, but it can be extended with additional capabilities in the form of ObjectExtensions. Other parts of the library, such as Access, work with objects that provide certain services, and those services may be provided by the ExtensibleObject itself or by any of its extensions. If a required service is not available, a ServiceNotAvailableException will be thrown when the service is required.

In practice, Platform provides a conventional, convenient way to define real-world objects, however, because access constraints are defined using IServiceProvider objects, access can be computed using any object that provides the correct services. For example, this very simple class can be used to compute Access using the CentralBodyObstructionConstraint:

Java
public static class Simple implements IServiceProvider, ILocationPointService {
    /**
     * Construct this class with a Point describing the location.
     */
    public Simple(Point locationPoint) {
        m_locationPoint = locationPoint;
    }

    /**
     * Implements IServiceProvider.getService.  We use isAssignableFrom to return any
     * interface that is directly implemented by this class.
     */
    @Override
    public final Object getService(Class<?> serviceType) {
        if (serviceType.isAssignableFrom(getClass())) {
            return this;
        } else {
            return null;
        }
    }

    /**
     * Implements ILocationPointService.getLocationPoint.
     */
    @Override
    public final Point getLocationPoint() {
        return m_locationPoint;
    }

    private Point m_locationPoint;
}

Because the CentralBodyObstructionConstraint only requires the ILocationPointService service, we can implement a simple class that provides only this service and then use instances of the class to create a link to assign to the constraint's ConstrainedLink (get / set).