Development and deployment

The following sections describe development and deployment for user-created receivers and handlers.

Development environment

The receiver and receiver handler development API relies on classes and interfaces from two packages:

These packages are part of the bcgsdk.jar file, which is found among the installable WebSphere Partner Gateway files in the following directories:

In all deployed instances, the bcgsdk.jar file is installed in the application server classpath.

For development, the bcgsdk.jar file must be included in the build path of the project that contains the user exit classes, that is, in the classpath.

Deployment and packaging (receivers)

All user-created code needs to be made available to the run-time environment. Package and deploy user-created code in one of the following ways for use during runtime:

Adding the JAR or class files to the run-time environment makes them available only if the transport or handler is configured to be used by the run-time library. Receiver transports and handlers are configured for use like the other product-provided transports and handlers. In order to configure them you must first make them known to the Community Console. You do this by importing their definitions into the Community Console by means of an XML descriptor file.

To import a Receiver transport, click Hub Admin > Hub Configuration > Targets > Manage Transport Types.

To import a Receiver transport handler, click Hub Admin > Hub Configuration > Handlers > Target > Import. One of the descriptors is the Handler Type. Only defined Handler Types are allowed and are based on the transport target configuration points. For user-defined transports, the transport descriptor file must be imported first in order to provide the handler type.

Descriptor file definition for a receiver transport

The receiver transport descriptor file uses the bcgtarget.xsd schema. Following is a brief outline for each of the elements in the descriptor file based on the following example:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (c) 2004 IBM Corp. - All Rights Reserved.-->
<!-- IBM makes no representations or warranties about the suitability of -->
<!-- this program, either express or implied, including but not limited to -->
<!-- the implied warranties of merchantability, fitness for a particular -->
<!-- purpose, or non-infringement. -->
<tns:TargetDefinition
         xmlns:tns="http://www.ibm.com/websphere/bcg/2004/v0.1/import/external"
     xmlns:tns2="http://www.ibm.com/websphere/bcg/2004/v0.1/import/external/types"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.ibm.com/websphere/bcg/2004/v0.1/import/external
     bcgtarget.xsd http://www.ibm.com/websphere/bcg/2004/v0.1/import/external/types
     bcgimport.xsd">
<tns:TargetClassName>com.mycompany.MyHTTPTransport</tns:TargetClassName>
<tns:Description>My company HTTP Transport</tns:Description>
<tns:TransportTypeName>MYHTTP</tns:TransportTypeName><tns:TransportAttributes>
<tns2:ComponentAttribute>
<tns2:AttributeName>URI</tns2:AttributeName>
<tns2:AttributeDefaultValue>localhost</tns2:AttributeDefaultValue>
</tns2:ComponentAttribute>
<tns2:ComponentAttribute>
<tns2:AttributeName>Timeout</tns2:AttributeName>
</tns2:ComponentAttribute>
</tns:TransportAttributes>
<tns:TargetConfigurationPoints>
<tns:Preprocess>RECEIVER.PREPROCESS.MYHTTP</tns:Preprocess>
<tns:SyncCheck>RECEIVER.SYNCCHECK.MYHTTP</tns:SyncCheck>
</tns:TargetConfigurationPoints>
</tns:TargetDefinition>

A description of the XML elements follows:

TargetClassName
The full class name of the Receiver implementation
Description
General description for the transport
TransportTypeName
The name that appears in the Transport drop down list in the Console Target List page
TransportAttributes (optional)
Any attributes that this transport can have
ComponentAttribute
An attribute name and default value that are used to provide configuration information to the target at runtime
AttributeName
The name of a specific attribute
AttributeDefaultValue (optional)
The attribute's default value
TargetConfigurationPoints (optional)
The names of the configuration points that this transport has
Preprocess
A preprocess configuration point, RECEIVER.PREPROCESS.xxx where xxx is the value of the TransportTypeName
SyncCheck
A SyncCheck configuration point, RECEIVER.SYNCCHECK.xxx where xxx is the value of the TransportTypeName
SyncResponseProcess
A SyncResponseProcess configuration point,RECEIVER.SYNCRESPONSEPROCESS.xxx where xxx is the value of the TransportTypeName

Any handlers defined for this receiver transport must match one of these TargetConfigurationPoints values.

Descriptor file definition for a receiver transport handler

The receiver transport handler descriptor file uses the bcghandler.xsd schema. Following is a brief outline for each of the elements in the descriptor file based on the following example:

<?xml version="1.0" encoding="UTF-8"?>
<tns:HandlerDefinition
     xmlns:tns="http://www.ibm.com/websphere/bcg/2004/v0.1/import/external"
     xmlns:tns2="http://www.ibm.com/websphere/bcg/2004/v0.1/import/external/types"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.ibm.com/websphere/bcg/2004/v0.1/import/external
     bcghandler.xsd http://www.ibm.com/websphere/bcg/2004/v0.1/import/external/types
     bcgimport.xsd ">
<tns:HandlerClassName>com.mycompany.RecvHandler</tns:HandlerClassName>
<tns:Description>My companies handler for my business protocol and multiple
     transports.</tns:Description>
<tns:HandlerTypes>
<tns:HandlerTypeValue>RECEIVER.PREPROCESS.MYHTTP</tns:HandlerTypeValue>
<tns:HandlerTypeValue>RECEIVER.PREPROCESS.JMS</tns:HandlerTypeValue>
</tns:HandlerTypes>
<tns:HandlerAttributes>
<tns2:ComponentAttribute>
<tns2:AttributeName>Attribute 1</tns2:AttributeName>
</tns2:ComponentAttribute>
<tns2:ComponentAttribute>
<tns2:AttributeName>Attribute 2</tns2:AttributeName>
<tns2:AttributeDefaultValue>Attribute2DefaultValue</tns2:AttributeDefaultValue>
</tns2:ComponentAttribute>
</tns:HandlerAttributes>
</tns:HandlerDefinition>

A description of the XML elements follows:

HandlerClassName
The full class name of the handler implementation.
Description
General description for the handler.
HandlerTypes
The handler types with which this handler can be used. For transports, the handler type corresponds to the TargetConfigurationPoints value defined for that transport. To see a list of the currently defined transport Handler Types, click Hub Admin > Hub Configuration > Handlers > Target > HandlerTypes.
HandlerTypeValue
The HandlerType value that corresponds to the TargetConfigurationPoints value. A handler can be associated with more than one transport type.
HandlersAttributes (optional)
The attributes, if any, for this handler.
ComponentAttribute
An attribute's name and default values that are used to provide configuration information to the handler at runtime.
AttributeName
The name of a specific attribute.
AttributeDefaultValue (optional)
The attribute's default value.

Reserved attribute names

Every target configuration has the following two reserved attribute names:

ACTIVESTATUSCD
An attribute whose value indicates whether the target of a receiver is enabled or disabled. You can enable or disable a target from the Community Console. If a target is enabled, this attribute has a value of 1. Do not obtain the value of this attribute at runtime from the configuration of the target by using the constant BCGDocumentConstants.BCG_TARGET_STATUS. While developing a receiver, do not define ACTIVESTATUSCD as an attribute in the receiver's deployment descriptor.
DESTNAME
An attribute whose value indicates the gateway type associated with the target. Every target has a gateway type associated with it. The gateway type can be configured from the Community Console while configuring a target. A gateway type is required for determining the participant connection. You can obtain the value of this attribute at runtime from the configuration of the target by using the constant BCGDocumentConstants.BCG_TARGET_DESTINATION. While developing a receiver, make sure that you do not define DESTNAME as an attribute in the deployment descriptor of the receiver. For every business document received by a target, the receiver creates an object of type ReceiverDocumentInterface, also referred to as a receiver document. The receiver sets the BCGDocumentConstants.BCG_RCVR_DESTINATION attribute on the receiver document. The value of this attribute should be same as the value of the BCGDocumentConstants.BCG_TARGET_DESTINATION attribute from the target configuration. If BCGDocumentConstants.BCG_RCVR_DESTINATION is not set on the receiver document, the Document Manager cannot determine the participant connection for this document.

Copyright IBM Corp. 2003, 2005