Developing exits for Electronic Signature

About the exit framework

Overview

In the main use case of Electronic Signature, a signer user can sign or reject a payment. To enable you to add specific post-processing behavior in this use case (for example, adding a payload in a specific archiver, generating a signature proof, and so on), Electronic Signature provides an Exit Framework as an API.

This framework is an asynchronous events dispatcher. When a payment is signed or rejected, a corresponding event is created and placed in a persisted queue. A periodic timer dispatches all these events to the registered implementation of the API. After being dispatched, an event is removed from the queue. For each event a post-processor instance is launched which enables you to post-process several events simultaneously. As such, the exit is not processed immediately after the signature or rejection action.

The success or failure of the post-processing is of no significance to the framework. It only ensures that all the events are correctly dispatched to post-processors. The error management is in charge of the exit implementation that you develop.

Description of exit framework API

There are two kinds of event: Sign Event and Reject Event. Each one is dispatched to a specialized class of post-processing: SignExitOperation and RejectExitOperation. An event is a set of properties such as payment signer, received date, payment number and so on. A property is defined by a unique String key and a value which together constitute a Java Object. The list below describes the main interfaces and classes of the API. For more information, refer to the Exit API Javadoc.

The main interfaces and classes of the API are:

• com.axway.fex.es.exit.IExitOperation
• This is the main interface of the API. It globally defines an Exit Operation: a post-processing operation on an event. It must not be directly implemented and is created for architectural purposes only.
• Two kinds of event are provided: sign event and reject event. For each kind, a specific IExitOperation is called to process it. Likewise, there are also two kinds of IExitOperation to process them which are abstract classes: SignExitOperation and RejectExitOperation.
• The framework ensures that a sign event is dispatched to a SignExitOperation and does the same for a reject event. Custom implementations of a SignExitOperation or a RejectExitOperation only have to be registered in the configuration of Electronic Signature.
• Custom implementation has to be a derived class from one of these abstract classes. Be careful, an IExitOperation implementation MUST respect the following properties:
  • Thread safe: an IExitOperation is launched in a Thread and several instances of the same IExitOperation may run simultaneously.
  • Stateless: an IExitOperation is a one time execution meaning that the framework creates a new instance of the IExitOperation for each event. When the event is post-processed, the corresponding IExitOperation is "destroyed".
• The framework sends an event to an IExitOperation. An event is basically a set of properties such as the date of the rejection of a payload, the name of the user who rejects it, the file name of the payload, and so on. So an event is represented by a HashMap containing all its properties. Each property is indexed in the HashMap by a String Key which is defined in the IExitPropertiesKey.
• com.axway.fex.es.exit.IExitPropertiesKeys
• List of all the keys that can be used in a HashMap event. The type of indexed Object in the HashMap is provided in the documentation of the Key. Refer to the Exit API Javadoc.
• com.axway.fex.es.exit.sign.SignExitOperation
• Abstract class representing a SignExitOperation that executes the post-processing for a signed payload. This class can be derived to provide custom post-processing on a sign event. It contains an abstract method named executeSignPostProcessing which is called by Electronic Signature. Redefine this method to provide custom post-processing implementation.
• com.axway.fex.es.exit.reject.RejectExitOperation
• Abstract class representing a RejectExitOperation and executes the post-processing for a rejected payload. This class can be derived to provide custom post-processing on a reject event. It contains an abstract method named executeRejectPostProcessing which is called by Electronic Signature. Redefine this method to provide custom post-processing implementation.

Development

Prerequisites

Electronic Signature provides a sample implementation of the Exit Framework. This sample is developed in JAVA and its environment based on Maven and Eclipse.

Oracle Java™

1. Installation
   1. Download Oracle Java™ JDK6 from: http://www.oracle.com/technetwork/java/javase/downloads/jdk-6u25-download-346242.html.
   2. Install Oracle Java™ JDK6 on your system.
   3. Accept the License Agreement and select a delivery in the list for your platform.
2. Setting the path
3. Set up your path environment variable:

Windows

1. Right-click the Computer Icon on your desktop and click Properties.
2. If using Windows 7, in the ControlPanel, select Advanced System Settings on the left.
3. In the System Properties window, click the Advanced tab then click Environment Variables.
4. Create a new User Variable by clicking New.
5. Name it JAVA_HOME and set the value to the Java™ installation directory path, usually in C:\Program Files\Java\jdk1.6.XXX if you didn’t specify another location.
6. Note that the XXX represents the version of your Java™ installation.
6. Click OK.
7. Go to the Systems Variables list and select the variable named PATH. Then click Edit.
8. At the end of the value line add: ";%JAVA_HOME%\bin". ( Without the " and don’t forget the ; at the beginning ).

Linux

To set up the PATH on a Linux system, edit the file ~/.bashrc. Add the following lines at the end of the file:

export JAVA_HOME=<YOUR_JAVA_INSTALL_DIR>

export PATH=$PATH:$JAVA_HOME/bin

Apache Maven

The sample is packaged with Apache Maven.

1. Go to http://maven.apache.org/download.html.
2. Select a Maven version 2.2.1 in the Mirrors list and download it.
3. To install Maven, go to http://maven.apache.org/maven-1.x/start/install.html. For Linux users, remember to define your MAVEN_HOME and add it to the PATH, see Setting the PATH.

Eclipse

The sample is packaged for Eclipse IDE. If you don’t have it:

1. Download the Classic distribution from: http://www.eclipse.org/downloads/.
2. Select your platform and select a mirror.
3. The download starts.
3. Unzip the Eclipse Archive file wherever you want.
4. The executable eclipse file is <ECLIPSE_INSTALL_DIR>/eclipse/eclipse.

Developing exits

Getting Started

In your development environment, make sure you are using Java 1.6 and Maven 2. After creating your project add the following jars into your build path:

• log4j-1.2.16.jar. The logger used by the Exit API. If you do not have the file, go to http://logging.apache.org/log4j/1.2/download.html, unzip the archive and put the jar in your build path. Install is not necessary.
• fex-es-exit-XXX.jar. The Exit API. It is located in <ELECTRONIC_SIGNATURE_INSTALL_DIR>/devKit/exit/lib.
• fex-es-exit-XXX-javadoc.jar. The Exit API Javadoc. It is located in <ELECTRONIC_SIGNATURE_INSTALL_DIR>/devKit/exit/lib. Link it as Javadoc archive for fex-es-exit-XXX.jar. If you want to access the Javadoc from a web browser, copy this jar to a directory, open a terminal and run jar xvf fex-es-exit-XXX-javadoc.jar. This will extract all the Javadoc in the current directory.
• axway-sentinel-ua-2.0.22.jarThe Axway Sentinel framework that allows you to send notification to Sentinel from your implementation, if required. It is located in <ELECTRONIC_SIGNATURE_INSTALL_DIR>/devKit/exit/lib.

Now you can start your development. If you want to create a post-processing of a signature, create a class which extends SignExitOperation (or for a reject post-processing extend RejectExitOperation).

Then override the following methods:

Remember: all implementations are, in fact, stateless as an instance of your IExitOperation is created for each event. Remember to ensure thread safety. Several instances of your IExitOperation may run at the same time in different threads.

You can pack several IExitOperation in the same jar. However, only one SignExitOperation class and only one RejectExitOperation class will be loaded in Electronic Signature.

Note that the runtime directory of Electronic Signature (and that of your implementation) is <ELECTRONIC_SIGNATURE_INSTALL_DIR>.

Installing and configuring exit implementation in Electronic Signature

1. Place your jar and all its dependencies in <ELECTRONIC_SIGNATURE_INSTALL_DIR>/lib without the Exit API jars, Sentinel API jar and log4j.
2. You may have to place your resource dependencies in <ELECTRONIC_SIGNATURE_INSTALL_DIR>/ (as with your configuration files).
2. To configure Electronic Signature to run your implementation, open the configuration.properties file located in <ELECTRONIC_SIGNATURE_INSTALL_DIR>/conf.
3. Navigate to the Exit Configuration part:

4. ###################################### #### Exit Configuration #### ###################################### # frequency of exit scanner, default 60 seconds # the value is in milliseconds exit.pollingFrequency=60000 # size of the thread pool used for reject exit processing exit.reject.thread.pool.size=2 # size of the thread pool used for sign exit processing exit.sign.thread.pool.size=5 # activate the reject exit post-processing exit.useReject=false # the name of the implementation class of the reject exit exit.reject.classname= # the classpath with all the dependencies of the reject exit # all jars must be separated by ; example: file:jars/signExit.jar;file:lib/dependency1.jar;file:lib/dependency2.jar exit.reject.classpath= # activate the sign exit post-processing exit.useSign=false # the name of the implementation class of the sign exit exit.sign.classname= # the classpath with all the dependencies of the sign exit # all jars must be separated by ; example: file:jars/signExit.jar;file:lib/dependency1.jar;file:lib/dependency2.jar exit.sign.classpath=

• exit.pollingFrequency defines the frequency of event dispatching. In this example, the queued events are dispatched every 60 seconds.
• exit.reject.thread.pool.size defines how many instances of your RejectExitOperation implementation can be run at the same time.
• exit.sign.thread.pool.size defines how many instances of your SignExitOperation implementation can be run at the same time.
• exit.useReject defines if Electronic Signature dispatches events to RejectExitOperation or not. Set to True if you want to register your own RejectExitOperation implementation.
• exit.reject.classname defines the name of the RejectExitOperation to be used in Electronic Signature. Use your implementation class full name with its packages (for example: com.axway.fex.es.exit.sample. RejectSentinelNotifier).
• exit.reject.classpath defines the necessary classpath to execute your RejectExitOperation. This list must be formatted: file:jars/signExit.jar;file:lib/dependency1.jar;file:lib/dependency2.jar ("file:" is necessary). Do not add the Exit API jars to this list.
• exit.useSign defines whether Electronic Signature dispatches events to SignExitOperation or not. Set to True if you want to register your own SignExitOperation implementation.
• exit.sign.classname defines the name of the SignExitOperationto be used in Electronic Signature. Put your implementation class full name with its packages (for example: com.axway.fex.es.exit.sample. XMLProofSignature).
• exit.sign.classpath defines the necessary classpath to execute your SignExitOperation. This list must be formatted: file:jars/signExit.jar;file:lib/dependency1.jar;file:lib/dependency2.jar ("file:" is necessary). Do not add the Exit API jars to this list.

Now you can run Electronic Signature and test your implementations.

Electronic Signature provides a sample of Exit API implementations.

Sample exit

Overview

The sample is provided by the Electronic Signature installation. It is located in <ELECTRONIC_SIGNATURE_INSTALL_DIR>/devKit/exit/.

Importing a sample project into Eclipse

1. Open a terminal and go to <ELECTRONIC_SIGNATURE_INSTALL_DIR>/devKit/exit/.
2. Run mvn eclipse:eclipse.
3. This generates the .classpath and the .project files.
3. Import it into Eclipse using the import menu.
4. Set the root directory of the project to <ELECTRONIC_SIGNATURE_INSTALL_DIR>/devKit/exit/.

Building the sample

1. Open a terminal and go to <ELECTRONIC_SIGNATURE_INSTALL_DIR>/devKit/exit/,
2. Launch an mvn clean install.
3. This builds the sample and at the end of the building phase you should find a target directory with the following:

• fex-es-exit-sample-XXX.jar. The jar of the sample.
• fex-es-exit-sample-XXX-javadoc.jar. The corresponding JavaDoc.
• fex-es-exit-sample-2.7.0-SNAPSHOT-bin.zip (and a .tar.gz one for UNIX platforms) which is the delivery of the sample.

Sample description

The following sample contains two different implementations:

• XMLProofSignature which is a SignExitOperation.
• This SignExitOperation creates a proof signature of a sign event. This proof is generated in XML using JAXB and is placed in a directory named "proofs". The XML proof is defined by an XML Schema (XSD) which is located in src/main/resources/xsd/signatureProof.xsd. This XSD basically defines the payment characteristics (bank id, customer id, order number, order type and so on) and its signature(s) (the signer user, certificates used to sign it and so on). JAXB generates Java data types which correspond to the XSD definition (in src/main/generated). These data types contain the sign event properties and JAXB serializes it into an XML file in the proof directory.
• RejectSentinelNotifier which is a RejectExitOperation.
• This RejectExitOperation uses the Sentinel API to send a notification to Axway Sentinel. Axway Sentinel is a monitoring software. When it gets a reject event, it places a copy of the rejected payload in a custom directory named "rejected". It then retrieves the SentinelAppender (which is the notification tool) from the reject event. A SentinelEvent is created with the HashMap reject event provided by Electronic Signature and this event is sent to Sentinel through the SentinelAppender.

Both are located in <ELECTRONIC_SIGNATURE_INSTALL_DIR>/devKit/exit/src/main/com/axway/fex/es/exit/sample.

Installing the sample in Electronic Signature

1. Unzip the delivery archive generated during the build.
2. This generates a fex-es-exit-sample-XXX directory.
2. Copy all its subdirectories (lib/, doc/ and conf/) to <ELECTRONIC_SIGNATURE_INSTALL_DIR>.
3. Configure the code in Electronic Signature in the directory <ELECTRONIC_SIGNATURE_INSTALL_DIR>/conf/configuration.properties.
4. Replace it with the following code in the Exit configuration part:

5. exit.useReject=true exit.reject.classname= com.axway.fex.es.exit.sample.RejectSentinelNotifier exit.reject.classpath= file:lib/fex-es-exit-sample-XXX.jar   exit.useSign=true exit.sign.classname=com.axway.fex.es.exit.sample.XMLProofSignature exit.sign.classpath=file:lib/fex-es-exit-sample-XXX.jar

5. Start Electronic Signature.

Related topics

Configuring Electronic Signature