trans_notification

Transaction Received Notification

In using the test engine you may want to be notified when a message is received by a particular simulator. The callback mechanism described implements that feature.

For the moment this can only be done when the notified system is built on top of Java Servlets version 2.5 or later. This restriction comes from the project philosophy of not exposing message details but instead providing Java level resources packaged in JAR files to users.

The callback mechanism is packaged into these pieces:

• Notification - Identification of a notification handler class in your system that implements a given interface.
• Configuration - Configuration added to the web.xml file of the receiving Java based web application
• Subscription - Information added to the simulator configuration

Important reminder - Jersey version

This service uses Jersey REST libraries and components. If your project already uses Jersey and uses a different version the dependencies brought into your project by Toolkit API will force a second copy of the Jersey jars with different version labels to be brought into your build. This will break Jersey.

The version Jersey used by toolkit can be found here in the Properties section, the property named jersey.version.

Notification

When a message of interest is received your system will be notified of the message and its details. This notification comes in the form of a method call to a configured Java class within your system. This Java class is called a notification handler.

This notification handler class must implement the interface gov.nist.toolkit.transactionNotificationService.TransactionNotification. This interface requires the implementing class contain the method

void notify(TransactionLog log);

where TransactionLog is defined as

public interface TransactionLog {
   String getSimulatorUser();
   String getSimulatorId();
   String getRequestMessageHeader();
   String getRequestMessageBody();
   String getResponseMessageHeader();
   String getResponseMessageBody();
}

For every message received by the engine that you have requested notification, the notification handler will be called. The user and id parameters define the simulator that is issuing the notification. The other parameters offer details on the transaction received.

Configuration

Notifications are delivered to a servlet installed in your system. This servlet calls the notification handler in your Java code. Configuring your web application to receive notifications requires installing this servlet and the supporting JAR files.

Configuring the notification servlet

The notification servlet is provided as part of toolkit and must be installed in your web application. There are two parts to this installation, updating web.xml and adding JAR files.

The web.xml update is

<servlet>
    <servlet-name>jersey</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>jersey.config.server.provider.packages</param-name>
        <param-value>gov.nist.toolkit</param-value>
    </init-param>
    <!-- The next two parameters force the return of debug info in X-JERSEY-* headers.
         They should be removed in production.
    -->
    <init-param>  
        <param-name>jersey.config.server.tracing.type</param-name>
        <param-value>ALL</param-value>
    </init-param>
    <init-param>
        <param-name>jersey.config.server.tracing.threshold</param-name>
        <param-value>VERBOSE</param-value>
    </init-param>

    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>jersey</servlet-name>
    <url-pattern>/rest/*</url-pattern>
</servlet-mapping>

This configuration adds the Jersey RESTful Web services environment to your web application. The toolkit notification system uses Jersey to transport messages from the test engine to your system. Based on the servlet-mapping block, your system will now accept REST messages to the URI

http://host:port/YourApp/rest/*

If this is an inconvenient URI then it can be changed. The corresponding change must be made to the simulator configuration described below in the section on subscriptions.

The jersey.config.server.provider.packages init parameter enables all Jersey REST resources in your system that belong to the package gov.nist.toolkit. In the libraries supplied there is only one, the receiver for notifications.

Adding the necessary JARs

The following JARs must be added to your web application. This usually means adding them to the directory WEB-INF/lib.

As Maven dependencies:

<dependencies>
    <dependency>
        <groupId>log4j</groupId>
        <artifactId>log4j</artifactId>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jersey.containers</groupId>
        <!-- if your container implements Servlet API older than 3.0, use "jersey-container-servlet-core"  -->
        <artifactId>jersey-container-servlet</artifactId>
        <version>2.22.1</version>
    </dependency>
    <dependency>
        <groupId>gov.nist.toolkit</groupId>
        <artifactId>transaction-notification-service</artifactId>
        <version>2.202.0-SNAPSHOT</version>
    </dependency>
</dependencies>

No specific version of log4j is required. The version of transaction-notification-service is current as of this writing and will change with future releases.

The same dependencies as a list of JARs are:

jersey-container-servlet-2.22.1.jar
log4j-1.2.12.jar
transaction-notification-service-2.202.0-SNAPSHOT.jar

Subscription

To receive notifications you must subscribe to the service that delivers them. This is done in the creation of the simulator. Any simulator that receives transactions can be configured to send notifications.

Note: At the moment only the Registry simulator is equipped to send notifications. 
This capability will added to the  other simulators soon.

There are two ways to create and configure a simulator, using the Toolkit user interface and through the callable service interface.

Using the Toolkit user interface

A subscription for a transaction received notification can be added through the Simulator Manager tool or through the Engine API.
To add it through the Simulator Manager tool:

1. Create a simulator using the Simulator Manager tool
2. Configure the simulator (Configure button)
3. Fill in the Transaction Notification URI
4. Fill in the Transaction Notification Class
5. Save the configuration

The Transaction Notification URI is the REST URI used to contact your web application. The value coordinates with the servlet configuration described in the Configuration section. On my test system the value is

http://localhost:8888/xdstools2/rest

which agrees with the servlet configuration above. My test server is running on http://localhost:8888/xdstools2 and the servlet-mapping url-pattern is /rest/*.

The Transaction Notification Class is the class name which accepts the notification, the notification handler. The requirements on this class are described above in the Notification section. On my test system the class name is

gov.nist.toolkit.transactionNotificationService.LoggingTransactionNotification

which simply logs the notification through log4j.

Using the callable service interface

Note: The service interface is not yet available

Logging

The relevant log4j entries are:

Toolkit Transaction Notification...
...classname - gov.nist.toolkit.transactionNotificationService.LoggingTransactionNotification
...exists
...implements TransactionNotification interface
...instance built - calling

which indicates that a Toolkit notification has arrived. It is configured to notify the LoggingTransactionNotification class. This class exists and does implement the TransactionNotification interface. The notification handler I use for testing logs:

Toolkit transaction notify called...
...User mike
...SimulatorId reg