Supervisor Customization

The Java-based supervisor is deployed with the Web application Server Admin in the embedded Tomcat Web container of each IdS-J.

The main component in the supervisor is a Groovy script. The script contains the control logic for monitoring the server(s), moving functionality and sending email notifications. It uses Java classes in the module Admin Client. The most important class is AdminClientController. It provides methods to

Read configuration data from and change in the Connectivity database.
Obtain the state of Java-based and C++-based servers.
Move adaptors between Java-based servers.
Move request workflow processing and scheduler between Java-based servers.
Move workflows between C++-based servers.

The Sendmail class allows for sending an e-mail.

Adapting the Groovy script requires Java knowledge. Only a few simple Groovy-specific syntaxes are used within the script. Editing and running the script is possible even with a normal text editor. You don’t need a compiler. For more convenience, we recommend using Eclipse with the Groovy plug-in. For more details on Groovy, check the Groovy web page: http://groovy.codehaus.org/.

The following sections help you to understand the logic of the supervisor script to help you adapt it to your needs. The first sections describe the script, a special section explains how to adapt e-mail texts and the last sections describe the most important Java utility classes.

Find the script and properties files in the following sub-folders of each respective Java server:

Start script and properties for mails in subfolder tomcat/webapps/serverAdmin/WEB-INF/scripts/sv.
Other common scripts in subfolder tomcat/webapps/serverAdmin/WEB-INF/classes/sv.

Supervisor in Server Admin

The control logic of the supervisor deployed in Server Admin is contained in the InsideGroovySupervisor.groovy script. This script is called from the Supervisor servlet on start-up only when the configuration in the Connectivity database requests automatic monitoring.

The startMonitoring method contains the script’s control logic. After reading its configuration it starts the monitoring loop. The method isJavaServerUp returns false if the Java server with the given name is not considered active. If this supervisor is also the one to monitor the C++ servers, it performs this in the method monitorCServer.

If a Java server is considered to be down, the supervisor, in its handleInactiveServer method, takes over all the features of the failed servers. These are especially the following items:

The scheduler, if the failed server hosted it.
The request workflow processing, if the failed server was responsible for request workflows.
The server’s movable adaptors. If one of the other JMS adaptors was active in the failed server, but not in the local one, then the supervisor activates it also on its embedding server.
The server’s monitoring tasks; that is, it also checks the state of those servers that should be monitored by the failed one.

The monitorCServer method monitors the registered C++-based servers. It calls the isCServerUp method to check the state of a given C++-based server. If the C++-based server is registered as active but fails to respond, the supervisor:

Sends an e-mail informing about the fail state.
Moves the Tcl-based workflows controlled by the failed server to another running C++-based server.
Sends an email informing about the move.
Requests the affected C++-based servers to reload.

The sendmail method sends an e-mail using the Sendmail class of the ClientAdminController component. The method obtains the mail configuration from the supervisor configuration, especially: from, to, subject, body and the name of the mail server. If a subject is passed to the method, it adds it to the configured subject. If a body is passed to the method, it adds it to the configured body.

Changing Mails in Supervisor Scripts

The supervisor scripts take the basic mail parameters from the supervisor configuration in the Connectivity database: see the section Supervisor Configuration above. These parameters specify mail parameters such as the recipients (to, cc, bcc), the subject and the body of the mail as well as the mail service.

The scripts send e-mails in various situations, especially when they move functionality from a failed server to an active one. All of these mails use the same mail configuration. To identify the actual situation, the scripts add specific information to the subject and the body:

Subject: the configured subject is extended with ": " followed by a string.
Body: the configured body is extended with a new line followed by a string.

The strings are taken from the file mail.properties in the sub-folder tomcat/webapps/serverAdmin/WEB-INF/scripts/sv of each affected Java server. Note that is has to be deployed for each server. They can be customized by adapting this file. The supervisor scripts find the appropriate texts via a key that identifies the situation. The currently evaluated keys are:

start: subject of the mail immediately before starting the monitor loop.

startbody: body of the mail immediately before starting the monitor loop.

j_down: subject of the mail after a Java-based server becomes inactive.

j_down_body: body of the mail after a Java-based server becomes inactive.

c_down: subject of the mail after a C++-based server becomes inactive.

c_down_body: body of the mail after a C++-based server becomes inactive.

INF_MOVE_ATS: body of the mail after workflows have been moved between C++-based servers.

c_ ats_move: subject of the mail after the messaging service has been moved.

c_ ats_move_body: body of the mail after the messaging service has been moved.

The texts contain string placeholders of the form %*n$s* where n is an integer that indicates the nth passed parameter; for example, %1$s. These parameters are the dynamic values depending on the context, typically identifying a server name.

If you want to suppress mails, find the location by scanning for the string "sendmail" in the appropriate script. Just uncomment the lines by prefixing them with "//" or remove them.

If you want to send additional mails: copy the lines for generating the subject and body strings and for sending the mail and paste them into the appropriate location. Replace the keys with your own names and extend the mail.properties file with the appropriate lines.

You can also replace the pre-configured mail parameters and set your own ones by using your own sendmail method. Just copy and paste the default sendmail method to define a new method (for example, myCustomSendmail) and adapt it to your needs.

Java Classes

The supervisor script uses a set of Java classes. The following sections give an overview on them.

AdminClientController

The net.atos.dirx.dxi.admin.client.controller.AdminClientController class provides a number of useful methods to read and update the configuration entries of the Java- and C++-based servers, to obtain the state of these servers and to move functionality between servers. The most important methods are:

getSupervisionConfigurationByName: Reads the supervisor configuration with the given name from the Connectivity database and returns it as a map with the option names as the index.
getServers: Reads the configuration of all Java-based servers from the Connectivity database and returns them in a map that is indexed by the display name of the server. The configuration for a server is provided as a Java bean with the configuration options available as a map.
getCServers: Reads the configuration of all C++-based servers from the Connectivity database and returns them in a map that is indexed by the display name of the server. The configuration for a server is provided as a Java bean with the configuration options available as a map.
getStateOfJavaServer: Sends a JMX operation to obtain the state of the indicated Java-based server. The state is given as an integer in the range from 0 (bad) to 10 (good).
getStateOfCServer: Sends a JMX/SOAP operation to obtain the state of the indicated C++-based server. The state is given as an integer in the range from 0 (bad) to 10 (good).
moveAdaptors: Moves the JMS adaptors and also the responsibility for request workflows from one server to another one.
moveReqWFType: Moves the responsibility for processing the request workflows from one server to another. It first changes the settings in the connectivity database and then requests the affected Java-based servers to reload their configuration and thus start the processing.
moveTclWorkflowAndActivities: Moves the workflows and activities that are controlled by a given C++-based server to another one given by name. It first changes the settings in the connectivity database and then requests the affected Java-based servers to reload their configuration and thus start the processing.

Sendmail

The net.atos.dirx.dxi.admin.client.controller.Sendmail class can send a mail. It sets the mail content type to either "text/html", if the body matches the HTML pattern or to "UTF-8" otherwise.