You 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 you create a custom service, use the administrative console
to configure that custom service for your application servers.
About this task
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.
If
you need to define a hook point that runs when a server starts and
shuts down, create a custom service class and then use the administrative
console to configure a custom service instance. When the application
server 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 Platform,
Enterprise Edition (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.
Procedure
- 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 that contains
configuration information for the service. You can use the externalConfigURLKey
property to retrieve this information.
- Properties that contain
name-value pairs that are 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.
- Configure the custom service.
In the administrative
console, click 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 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.
This procedure adds the path name to the extension classloader, which
allows the custom service to locate and correctly load the native
library.
- Stop the application server,
and then restart it.
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 starts and shuts down.
Example
As
previously mentioned, your custom services class must
implement the com.ibm.websphere.runtime.CustomService interface. In
addition, your class must implement the initialize and shutdown methods.
The following example, shows the code that declares the class
ServerInit that
implements your custom service. This code assumes that your custom
service class needs a configuration file. This example also includes
the code that accesses the external configuration file. If your class
does not require a configuration file, you 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 to
verify that the initialize and shutdown methods of the custom service
run the way that you want them to run.