Chapter 8   Building Identrus solutions


The iPlanet Trustbase Transaction Manager platform and associated development tools provide a means of developing Identrus applications starting from the base DTD through to installing the service for use in a run-time environment.

The following sections walk through the generation of an Identrus application called Ping. This application is designed to highlight the following concepts:

• Overall development process

• Use of iPlanet Trustbase Transaction Manager developer tools

• The class generation tool JAXHIT

• Using configuration objects

• Using the log manager

Methodology

---

Development process

The development of an application requires a base input of an Identrus compliant DTD. This is passed through a class generator that produces Java Classes for all of the elements in the DTD along with a set of stub rules and a service definition within a JAR file. The developer is then at liberty to extend this base data by implementing the appropriate business logic in the form of a set of Java classes called by the service stub that perform the appropriate actions.

The set of generated files and associated developer files are then packaged into a single JAR and deployed into an iPlanet Trustbase Transaction Manager directory structure. The iPlanet Trustbase Transaction Manager (when re-started) will locate a package descriptor within the JAR file and offer this new service for activation within the running environment. The overall process is outlined in Figure 8-1.

Figure 8-1    Development process

Class generation

The iPlanet Trustbase Transaction Manager class generation tool is designed to produce a set of classes that may be used at two points in the message processing pipeline. We now provide a brief overview. ( more details can be found in "The JAXHIT Class Generation Tool" of the appendix at the end of this document). These are:

Presentation - The iPlanet Trustbase Transaction Manager XML parser uses the classes to validate incoming XML against the DTD.

Services - Business logic that accesses elements of the message

In order to access the class generation tool, a JDK 1.2.x or greater must be installed; a JRE does not contain the correct compilers to build an iPlanet Trustbase Transaction Manager service. Also the classpath must be correctly set, executing the following on your iPlanet Trustbase Transaction Manager installation can do this:

cd ......./Trustbase/TTM/Scripts . ./jaxhit

This sets the CLASSPATH environment variable to the correct value for the iPlanet Trustbase Transaction Manager tools.

The class generation tool is available as a command line option and is invoked using the following:

jaxhit [-options] [<public Id> <DTD file>]

Where options include:

-help	displays help
-config <file>	Specify the name of the configuration file. (See "Message Handler Example" for more options on this
-cp <classpath>	Specify the classpath to use for compilation
-y	Do not confirm before overwriting existing files
-stub	Generate a stub service
-quiet	quiet output
-v	verbose output
-debug	debug output

And PublicID is the name of the service stub that will be generated. The Public Id is a mandatory requirement for all Identrus DTD's, and is in the standard form shown below:

-//IDENTRUS//service_name//EN

Where service name represents the Identrus service declared by the DTD. The Public ID is case sensitive and should be carefully entered as it forms part of the package name for the generated classes.

The tool will only generate classes for DTD elements that do not already have classes available on the classpath. Therefore, the core Identrus classes are not regenerated with each new Identrus service because they are already available in Trustbase jars.

A '-root' entry must be made for each of the elements in the DTD that can be the root XML element in a message. This is necessary to allow the automatic processing of the Identrus Message by the default presentation layer in the iPlanet Trustbase Transaction Manager.

A '-stub' option must be used if the tool is required to generate a stub iPlanet Trustbase Transaction Manager service for the new message types. The Java source file for this stub class is placed in the current directory when the tool completes. Do NOT re-package the stub class once generation has completed - the fully qualified name of the stub class is recorded in the tbasesvc.properties file in the generated jar file.

The Class generator will attempt to recursively load the referenced DTD(s). The references may be:

• Unqualified - The DTD must be located in the directory in which the class generator is run in

• Local - The file:/// qualifier is used

• Fully qualified - The HTTP://www qualifier is used

An invocation of the JAXHIT tool will produce the following output:

• A .zip containing
  • A set of generated classes, one for each entity in the DTD

  • A set of DTD's that represent the input actually used by the XML parser for generating the classes

  • A tbasesvc.properties file used by iPlanet Trustbase Transaction Manager to register the service

• A service stub in the current directory - only if the '-stub' option is used

Each of the generate classes implements the TbaseElement interface. This interface provides two specific roles:

• Parser - Allows the iPlanet Trustbase Transaction Manager parsing mechanisms to validate incoming XML messages

• Service - Provides a standard means of getting data from incoming messages and constructing valid responses without explicitly producing the XML.

There is a sub-class of TbaseElement called TbaseIdentifiedElement that represents elements that have an attribute named 'id' with a type of 'ID'. This allows a type-safe method of checking ID compliance when generating or validating XML DSIG signatures.

The service role of the TbaseElement provides the following function:

• Constructing the XML document hierarchy

• Reading and writing the element attributes by name

• Validating the object representation of the XML document

• Generating the String representation of the XML document described by the object hierarchy

All elements that are identified by a '-root' option at class generation time, will end up extending the base class com.iplanet.trustbase.identrus.message.IdentrusMessage. This enforces that the message has a valid structure (as defined by Identrus Core Network Messaging Definition) and the framework can carry out that mandatory processing of the message. An example of using this interface is shown in the example section at the end of this document.

---

Note	The API classes for com.iplanet.trustbase.identrus.message.IdentrusMessage, com.iplanet.trustbase.xml.message.TbaseElement and com.iplanet.trustbase.xml.message.TbaseIdentifiedElement provide more information on their function.

---

Service development

Development of a service is the act of completing the service stub into a functional business component.

Every service must be stateless so that it may be replicated by the platform. This means that a service must be capable of processing messages from different transactions and different users without holding information about a previous Session State Transaction. If a service is required to hold information about a session or transaction state, this must be persisted in a database, as the subsequent messages in a transaction are not guaranteed to be passed to the same host machine within a cluster.

All Identrus network message processing is performed by the iPlanet Trustbase Transaction Manager platform prior to and after the invocation of the ProcessIdentrusMessage method in the service stub class generated by the Class Generation tool. Figure 8-2 shows the message processing path with a Developer written Identrus Service using the generated message libraries and proxied by the iPlanet Trustbase Transaction Manager message process stub.

Figure 8-2    Message path processing

This means that for most Identrus services, the developer only needs to modify the generated stub class to implement the business processing of the incoming message and generate the core content of the outbound message.

The business processing does not need to do any of the mandatory message processing such as mandatory signature verification or generation on the message. These core processing tasks are completed by the iPlanet Trustbase Transaction Manager presentation layers.

To develop the service, include the generated jar file on the classpath during development, along with the core iPlanet Trustbase Transaction Manager libraries.

Service Building

Having successfully generated the messaging classes and developed the message processing logic extensions to the stub service, the next task is to build a iPlanet Trustbase Transaction Manager service jar.

Building the iPlanet Trustbase Transaction Manager service jar is a simple matter of the following steps:

• Using the standard JDK 'jar' tool, unpack the generated jar file into a directory.

  mkdir DumpDirectory cd DumpDirectory jar -xvf ../jarfile.jar cd ..

• Beneath the 'DumpDirectory' copy in all of the classes which are required for the processing of the message. Ensure that the correct package structure is maintained for all these classes. n.b. Remember that the service stub class must not have been re-packaged since the class generation created it.

• Using the standard JDK 'jar' tool, repack the archive

  jar -cvf jarfile.jar -C DumpDirectory DumpDirectory/*

• The jar file is now ready for deployment.

Service Deployment

Once the service jar file has been built it can be deployed into iPlanet Trustbase Transaction Manager. This is done in three stages:

• Copy the jar file into the directory: ...../Trustbase/TTM/current/deploy

• Use the administrator console to deploy the service into the running iPlanet Trustbase Transaction Manager

• Re-start iPlanet Trustbase Transaction Manager to activate the service

To deploy the service, logon to iPlanet Trustbase Transaction Manager as 'administrator' and select the 'Deployment' option from the services menu. If you have copied the service jar into the 'deploy' directory then the new service should appear on the left hand side of the deployment screen.

• To deploy the service select
  
  followed by
  
  

Figure 8-3    Deploying PingService within iPlanet Trustbase Transaction Manager

Services may also require authorisation. Select <Authorisation><Add Service>. The service itself will need to be assigned a role, as illustrated below:

Figure 8-4    Assigning a role to a service

---

Note	If no role is available you may have to define a role. Consult the Configuration and Installation Guide for more details about this.

---