Start page
Start page

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).

Important 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.

Important 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.
}

© 2005 - 2015 e-Spirit AG | All rights reserved. | Last change: 2013-12-09