Chapter 2   Presentation logic


When an iPlanet Trustbase Transaction Manager implementation, on receiving a message, routes the message through to its appropriate service, and the service cannot directly act upon this message, iPlanet Trustbase Transaction Manager utilises the Connection Manager component to process messages appropriately.

Overview

---

The iPlanet Trustbase Transaction Manager presentation components comprise of a set of protocol handlers, message readers and message writers. The purpose of the protocol handlers is to extract the transport specific headers and footers, determine the MIME type and message type, and to forward the message content to an appropriate message handler.

The message handlers are selected on the basis of the MIME and Message type determined by the protocol handlers. The iPlanet Trustbase Transaction Manager provides two default message handlers, these are:

• Identrus XML messages

• HTML messages

In the case of the Identrus XML message, the appropriate Identrus network processing is performed as described in the following sections.

Figure 2-1    Presentation layer components

In the case of HTML requests, the message reader converts all of the fields in the HTML form into an XML structure represented by a set of DOM nodes.

In both the cases of XML and HTML the output to the router is wrapped with the session information into an iPlanet Trustbase Transaction Manager message. These iPlanet Trustbase Transaction Manager messages are then sent, by the router, to the appropriate service.

The services perform the appropriate message transformation or construction and return an iPlanet Trustbase Transaction Manager message back to the router. The router will then send the iPlanet Trustbase Transaction Manager message back to an appropriate message writer. In the case of the HTML message writer this will extract the DOM values in the message into an HTML template determined by the message type. The template may contain a set of directives that allow conditional or recursive construction of form data.

Protocol handlers

---

When the platform receives a message, the protocol handler is selected on the basis of the MIME type of the incoming message and is then invoked. The function of this component is to determine the application protocol information, specifically:

• Message type

• Context ID

Each MIME type, and therefore protocol handler, represents a class of messages e.g. application/OCSP. The client must be capable of generating the appropriate MIME type.

• HTML Protocol Handler If the client is a Web browser it normally generates a MIME type of application/x-www-form-url-encoded. iPlanet Trustbase Transaction Manager comes supplied with the default Protocol Handler for use in this situation. Its default actions are to:

• Search the form fields for:
  • Message Type - Identifying the message type

  • Context ID - Identifying the Context Identifier

• To set the response MIME type to text/html indicating to the Browser that the reply is a standard HTML page.

Identrus protocol handler

The protocol handler does the initial message processing for all messages arriving at the TC with a mime-type that begins with the following string: "application/identrus-".

Once at the protocol handler the following actions are carried out in the following order:

• The raw XML stream is read from the client.

• The raw XML is parsed into the internal iPlanet object structure (known as the message tree)

• The message tree is then validated against the DTD for that message that is specified by the DOCTYPE in the XML message.

• The message tree is traversed and any ID attributes are checked to ensure that there are no duplicates. This is a mandatory XML processing step, and is especially important where XML structures will be digitally signed.

• The system identifier from the DOCTYPE tag is placed into a iPlanet Trustbase Transaction Manager Message Attribute identified by IdentrusConstants.SYSTEM_ID_ATTR.

• Elements from the NIB are extracted ready for Raw Message Logging.

• The Certificate Bundle is extracted from the message and all of the certificates are logged in the Certificate Log.

• The message, minus its Certificate Bundle, is sent to the Raw Message Log.

• The Raw Log Id is returned from the log and placed into a iPlanet Trustbase Transaction Manager Message Attribute identified by IdentrusConstants.RAW_RECORD_MARKER

• The iPlanet Trustbase Transaction Manager Message type is set to be IdentrusConstants.IDENTRUS_MESSAGE

• The message tree is attached to the iPlanet Trustbase Transaction Manager Message as serialised content, ready to be sent to the appropriate message reader.

  
  

  ---

  Note	The variable DOCTYPE is an XML concept. See for instance http://www.w3.org/TR/REC-xml. The constants SYSTEM_ID_ATTR, RAW_RECORD_MARKER and IDENTRUS_MESSAGE are Identrus Constants. See com.iplanet.trustbase.identrus.IdentrusConstants for more information on Identrus constants.

  ---

  
  

Message Readers

---

The appropriate message reader is invoked based on the information gathered by the protocol handler. Each Message Reader will have an implicit understanding of the class of messages it can convert into an internal iPlanet Trustbase Transaction Manager message.

Default Message Reader, HTTP/HTML Reader

iPlanet Trustbase Transaction Manager comes with a pre-registered HTTP/HTML Message Reader that takes an application/x-www-form-url-encoded type. This is registered as a default message reader, meaning that if the message reader registry is unable to make a specific match to the message type detected by the host environment adapter then the default HTTP/HTML message reader will be returned. If the MIME type is anything other than application/x-www-form-url-encoded an error is returned.

Once the appropriate message reader has been found it is then passed an iPlanet Trustbase Transaction Manager Message object and the input stream containing the remaining unprocessed message content. The message reader reads and parses this message content from the input stream and creates a data block containing an internal representation of the message content. This is then stored in the iPlanet Trustbase Transaction Manager Message object for use by the appropriate service(s).

Once the message reader has parsed the input stream, and completed construction of the iPlanet Trustbase Transaction Manager Message, the message analyser passes the iPlanet Trustbase Transaction Manager Message on to the Router, and handles any errors or exceptions that result from the subsequent processing of the iPlanet Trustbase Transaction Manager Message.

Using the default HTTP Reader

The HTTP reader performs a relatively simple extraction of information from the input stream. Each input field is extracted from the HTTP Post or Get string and placed into a DOM structure. Once all the fields have been extracted this DOM Object is stored within the iPlanet Trustbase Transaction Manager Message. If the user does not specify the structure of the DOM object then each field is stored as an attribute of a node HTTP_VALUES,

HTTP HTTP_VALUES Attributes [<field_name> = <value>]*

However it is possible for the developer to force the fields to be stored in a more complex structure using certain escape sequences.

In order to create your own DOM structure the HTTPReader class has the ability to recognise an escape sequence contained in place of an input field name: <input name="$|xml:<node1>...<noden>|$">. For example:

<input name="$|xml:message.user.name|$"> <input name="$|xml:message.user.address|$"> <input name="$|xml:message.user?jobtitle|$">

This will lead to a set of nodes being created under the root HTTP node containing the following data:

HTTP HTTP_VALUES Attributes [<field_name> = <value>]* message user Attribute jobtitle=<value> name = <value> address = <value>

Default Message Reader, Identrus Reader

This message reader will handle messages with a mime-type that begins with "application/identrus-" and a message type of IdentrusConstants.IDENTRUS_MESSAGE.

Once at the message reader the following actions are carried out:

• Signature check the mandatory DSIG signature

• Verify the certificate chain in the message, and ensure that the root certificate of the chain is in the database. Ensure that the root of the chain has a Certificate Store attribute of IdentrusConstants.IR_CA.

• Set the security context on the iPlanet Trustbase Transaction Manager Message ready for the authorisation phase in the router.

• Make a billing log entry for the message

The message is then sent for routing.

Default Message Reader, Identrus Error Reader

This message reader will handle messages with a mime-type of "application/identrus-identrustransporterror" and a message type of IdentrusConstants.IDENTRUS_TRANSPORT_ERROR

Once at the message reader the following actions are carried out:

• There is no signature to check on an incoming "Identrus Transport Error", so the security context on the iPlanet Trustbase Transaction Manager Message is left unset. Messages arriving through this reader should only be coming through the connector, so they should never go to the router.

Message Writers

---

Once a message has been routed through to one or more services and returned to the Router, it is passed back to the Message Analyser (this assumes no exceptions or errors are thrown). At this point the message analyser is required to determine which Message Writer to be used to process the returned iPlanet Trustbase Transaction Manager Message into a suitable form for return to the user. As with message readers the analyser uses the Messages returned type and response MIME type values to select the appropriate message writer.

The message writer is responsible for extracting information contained in the iPlanet Trustbase Transaction Manager Message and processing it into a format that can be written back to the client.

To register the message writer with the registry iPlanet Trustbase Transaction Manager is supplied with an HTML management interface. This allows the developer to register new Message Writer sub-classes in the internal configuration store associated with iPlanet Trustbase Transaction Manager. Alternatively registration may be undertaken by adding the appropriate entries to the tbase.properties file. To achieve this, new Message Writers should be added to the [MessageWriter] section and take the form:

message.writer=<name>:<classpath> message.writer= Script:uk.co.jcp.tbaseimpl.parse.message.http.ScriptWriter

where the <name> is a name given by the developer and the <classpath> is the fully qualified classpath of the new MessageWriter instance. It is important to note that if you add new Message Writers through the management interface and at a later date it becomes necessary to restart iPlanet Trustbase Transaction Manager using the properties file then all changes will be lost. So it is as well to add entries to the properties file even if you are using the management interface.

Default HTML Message Writer

iPlanet Trustbase Transaction Manager comes with a pre-registered HTML message writer that takes a text/html MIME type. This is registered as a default message writer, meaning that if the message writer registry is unable to make a specific match to the message type and MIME type detected by the host environment adapter then the default HTML message reader will be returned. If the MIME type is anything other than text/HTML an error is returned.

This MessageWriter is capable of translating XML fields contained in the message into an HTML form using pattern matching and templates similar to many other Dynamic HTML writers.

The ScriptWriter, the default HTML Message Writer, uses a scripting language that is intended to provide a simple way to display uncomplicated information quickly and efficiently without having to recourse to a full XSL.

This is intended for use where the response is expected to contain text (usually HTML), and the information returned by the router is simple enough to allow straightforward substitution of values from the returned XML into the Template.

The ScriptWriter class works by taking the DOM object contained in the returned message and extracting all the fields therein. These fields are then substituted into the template that is selected by using the type and format of the returned message type. The substitution is achieved using a series of Script Tags that allow the developer to specify which parts of the returned message are to be placed where in the template. The templates used by the ScriptWriter may be configured in one of two ways, either through the iPlanet Trustbase Transaction Manager HTML management interface or by adding the appropriate entries to the tbase.properties file in the [ScriptWriter] section as illustrated below:

writer.typeandformat=<format>:<type>:<template> writer.typeandformat=text/html:TimeServiceTimeResponse:Config\Templates\ TimeService\TimeServiceTimeResponse.html

Where the <format> is text/html, <type> is the message type that will have been set by the service that last processed the message before it was returned, and <template> is the name of the template file. This file may either be an absolute path or a relative path, if it is a relative path then an entry is required to specify the location of the 'root':template.directory=.\ (note the trailing '\' which is required)

Script Tags

There are four main tags used in the script templates:

• $$xml:<XML Variable Name>$$

This represents the single substitution of a variable from the XML Document into the template. <XML Variable Name> is the fully qualified 'location' of a node in the XML Document returned by the router which is expected to contain a string value that may be substituted into the template. For instance, to retrieve the name from an XML Document one might specify the tag,

$$xml:message.content.user.name$$

This tag is also capable of specifying an attribute from a given XML node using the "?" escape sequence to select the given attribute. For example, in order to retrieve users middle initials that are stored as an attribute of their name, one might specify the following tag,

$$xml:message.content.user.name?middle_initials$$

• $$repeat:<XML Array Name>[<UserDefined Tag Name>:<Iterations>]$$...$$/repeat$$

Represents the start point for a repeating array of values contained in XML Document.

<XML Array Name> is the fully qualified 'location' of an array in the XML Document.

<UserDefined Tag> Name allows the template author to provide a shorthand name for this array location, e.g. If the array represents the address of a user, Response.Content.User.Address, then the author could tag this as address for ease of use within the repetition block.

<Iterations> tag allows the author to specify which 'parts' of the array are to be displayed.

Table 2-1    XML Repeat Iterators

Iterator	Description	Example
*	Iterate over all items contained in the specified array	*
<n>	Select the nth element of the array, if the array has less than n elements then nothing is displayed	2
<m>-<n>	Select from the mth to the nth elements (inclusive), if the array has less than n elements then this selects from m to the end, if the array has less than m elements then nothing is displayed	3-5
<m>-*	Select all elements from the mth up to the last element in the array	2-*
<attribute>=<value>	Select ALL the elements in the array where the specified attribute equals the given value	location= London
,	Allow multiple iterators to be specified together	0,3-5,9,postcode=EC1

Every repeat block is terminated with a $$/repeat$$ statement.

• $$xif:<XML Variable Name>[="<value>"]$$ ... $$/xif$$

Represents a conditional tag. In its simplest form this tag says iterate everything contained within the conditional statement if the node (or attribute - using the same "?" escape sequence) is found to exist within the XML.

If the "=" is used however, not only does the node or attribute have to exist but the value has to be an exact (case sensitive) match of the one specified. For example one might specify a conditional block say only print the user details if the job title matches "SysAdmin" as follows:

$$xif:message.content.user?jobtitle="SysAdmin"$$

Associated with the $$xif:...$$ tag there is also an $$xelse:...$$ tag to provide optional switching. This tag has two modes of use:

$$xelse$$

Simple usage, if the $$xif:...$$ condition is unfulfilled then this condition is used instead. One might use this sequence if it is necessary to use two different display formats based on the contents of an XML node.

$$xelse:<XML Variable Name>[="<value>"]$$

Uses the same format as the xif statement to determine if this branch should be executed. This provides extra conditional switching which can be used to make more complex decisions about which sections of the template are to be used.

• $$xprop:[<section>]<property>[=<default_value>]$$

This is a special tag that is used to incorporate property's values from the tbase.properties file into the template. This allows different application server environments to be supported by the same template by changing the property value for each server type. The $$xprop:...$$ tag is also special in that it is pre-processed before any of the other tags are dealt with, thus it is possible to include other tag information (except $$xprop:...$$ itself) in the properties.

• <section> the name of the section that contains the property, if this is left out, the section used is the ScriptWriter section.

• <property> the name of the property that is to be used.

• <default_value> a default value to be used if the property is not found, if this is not specified and the property is not found then an empty string is returned.

Using the ScriptWriter tags

• $$xml:...$$ substitution

As documented above this tag represents a straightforward substitution of a single value contained in the returned XML Document, into the HTML Template. In the following template snippet, we can see that the author expects the XML Document returned from the router to contain data indicating an administrative support mail address.

<P> <FONT SIZE=-2> Please try our <A HREF="mailto:$$xml:response.content.supportaddress$$">Support Desk</A> if you have any enquiries </FONT> </P>

• $$xml:...$$ filtering

It is also possible to introduce an attribute filter into the qualified path, as shown in the code snippet below:

<P> Email the <A HREF="mailto:$$xml:response.content.user?title="SysAdmin".email$$" >System Administrator</A> if you have any enquiries regarding your login details. </P>

Here the XML Document contains an array of one or more user's details and each user contains a node that contains their email address. We use the user title attribute to determine which of the users job description is System Administrator and use the resultant user to extract the email address.

• $$repeat:...$$ loop

The following example shows the complete usage of a repeat block, including the $$/repeat$$. Here the author is indicating the XML Document response will contain an array of transactions, under the node http_response.content.transaction. This section of the XML Document tree is then tagged as txn.

Inside the repeat block, one then uses the standard $$xml:...$$ notation to select data contained in each member of the array returned.

Each transaction will contain three nodes date, description and amount. These will be filled into a single table row and the table will contain as many rows as there are transactions returned.

<table BORDER="1" BGCOLOR="#fff0a0"> <th COLSPAN="3" BGCOLOR="ffd080"><b><i><font SIZE="+1" COLOR="#00a000">Statement Details</font></i></b></th> <tr> <td WIDTH="50" ALIGN="center"><B>Date</B></td> <td WIDTH="400" ><B>Description</B></td> <td WIDTH="200" ALIGN="center"><B>Amount</B></td> </tr> $$repeat:message.content.transaction[txn:*]$$ <tr> <td>$$xml:[txn].date$$</td> <td>$$xml:[txn].description$$</td> <td ALIGN="right">$$xml:[txn].amount$$</td> </tr> $$/repeat$$ </table>

• Nesting $$repeat:...$$ blocks

It is also possible to nest repeat blocks, if we consider the users example again it might be that each user node contains an array of address nodes (one per line of their address) and hence we might wish to iterate over the address lines for each user. The following template snippet shows how this might be done:

<table BORDER="1" BGCOLOR="#fff0a0"> <th COLSPAN="3" BGCOLOR="ffd080"><b><i><font SIZE="+1" COLOR="#00a000">System Users</font></i></b></th> <tr> <td WIDTH="100" ALIGN="center"><B>Name</B></td> <td WIDTH="400" ALIGN="center"><B>Address</B></td> <td WIDTH="100" ALIGN="center"><B>Telephone</B></td> </tr> $$repeat:message.content.user[user:*]$$ <tr> <td>$$xml:[user].name$$</td> <td> $$repeat:[user].address[addr:*]$$ $$xml:[addr]$$<br> $$/repeat$$ </td> <td>$$xml:[user].telno$$</td> </tr> $$/repeat$$ </table>

• $$xif:...$$

In this case, we will extend the repeat example to show how we might need to perform a conditional display. In this case the phone number column either displays a home phone number for all teleworkers or an internal extension for those based in the office.

<table BORDER="1" BGCOLOR="#fff0a0"> <th COLSPAN="3" BGCOLOR="ffd080"><b><i><font SIZE="+1" COLOR="#00a000">System Users</font></i></b></th> <tr> <td WIDTH="100" ALIGN="center"><B>Name</B></td> <td WIDTH="400" ALIGN="center"><B>Address</B></td> <td WIDTH="100" ALIGN="center"><B>Telephone</B></td> </tr> $$repeat:http_response.content.user[user:*]$$ <tr> <td>$$xml:[user].name$$</td> <td> $$repeat:[user].address[addr:*]$$ $$xml:[addr]$$<br> $$/repeat$$ </td> <td> $$xif:[user].workType="Teleworker"$$ $$xml:[user].homePhone$$ $$xelse$$ $$xml:[user].workExtn$$ $$/xif$$ </td> </tr> $$/repeat$$ </table>

• $$else:...$$

Lastly, it is possible to perform a multiple conditional statement using the extendedlse construct. Taking the previous example we can extend the switch to include an extra case for salesmen.

<td>      $$xif:[user].workType="Teleworker"$$                     $$xml:[user].homePhone$$      $$xelse:[user].workType="Sales"$$                     $$xml:[user].mobile$$      $$xelse$$                     $$xml:[user].workExtn$$      $$/xif$$ </td>

• $$xprop:...$$ property substitution

The code snippet below shows how to get a property from the tbase.properties file into a template:

<hr> <form METHOD=post ACTION="$$xprop:[ApplicationServcer]form.string$$/appservlet">      <h3> Please enter your card details so that we may confirm your identity: </h3>

Default Identrus Message Writer

This message writer will handle messages with a mime-type that begins with "application/identrus-" and a message type of IdentrusConstants.IDENTRUS_MESSAGE.

Once at the message writer the following actions are carried out:

• Sign the message with the IdentrusConstants.L1_IP_SC certificate, unless the iPlanet Trustbase Transaction Manager Message attribute identified by IdentrusConstants. SIGNING_CERT_ATTR is present. If this attribute is present then its value is taken as the purpose Id of the certificate/key used to sign the outgoing message.

• The outgoing message is DTD validated according to its DOCTYPE, this prevents malformed messages from leaving the TC.

• The DOCTYPE tag is set and the mime-type of the message is determined from the DOCTYPE

• The Certificate Bundle is extracted from the message and logged with the Certificate Log

• The XML of the outgoing message, minus the Certificate Bundle, is recorded in the message log

• The message is written back to the client.

Default Identrus Error Writer

This message writer will handle messages with a mime-type of "application/identrus-identrustransporterror" and a message type of IdentrusConstants.IDENTRUS_TRANSPORT_ERROR

Once at the message writer the following actions are carried out:

• The outgoing message is DTD validated according to its DOCTYPE, this prevents malformed messages from leaving the TC.

• The DOCTYPE tag is set and the mime-type of the message is determined from the DOCTYPE

• The XML of the outgoing message is recorded in the raw log

• The message is written back to the client.

Connection Manager

---

On receiving a message iPlanet Trustbase Transaction Manager routes this message to an appropriate service which can process the message accordingly, and can, if required return a message in response. A problem arises when the particular iPlanet Trustbase Transaction Manager implementation, on receiving a message, routes the message through to its appropriate service, and the service cannot directly act upon this message. It needs additional information from another source in order to complete the task presented to it by the received message. Hence, iPlanet Trustbase Transaction Manager needs the facility to create new messages using specific message transport protocols and send these messages to specific external destinations. To accomplish this, the service needs to call the "Connection Manager".

Figure 2-2    Connection Manager Architecture

---

Note	Please consult your API for more information about this: uk.co.jcp.tbase.connector uk.co.jcp.tbase.xurl uk.co.jcp.tbaseimpl.connector

---

The Connection Manager is essentially a service that can be used to send and receive messages to and from external entities. The Connection Manager is passed a iPlanet Trustbase Transaction Manager message and Destination Object. It uses this information to send and receive messages related to the specific message/destination object supplied. The Connection Manager Message Process works as follows:

• The Service calls the Connector, passing the iPlanet Trustbase Transaction Manager Message containing the request to the external resource, and a Destination Object describing the external resource. Destination Objects are application-defined implementations, and are recognised by ProtocolMap objects that are application defined plug-in components to the Connector. A null Message parameter may be passed, in which case no attempt will be made to write data to the URLConnection object when a connection has been established.

• The Connector calls the ProtocolMapManager to translate the Destination Object it was supplied with into a ProtocolDescriptor Object that specifies a URL for the connections, and a mime-type for the request content. The ProtocolMapManager determines which ProtocolMap from those registered with it (an administration activity ) is responsible for dealing with the supplied Destination implementation, and passes the Destination Object to the ProtocolMap.

• The ProtocolMap translates the Destination Object into a ProtocolDescriptor . This action may be simple and local, or it may be complex and involve further external requests.

• The Connector makes a connection to the external resource using the URL in the ProtocolDescriptor to form a URLConnection.

• If a Message was passed to the Connector, it sets the doOutput variable on the URLConnection to true, to signify it's intention to write data to the connection. The Connector then selects a MessageWriter from its registry of MessageWriters, according to the type of the Message to be written (in the message Type attribute), and the required format, as specified in the ProtocolDescriptor. The MessageWriter is called to translate the Message to the appropriate format, and write it to the OutputStream of the URLConnection. Should no Message have been passed to the Connector, the doOutputfield of the URLConnection is set to false, then nothing is written to the URLConnection..

• The Connector hands the InputStream of the URLConnection to the ConnectionProtocolAnalyser, along with the mime-type of the response [determined from the URLConnection]. The ConnectionProtocolAnalyser determines a ProtocolHandler to call, using the mime-type of the response.

• The ConnectionProtocolAnalyser gives the selected ProtocolHandler a new iPlanet Trustbase Transaction Manager Message, and the InputStream . The ProtocolHandler reads from the InputStream to determine the Message type of the response, which it sets on the Message (it may also set a Context identifier, although this will be ignored in this setting), before returning.

• The Connector selects a MessageReader based on the response Message type, and the response InputStream mime-type. The MessageReader is called to complete the parsing of the response. After the MessageReader completes, the Connector releases any resource used in making the external connection, and returns the parsed Message to the requesting Service.

  
  

  ---

  Note

  iPlanet Trustbase Transaction Manager provides a default connector that implements the connector interface defined in uk.co.jcp.tbaseimpl.connector.DefaultConnector. Most of these classes are supplied as part iPlanet Trustbase Transaction Manager. Some are not. For instance, java.net.URLConnection is part of the core Java API.

  ---

  
  

Protocol Map Manager

The Connection Manager provides the ability for Services in the iPlanet Trustbase Transaction Manager framework to communicate with other external entities. To do this the Service passes a message and Destination to the Connector (Connection Manager), which routes the message to the specific external entity. To find the address of the communicating party, the supplied Destination is passed to the ProtocolMapManager. This ProtocolMapManager then passes the Destination to its associated ProtocolMap registered with the ProtocolMapManager. The specific ProtocolMap then returns a ProtocolDescriptor object associated with this Destination. Each specific ProtocolMap decides which ProtocolDescriptor to return for any supplied Destination.

To create a new application specific protocol mapping system, the following steps have to be followed:

• Creation of a Specific ProtocolMap.

• Creation of a Specific Destination

• Registering the new ProtocolMap with the ProtocolMapManager.

• Populating the ProtocolMap with data.

  
  

  ---

  Note	Please consult the framework uk.co.jcp.tbase.connector and the default connection manager class implementation can be found in uk.co.jcp.tbaseimpl.connector.

  ---

  
  

These are now described in turn.

• Creation of a Specific ProtocolMap

All ProtocolMap objects must implement the ProtocolMap interface. They must also provide an empty/default constructor, due to the fact that the ProtocolMapManager will dynamically instantiate the ProtocolMap object in order to register the class with itself.

The ProtocolMap enforces the following methods:

public Enumeration getDestinationTypes()

Returns a list of the package qualified class names of the Destination implementations that this ProtocolMap recognises.

public ProtocolDescriptor getProtocolDescriptor(Destination destination)      throws InvalidDestinationException

Translates an application's specified Destination object into a ProtocolDescriptor, specifying the URL and mime type for the connection.

---

Note	The application specific ProtocolMap must not contain any objects that are not serializable, as the ProtocolMapManager has persistence. Consult your API uk.co.jcp.tbase.connector.ProtocolMap for more information on this.

---

• Creation of a Specific Destination

All Destinations must implement the Destination interface. This interface does not enforce any methods, leaving all methods and data purely application specific, thus relying on its associated ProtocolMap to have prior knowledge of its format.

---

Note	The application specific Destination must not contain any objects that are not serializable, as the ProtocolMapManager has persistence. Consult your API uk.co.jcp.tbase.connector.Destination for more information on this.

---

• Registering the new ProtocolMap with the ProtocolMapManager.

Once an application specific ProtocolMap and Destination have been constructed, the ProtocolMap has be registered with the ProtocolMapManager before any Service in iPlanet Trustbase Transaction Manager can utilise its function.

---

Note	If a new application specific ProtocolMap contains a reference to a specific Destination used by an existing ProtocolMap registered with the ProtocolMapManager then the new ProtocolMap will be prevented from registering with the ProtocolMapManager.

---

Protocol Maps can be registered in the tbase.properties file that contains a property section called "ProtocolMapManager". In this section the application specific ProtocolMap objects can be supplied. For instance,

[ProtocolMapManager] protocol.map=uk.co.jcp.tbase.connector.SimpleProtocolMap

---

Note	This tbase.properties file will only be read once unless the configuration object associated with the instance of iPlanet Trustbase Transaction Manager is removed. Note also, the full package name must be supplied.

---

URL Connection Implementation

Internally in the Connection Manager, once the ProtocolMapManager returns a ProtocolDescriptor from a supplied Destination, the URL string representation is obtained from the ProtocolDescriptor. From this string representation of a URL, an URLConnection object is obtained, from which the output and input streams are used to send and receive the message from the Connection Manager (Connector). This conversion of a string representation of a URL to a URLConnection object is carried out through the XURLxxxxx classes. The classes used are:

• XURL

• XURLStreamHandler

• XURLStreamHandlerFactory

These classes are needed, due to the fact that the existing URL class hierarchy supplied by javasoft is not extensible in an EJB format. This is because in the existing framework, if the URL class does not recognise an URL format then it looks to see if a XURLStreamHandlerFactory is loaded, which could supply the unknown URL format. This factory can only be set once, so in an EJB environment it is impossible to ascertain whether URLStreamHandlerFactory has been instantiated, so making this framework unusable. Hence, we have produced an extensible framework that can work in any environment. These objects are identified as XURL, XURLStreamHandler, and XURLStreamHandlerFactory.

The process flow is as follows:

• A XURL object is constructed using the string representation of the URL supplied by the ProtocolDescriptor.

• To obtain the URLConnection object the XURL's method openConnection() is called.

• Inside this method the XURLStreamHandlerFactory is called.

• The XURLStreamHandlerFactory, if not called before initialises itself from the tbase.properties file, registering XURLStreamHandler classes in the section "XURLStreamHandlerFactory", each class mapped against the value "url.stream.protocol".

• The XURLStreamHandlerFactory is searched using the protocol that will be used to connect to the specified URL as the key.

• If the protocol supplied maps to a XURLStreamHandler registered with the XURLStreamHandlerFactory, then the XURLStreamHandler object is called in order to provide the URLConnection object required.

• If the protocol does not match any XURLStreamHandlers stored within the XURLStreamHandlerFactory, then an URL object is created from the supplied string representation in the XURL, and the URLConnection object is obtained directly from that.

Providing this extra framework, JCP supplies the ability to override existing protocol formats, in order to introduce any specific enhancements, i.e. HTTPS, where our SSL is directly tied in with our Certificate Storage interfaces.

---

Note	Please consult your API for more information this: uk.co.jcp.tbase.xurl.

---