Chapter 9   Ping Example


The following sections use the Ping DTD as defined in the Identrus messaging specification to walk through the steps in the development cycle as described in the previous chapter. Developing a service prior to deploying it involves a number of steps.

1. Create your DTD definitions that specify the syntactic structure of the messages you wish to send round the system.

2. Use Classgen com.iplanet.trustbase.app.classgen.ClassGen to generate your java classes from your DTD definitions.

3. Write the Java code for the service using the Identrus API that assists the Identrus processing and validating of messages, certificates, keys and digital signatures.

4. Use the JDK JAR tool to build the final iPlanet Trustbase Transaction Manager service jar file.

5. Deploy the service within iPlanet Trustbase Transaction Manager by selecting the relevant configuration options as described below in this guide.

6. Finally, once it has been deployed within iPlanet Trustbase Transaction Manager itself you can run your service.

Create DTD Definitions

• This example uses the 'Ping' DTD defined in the Identrus Messaging specification and included below for completeness. Thus, create your DTD definitions which can be found in ping.dtd. (See IT-TCMPD, the Identrus TC Messaging Specification for the structure and definition of ping.dtd)

  <!--PUBLIC ID for this DTD is: "-//IDENTRUS//PING DTD//EN"--> <!ENTITY % CoreNetwork.dtd PUBLIC "-//IDENTRUS//CORE NETWORK INFRASTRUCTURE DTD//EN" "corenetworkinfrastructure.dtd"> %CoreNetwork.dtd; <!ELEMENT PingRequest (NIB, Signature, CertBundle, PingData)> <!ATTLIST PingRequest       id ID #REQUIRED > <!ELEMENT PingResponse (NIB, Signature, CertBundle, PingData)> <!ATTLIST PingResponse       id ID #REQUIRED > <!ELEMENT PingError (NIB, Signature, CertBundle, ErrorInfo)> <!ATTLIST PingError       id ID #REQUIRED > <!ELEMENT PingData (#PCDATA)> <!ATTLIST PingData       id ID #REQUIRED > <!ELEMENT ErrorInfo (VendorData*)> <!ATTLIST ErrorInfo       id ID #REQUIRED       errorCode NMTOKEN #REQUIRED > <!ELEMENT VendorData (#PCDATA)> <!ATTLIST VendorData       id ID #REQUIRED       dataType CDATA #REQUIRED >

• These link to other dtd files that are supplied with iPlanet Trustbase Transaction Manager and are listed below:

  XMLDSIG.dtd corenetworkinfrastucture.dtd Foundation.dtd

  
  

  ---

  Note	All dtd's can be found in <install-dir>/Trustbase/TTM/current/apidocs.

  ---

  
  

Prepare to execute the ClassGen tool by completing the following steps:

• Change directory to ../Trustbase/TTM/Scripts

• Set up the classpath ready for the ClassGen tool to be executed. This is done by sourcing the setcp script. E.g. ". ./setcp" in the standard shell.

• Make a new sub-directory called ping and make this the current directory

• Copy ping.dtd and each of the 3 core Identrus DTD's to the new directory. It is essential that the names of the DTD files are correct, they are case sensitive and their exact names can be found by looking inside the DTD files. The last attribute of an <!ENTITY ....> tag defines the local file name for the included DTD.

• Establish which options must be passed to the ClassGen tool, Table 9-1 shows each of the options for this example.

Table 9-1    Classgen Options

ClassGen Options for Ping DTD
-d .	Create the files in the current directory
-o ping.jar	Create the final jar called ping.jar
-r	Recurse through all sub-dtd's and generate any classes that do not already exist on the classpath.
-root PingRequest	The PingRequest element in the DTD is an eligible root element for an XML document.
-root PingResponse	The PingResponse element in the DTD is an eligible root element for an XML document.
-root PingError	The PingError element in the DTD is an eligible root element for an XML document.
-stub com.iplanet.trustbase.sample.PingService	Create the stub Identrus Service source code in the output directory; package the file in com.iplanet.trustbase.sample.
"-//IDENTRUS//PING DTD//EN"	This is the public identifier for the Ping DTD
Ping.dtd	The DTD from which class generation should begin.

This results in the following command being issued:

java com.iplanet.trustbase.app.classgen.ClassGen -d . -o ping.jar -r -root PingRequest -root PingResponse -root PingError -stub com.iplanet.trustbase.sample.PingService "-//IDENTRUS//PING DTD//EN" ping.dtd

The result of executing this command is the following:

• Many warnings on the screen. These warnings state that classes have not been generated for certain elements in the DTD's referenced from the ping.dtd. This is because these classes already exist on the classpath of iPlanet Trustbase Transaction Manager and therefore do not need to be regenerated.

• A file called ping.jar in the current directory. This contains the compiled message classes for the ping DTD.

• A sub-directory called src that contains the source code of all of the generated class files.

• A file called PingService.java in the current directory. This is the stub Identrus Service that needs to be updated with message processing code in the next stage.

With the JAR file and the stub service generated, you can now move to the next stage of the development of a service.

API

Before writing your Java code you'll need to know some of the core API that is supplied with iPlanet Trustbase Transaction Manager for handling Identrus Messages:

com.iplanet.trustbase.identrus

This package allows access to Identrus message Specification

com.iplanet.trustbase.identrus.message

This package provides the necessary routines to allow Identrus message processing

com.iplanet.trustbase.identrus.security

This package processes certificates and keys

com.iplanet.trustbase.util.tree

Searches tree

com.iplanet.trustbase.xml.dsig

Generates and validates XML Digital signatures, this package is not required if the only signatures on the messages are the mandatory level 1 signatures. These mandatory signatures are checked/generated automatically by iPlanet Trustbase Transaction Manager.

uk.co.jcp.tbase.config

This package interfaces with configuration objects

PingService Source Code

PingService.java - the generated service stub is an implementation of the abstract IdentrusService in which the ProcessIdentrusMessage method parameter is the message received by the TTM platform.

By the time the message arrives at this ProcessIdentrusMessage method, it has already passed mandatory signature validation checks and been raw logged.

The method must create a response message to the incoming request. Using the supplied Identrus API's this is simple.

package com.iplanet.trustbase.sample; import com.iplanet.trustbase.identrus.message.IdentrusMessage; import uk.co.jcp.tbase.service.ServiceException; import com.iplanet.trustbase.generated.IDENTRUS.PING_DTD.*; import com.iplanet.trustbase.generated.IDENTRUS.CORE_NETWORK_INFRASTRUCTURE_DTD .*; import com.iplanet.trustbase.identrus.IdentrusService; import com.iplanet.trustbase.identrus.message.*; import uk.co.jcp.tbaseimpl.log.error.*; import uk.co.jcp.tbase.service.*; /*** Stub Identrus service implementation. */ public class PingService extends IdentrusService {       public IdentrusMessage processIdentrusMessage( IdentrusMessage message )       {          if (message instanceof PingRequest)          {             // Handle PingRequest             PingResponse pr = new PingResponse();             PingData pd = new PingData();             pd.setPCDATA( "The ping was successful" );             pr.setPingData( pd );             try             {                NIBAccessor niba = NIBAccessor.getInstance( message.getNetworkInfoBlk(), "2" );                pr.setNetworkInfoBlk( niba );             }             catch (NIBAccessorException nie)             {                ErrorLog.log( new ErrorObject( "IDT0052", nie ));             }             return pr;          }          if (message instanceof PingResponse)          {             // Handle PingResponse          }          if (message instanceof PingError)          {             // Handle PingError          }             return message;       }       }

Having written this simple service it may be compiled ready to be built into a Service JAR.

Creating the Identrus Service JAR

The final step before deploying the service into iPlanet Trustbase Transaction Manager is to create the consolidated JAR file that contains all of the generated classes as well as the PingService class that has been developed by hand.

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 ../ping.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 ping.jar -C DumpDirectory DumpDirectory/*

• The jar file is now ready for deployment.

Deploying ping.jar within iPlanet Trustbase Transaction Manager

• Place ping.jar in the deploy directory. ...../Trustbase/TTM/current/deploy

• Logon to iPlanet Trustbase Transaction Manager as Administrator

• Deploy PingService within iPlanet Trustbase Transaction Manager. Select <Services> followed by <Deployment>.

• Since Ping.jar has been placed in the deploy directory automatically by the builder, iPlanet Trustbase Transaction Manager picks up all the relevant information and places this in the screen headed "Available services" as illustrated below.

• To deploy the service select
  
  followed by
  
  

Figure 9-1    Deploying PingService within iPlanet Trustbase Transaction Manager

• Services require registration. This is done automatically when the jar file is built from the builder tool. PingService can in fact be seen from the Configuration Console by selecting <Services> <Registry Configuration> as illustrated below:

Figure 9-2    Service Registry Configuration

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

Figure 9-3    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.

---