InfoCenter Home >
4: Developing applications >
4.10: Developing custom services

4.10: Developing custom services

You can write a custom service class that implements the com.ibm.websphere.runtime.CustomService interface (shown below). The administrator can then create a custom service configuration for an application server, supplying the class name. When the application server is started, the custom service will be started and initialized.

The properties passed by the application server runtime to the initialize method can include one for an external file containing configuration information for the service (retrieved with the externalConfigURLKey). In addition, the properties can contain any name-value pairs that are stored for the service, along with the other system administrations configuration data for the service. The properties are passed to the initialize method of the service as a Properties object.

There is a shutdown method for the interface as well. Both methods of the interface declare that they may throw an Exception, although no specific exception subclass is defined. If an exception is thrown, the runtime will log it, disable the CustomService, and proceed with Server startup.

The interface does not pass in the context for the services to use for registration binding. This is how it differs from the ServiceInitializer interface provided in Version 3.5.

Custom service interface

The following code is the complete source for the interface.

package com.ibm.websphere.runtime;
/**
* The CustomService interface must be implemented by all
* WebSphere Custom Service extensions.
* The application server runtime will call the initialize method of
* this interface on every enabled Custom Service configured in the server.
*
*/
public interface CustomService {
static final java.lang.String externalConfigURLKey =
"com.ibm.websphere.runtime.CustomService.externalConfigURLKey";
/**
* The initialize method is called by the application server runtime during
*		server startup. The Properties object passed in on this method must
*		contain all configuration information necessary for this service to
*		initialize properly.
*
* @param configProperties java.util.Properties
*/
void initialize(java.util.Properties configProperties) throws Exception;
/**
* The shutdown method is called by the application server runtime when the
*		server begins it shutdown processing.
*
* @param configProperties java.util.Properties
*/
void shutdown() throws Exception;
}
Limitations of the custom service implementation

There are restrictions on the functions that can be executed within a custom service. The initialize method of all custom services is invoked by the server runtime before most other components have been initialized, including the ORB, Trace, Naming, Transaction Manager, and Connection Manager. This provides the custom service with great flexibility in effecting the server runtime environment, but also prevents the custom service initialize method implementation from being able to take advantage of the application server runtime services.

For example, a custom service cannot count of being able to make JNDI lookup method calls in its initialize method, since the Naming Service has not been initialized within the server runtime at that point in server process startup. A custom service can execute code in its initialize method that reads its configuration values and processes them in whatever manner makes sense for that service. This includes executing code that reads the external configuration file for the custom service, provided that the permissions set for the external config file match those of the server identity under which the custom service code runs. A JDBC Connection can be obtained and used as long as the pooling services of the WebSphere Connection Manager are not expected to be used (since the Connection Manager has not been initialized at the time that the custom service initialize method is invoked).

Specifically, within the implementation of a custom service:

  • The initialize and sutdown methods must return control to the runtime.
  • No work will be dispatched into the server instance until all custom service initialize methods return.
  • Custom services are initialized serially, but in no predictable order.
  • The initialize and shutdown methods will be called only once on each service, and once for each operating system process that makes up the server instance. File I/O is supported.
  • Initialization of process level "static" data without leaving the process is supported.
  • The identity/credential that the custom service code runs under is the server identity.
  • Only JDBC RMLT (local tran) operations are supported. All UOW must be completed before the methods return.
  • JNDI operations are not supported.
  • Creation of threads is not supported.
  • Creation of sockets and I/O other than file I/O is not supported.
  • Execution of standard J2EE code (client code, servlets, enterprise beans) is not supported.
  • The JTA interface is not available. This feature is available in J2EE server processes and distributed generic server processes only.
  • While the runtime will make a best effort to call shutdown, there is no gaurantee that shutdown will be called prior to process termination. These restrictions apply to shutdown and init equally.
Go to previous article: Verification Header Handler Go to next article: Securing applications -- special topics

 

 
Go to previous article: Verification Header Handler Go to next article: Securing applications -- special topics