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 JAXHIT 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/samples/ping/resources

  ---

  
  

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 following instructions assume that you are using a Bourne Shell or derivative, and that you have a JDK (at least v1.2.2) installed.

1.    From the Trustbase installation directory change into the Scripts sub-directory:

   cd Scripts

2.    Set the shell CLASSPATH environment variable to include all of the iTTM libraries

   . ./setcp

3.    Change directory into the Ping Sample resource directory

   cd ../samples/ping/resources

4.    Generate the classes from the ping.dtd file, using the JAXHIT tool

   ../../../Scripts/jaxhit -config IdentrusPingMessaging.xml -y

5.    Change directory to the parent directory and compile the generated classes

   cd ..

   javac -d build src/com/iplanet/trustbase/generated/IDENTRUS/PING_DTD/*.java

6.    Compile the ping service classes

   javac -d build -classpath $CLASSPATH:build src/com/iplanet/trustbase/identrus/ping/*.java

7.    Compile the ping client classes

   javac -d build -classpath $CLASSPATH:build src/com/iplanet/trustbase/identrus/tools/*.java

8.    Build all of the classes and the service descriptor file (build/config/tbasesvc.properties) into a JAR file which can be deployed into iTTM.

   jar -cvf pingsample.jar -C build com -C build config

9.    Make the new service JAR file available for deployment in iTTM

   cp pingsample.jar ../../current/deploy

Deploying pingsample.jar within iPlanet Trustbase Transaction Manager

• 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.

---