Develop custom services

 

Overview

To define a hook point to be run when a server or node agent starts and shuts down, you develop a custom service class and then configure a custom service instance. When the application server or node agent starts, the custom service starts and initializes.

The following restrictions apply to the WAS custom services implementation:

• The init and shutdown methods must return control to the runtime.

• No work is dispatched into the server instance until all custom service initialize methods return.

• The init and shutdown methods are 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.

• Only JDBC RMLT (resource manager local transaction) operations are supported. Every unit of work (UOW) must be completed before the methods return.

• Creation of threads is not supported.

• Creation of sockets and I/O, other than file I/O, is not supported. Running 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 makes an effort to call shutdown, there is no guarantee that shutdown will be called prior to process termination.

Note that these restrictions apply to the shutdown and init methods equally. Some JNDI operations are available.

 

Procedure

1. Develop a custom service class that implements the com.ibm.websphere.runtime.CustomService interface. 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 externalConfigURLKey). In addition, the properties can contain any name-value pairs that are stored for the service, along with the other system administration 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 create an exception, although no specific exception subclass is defined. If an exception is created, the runtime logs it, disables the custom service, and proceeds with starting the server.

2. On the Custom Service page of the administrative console, click New. Then, on the settings page for a custom service instance, create a custom service configuration for an existing application server or node agent, supplying the name of the class implemented. If your custom service class requires a configuration file, specify the fully-qualified path name to that configuration file in the externalConfigURL field. This file name is passed into your custom service class.

   To invoke a native library from the custom service, provide the path name in the Classpath field in addition to the path names that are used to locate the classes and JAR files for the custom service. Doing this adds the path name to the WAS extension classloader, which allows the custom service to locate and correctly load the native library.

3. If you are developing a custom service for an application server, stop the application server and then restart the server.

4. If you are developing a custom service for a node agent, stop and then restart the processing of the node agent. On the Node Agents page of the administrative console (System Administration > Node Agents), place a checkmark in the check box beside the node agent you want to stop, then click Stop. To restart the node agent, place a checkmark in the check box beside the node agent, then click Restart.

5. Check the application server or node agent to ensure that the initialize method of the custom service ran as intended. Also ensure that the shutdown method performs as intended when the server or node agent stops.

 

ExampleServerInit

public class ServerInit implements CustomService

{ /** * The initialize method is called by the application server run-time when the * server starts. The Properties object passed to this method must contain all * configuration information necessary for this service to initialize properly. * * @param configProperties java.util.Properties */ static final java.lang.String externalConfigURLKey = "com.ibm.websphere.runtime.CustomService.externalConfigURLKey"; static String ConfigFileName=""; public void initialize(java.util.Properties configProperties) throws Exception { if (configProperties.getProperty(externalConfigURLKey) != null) { ConfigFileName = configProperties.getProperty(externalConfigURLKey); } // Implement rest of initialize method }