Aperi Data Server R2 Extensibility

Introduction

NOTE: This page is still very much a work in progress!

The purpose of this page is to present information on how to extend the functionality provided by the Aperi Data Server. More than anything, this page should be viewed as a series of HOWTOs. It assumes knowledge of key Equinox / OSGi concepts (e.g., plugins, extension points, etc.), as well as a basic understanding of Aperi’s architecture. Below is a brief, high-level, outline of the topics this page addresses:

• General Infrastructure
  • Deployment
  • Serviceability
• Service Infrastructure
• Resource Attribute Infrastructure
• Job / Schedule Infrastructure
• Alert Infrastructure

As with all software projects, Aperi will evolve over time. However, the content of this page is specific to its 0.2 release. This page should be viewed as a living document. It will evolve in response to the needs of developers looking to build on top of the Aperi platform. Please feel free to share any questions, comments, and / or concerns on either the Aperi Development mailing list or the Aperi newsgroup. Any and all feedback is welcome.

Service Infrastructure

The key service infrastructure building blocks are service providers, request handlers, request objects, and response objects. Service providers handle thread management for, and coordinate message log output across, a set of request handlers. Request handlers are responsible for processing incoming request objects and producing corresponding response objects. This section focuses on answering the following questions related to the service infrastructure:

• How do you create and register a new service provider?
• How do you create and register a new request handler?
• How do you create a custom request / response object?

How do you create and register a new service provider?

Before getting into a discussion of how to create and register a new service provider, it is important to note that the Data Server ships with the following service providers:

• AgentSvp. The request handlers associated with the Agent service provider processes non-GUI originated requests. They take care of requests submitted by agents and handle several internal server-side jobs.
• CimomSvp. The request handlers associated with CIMOM service provider are responsible for requests and internal server-side jobs that require communication with a CIMOM. The CIMOM service provider is intended to be used to process long running requests, isolating them from others that can be processed more quickly.
• GuiSvp. The request handlers associated with the GUI service provider are designed to handle requests submitted by the GUI.
• SchedulerSvp. The request handlers associated with the Scheduler service provider handle requests related to the Data Server scheduler (e.g., requests to obtain information about long running jobs, etc.).
• ServerSvp. The request handlers associated with the Server service provider handle generic management tasks (e.g., service provider startup / shutdown, agent registration, etc.).

The service providers mentioned above are defined in the org.eclipse.aperi.server.svp package of the org.eclipse.aperi.server.data plugin. Their availability largely eliminates the need to put together new service providers. Service providers and request handlers are loosely coupled. A new request handler can be associated with any existing service provider.

All the above said, there may be certain situations that require the creation and registration of a new service provider. For example, there may be a desire to logically isolate some set of request handlers from all of the other request handlers in the Data Server. Or, there may be a requirement that the message log output produced by some set of request handlers appear in a specific file. Whatever the case may be, creating and registering a new service provider can be accomplished by carrying out the following steps:

• [1] Define a request type constant for the service provider. It must be a string value unique to, at least within the JVM, the service provider. In support of uniqueness, the use of a Java-based naming scheme is recommended. For example, the request type constant associated with the Agent service provider is org.eclipse.aperi.agent.svp.AgentSvp, the name of the Agent service provider implementation class. The request type constant should be placed in a class defined in a package that is exported by the plugin in which it resides. Request type constants are used to set the typeCode instance variable of request objects (instances of the Request (org.eclipse.aperi.request) class), which is involved in routing requests, within the Data Server, to the appropriate service provider. Here is a sample request type constant definition:

Insert sample code...

• [2] Define a request type metadata source for the service provider. There are three key pieces of metadata associated with request type constants. First there is the internal name, used to identify the service provider in trace output and error messages produced by the Data Server. Next, there is the external name, used to identify the service provider in the list of Data Server services presented in the GUI. And finally, there is the log prefix, used to name the message log files associated with the service provider. The metadata source should implement the IMetadataSource (org.eclipse.aperi.constants.metadata) interface and look like the RequestTypeSource (org.eclipse.aperi.constants.core.metadata) class. The plugin containing the metadata source must import the appropriate packages from org.eclipse.aperi.common. A request type metadata source might look something like this:

Insert sample code...
Present GUI screenshot (list of Data Server services)...

• [3] Register the request type metadata source associated with the service provider. The org.eclipse.aperi.common plugin defines the requestTypeSource extension point for registering request type metdata sources. The following XML snippet would be added to the plugin.xml of the plugin containing the metadata source presented above:

Insert sample XML content...

Request type metadata is used not only in the Data Server, but also in the Agent and the GUI. That means that the request type metadata source must be registered in multiple JVMs. Given that requirement, it makes sense to place the request type constant, and its associated metadata source, in a plugin separate from the one containing the actual service provider implementation. For example, the request type constants and metadata sources associated with the service providers that ship with the Data Server are defined in the org.eclipes.aperi.common plugin (see RequestType (org.eclipse.aperi.constants) and RequestTypeSource), while their implementations are in the org.eclipse.aperi.server.data plugin (e.g., AgentSvp).

• [4] Create a request handler extension point for the service provider. The extension point is used to register request handlers with the service provider. Its definition should leverage the request handler extension point schema available in the org.eclipse.aperi.server.data plugin (requestHandler.exsd), and look something like this:

Insert screenshot of extension point wizard...
Insert sample code (stripped-down schema) (highlight schema inclusion)...

For the sake of reference, the request handler extension point schemas associated with the service providers that ship with the Data Server are available in the schema folder of the org.eclipse.aperi.server.data plugin.

• [5] Extend the abstract ServiceProvider (org.eclipse.aperi.server) class:

/**
 * This abstract class must be extended by all service providers.
 * The methods declared in this class are used by the service
 * controller to initiate and terminate a service provider.
 */
public abstract class ServiceProvider
{
    /**
     * Must return the service ID that can be used to look up this
     * provider's name and major request code. The major request code
     * describes the category of requests that this provider is capable 
     * of processing.
     */
    public abstract String getTypeCode();

    /**
     * Should spawn 1 or more threads to handle the requests placed on
     * the passed ServiceQueue. Threading & routing of requests to your
     * service's request handlers can be managed by the RequestManager
     * class. Should return to caller after kicking off your threads.
     */
    public abstract void startup(ServiceQueue queue) throws Exception;

    /**
     * Should terminate all threads of execution, release all held 
     * resources and return to caller. The shutdownOption will be one of
     * Constants.SHUTDOWN_NORMAL or Constants.SHUTDOWN_IMMEDIATE.
     */
    public abstract void shutdown(byte shutdownOption);
}

The getTypeCode() method must return the request type constant associated with the service provider. The startup() method should instantiate and initialize a new RequestManager (org.eclipse.aperi.server). The RequestManager class manages the request handlers registered against the service provider. It takes care of thread management and is responsible for routing incoming requests to the correct handlers. The RequestManager must be constructed using the ID of the extension point setup to accommodate request handler registration for the service provider. The shutdown() method simply needs to dispose of the RequestManager created in startup(). A full service provider implementation might look something like this:

Insert sample code (see ServerSvp)
(use pseudocode comment to refer to loading service provider configuration) 
(comment parameters passed to RequestManager constructor)

• [6] Register the service provider implementation. The org.eclipse.aperi.server.data plugin defines the serviceProvider extension point for service provider registration. The following XML snippet would be added to the plugin.xml containing the service provider implementation presented above:

Insert sample XML content...