Start page / Plug-In Development / Implementation and Deployment / Using FirstSpirit APIs / Services
Services
Module developers may design services that provide background functionality during the server's or a client program's run-time.
The FirstSpirit Developer API provides integration points for two scopes of service:
- Server-wide services provide functionality that should be available across all projects maintained on a FirstSpirit server.
- Client services provide functionality within the scope of a single client session, i.e. a specific SiteArchitect or ContentCreator session.
It is possible to request a service using a services broker. This agent can be used to obtain either of the two service types.
Service Types
Server-Wide Services
Service plug-ins that should provide server-wide functionality implement the Service interface and must be referenced in a <service> component in a FirstSpirit Module's module.xml file.
Once installed using a FirstSpirit Module, a service may be configured to start automatically during server start-up or may be manually started using the Modules page of the server configuration panel in Project and Server Configuration (see FirstSpirit Manual for Administrators, chapter 7.3.11).
 |
Because services are obtained by class name, each server-wide service that is to be installed on a single, specific server must be a separate class implementation of the Service interface. |
Client Services
Client services provide functionality within the scope of a single client session (e.g. one SiteArchitect instance run by a specific user) and are registered programmatically as needed.
These client services are not provided as plug-ins, nor do they have to implement a specific API interface to be loaded. Rather, module developers should provide a Java class in a FirstSpirit Module that is then registered using the ClientServiceRegistryAgent. Registration and unregistration of a client service should be handled by a permanent plug-in which is initialized after project selection takes place during client start and is stopped as the client program exits.
|
Because services are obtained by class name, each client service object registered during a single, specific client session must be an instance of a unique class. |
Registering a client service
Assuming the class MyClientServiceClass implements functionality that should be used as a client service, the following code snippet may be used to register an object instance of this class:
final MyClientServiceClass myClientServiceObject = new MyClientServiceClass();
final ClientServiceRegistryAgent clientServiceRegistryAgent = context.requestSpecialist(ClientServiceRegistryAgent.TYPE);
clientServiceRegistryAgent.registerClientService(MyClientServiceClass.class, myClientServiceObject);
Unregistering a client service
Once a client service is no longer needed, it should be unregistered. For this process, the ClientServiceRegistryAgent only requires the class of the service that is to be unregistered:
final ClientServiceRegistryAgent clientServiceRegistryAgent = context.requestSpecialist(ClientServiceRegistryAgent.TYPE);
clientServiceRegistryAgent.unregisterClientService(MyClientServiceClass.class);
Obtaining and Using Services
Both server-wide and client services may be obtained using the ServicesBroker, which is available in most contexts (see Accessing FirstSpirit Functionality).
final ServicesBroker servicesBroker = context.requestSpecialist(ServicesBroker.TYPE);
try {
final MyClientServiceClass myClientServiceObject = servicesBroker.getService(MyClientServiceClass.class);
} catch (ServiceNotFoundException e) {
// Handle cases in which the requested service cannot be obtained.
}