Create custom services

We can create one or more custom services for an application server. Each custom services defines a class that is loaded and initialized whenever the server starts and shuts down. Each of these classes must implement the com.ibm.websphere.runtime.CustomService interface. After creating a custom service, use the console to configure that custom service for the application servers.

(zos) Custom services run in servants, not in controllers. For example, because there can be more than one servant started in the life of a server and these servants can be started long after the server (controller) is up, as needed by WLM, a custom service runs during the start of each servant.

(zos) If we need to define a hook point that runs when a server starts and shuts down, create a custom service class and use the console to configure a custom service instance. When the application server starts, the custom service starts and initializes.

To define a routine that runs whenever 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.

Following is a list of restrictions that apply to the product custom services implementation. Most of these restrictions apply only to the initialize method:

• The initialize 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 initialize and shutdown methods are called only once on each service, and once for each operating system process that makes up the server instance.

• 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 Java EE code, such as client code, servlets, and enterprise beans, is not supported.

• The Java Transaction API (JTA) interface is not available.

• This feature is available in Java EE 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.

• JNDI operations that request resources are not supported.

1. Develop a custom service class that implements the com.ibm.websphere.runtime.CustomService interface.

   The com.ibm.websphere.runtime.CustomService interface includes an initialize and shutdown methods. The application server uses the initialize method to pass properties to the custom service. These properties can include:

   • A property that provides the name of an external file containing configuration information for the service. We can use the externalConfigURLKey property to retrieve this information.

   • Properties containing name-value pairs stored for the service, along with the other system administration configuration data for the service.

   Both the initialize and shutdown methods declare that they might create an exception, although no specific exception subclass is defined. If either method creates an exception, the runtime logs the exception, disables the custom service, and continues to start the server.

2. Configure the custom service.

   In the console, click Servers > Server Types > WebSphere application servers > server_name, and then under Server Infrastructure, click Custom Services > 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 the 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 the 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 used to locate the classes and JAR files for the custom service. This procedure adds the path name to the extension classloader, which allows the custom service to locate and correctly load the native library.

3. Stop the application server, and then restart it.

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

   If we are developing a custom service for a node agent, stop and then restart the processing of the node agent. In the console, click System Administration > Node agents, select the node agent to stop, and then click Stop. To restart the node agent, select the node agent to restart, and click Restart.

   (zos) Stop the application server, and then restart the server.

Results

Each custom services defines a class that is loaded and initialized whenever the server starts and shuts down.

The custom service loads and initializes whenever the server or node agent starts and stops.

(zos) The custom service loads and initializes whenever the server starts and shuts down.

Example

As previously mentioned, the custom services class must implement the com.ibm.websphere.runtime.CustomService interface. In addition, the class must implement the initialize and shutdown methods. The following example, shows the code that declares the class ServerInit that implements the custom service. This code assumes that the custom service class needs a configuration file. This example also includes the code that accesses the external configuration file. If the class does not require a configuration file, we do not have to include the configProperties portion of this code.

public class ServerInit implements com.ibm.websphere.runtime.CustomService
{
/**
* The initialize method is called by the application server runtime when the * server starts. The Properties object that the application server passes
* to this method must contain all of  the configuration information that this 
* service needs 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     }

/**
* The shutdown method is called by the application server runtime when the * server begins its shutdown processing.
*
    public void shutdown() throws Exception
    {
        // Implement shutdown method     }

What to do next

Check the application server or node agent to verify that the initialize and shutdown methods of the custom service run the way we want them to run.

(zos) Check the application server to verify that the initialize and shutdown methods of the custom service run the way we want them to run.

Subtopics

• Custom service collection
  Use this page to view a list of services available to the application server and to see whether the services are enabled. A custom service provides the ability to plug into an application server and define code that runs when the server starts or shuts down.

Related tasks

Stopping an application server

Start an application server