Appendix: Using the Integration Broker Connector SDK

This appendix provides an overview of the PeopleSoft Integration Broker connector software development kit (SDK) and discusses how to:

Click to jump to parent topicUnderstanding the PeopleSoft Integration Broker Connector SDK

This section discusses:

Click to jump to top of pageClick to jump to parent topicThe PeopleSoft Integration Broker Connector SDK

Target connectors generate message requests, send them to integration participants, wait for responses from participants, and deliver the responses back to the gateway manager. Listening connectors receive message requests from integration participants, send them to the gateway manager, and deliver responses back to the integration participants.

PeopleSoft Integration Broker is bundled with connectors for use with PeopleSoft, HTTP, Java Messaging Service (JMS), PeopleSoft 8.1x, File Transfer Protocol (FTP), and Simple Mail Transfer Protocol (SMTP) communication formats. You can use the PeopleSoft Integration Broker Connector SDK to build and implement connectors for other communication formats and application requirements.

Click to jump to top of pageClick to jump to parent topicSDK Contents

The PeopleSoft Integration Broker Connector SDK includes:

Click to jump to top of pageClick to jump to parent topicSDK Location

The following table lists the location of the SDK and its contents.

Item

Location

SDK

<PIA_HOME>\webserv\<DOMAIN>\applications\ peoplesoft\PSIGW.war\SDK

Java classes

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\ PSIGW.war\WEB-INF\classes

Sample code for listening and target connector classes

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\ PSIGW.war\SDK\src

Send Master utility

Microsoft Windows:

<PIA_HOME>\webserv\<DOMAIN>\piabin\StartSendMaster.bat

UNIX:

<PIA_HOME>\webserv\<DOMAIN>\piabin\StartSendMaster.sh

Simple Post utility

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\ PSIGW.war\WEB-INF\classes\com\peoplesoft \pt\simplepost

Click to jump to top of pageClick to jump to parent topicSDK Connector Examples

Four sample connectors are provided as part of the SDK:

These connectors can be used as the basis for new development.

The ExampleListeningConnector and the ExampleServletListeningConnector highlight the differences between a minimalist listening connector and one intended to be run as a servlet.

The ExampleTargetConnector shows the basic requirements of a working target connector.

The SimpleFileTargetConnector is an example of a target connector written to perform a specific task: write outgoing message data to the file system.

To compile these connectors you must set the Java classpath to include the Integration Broker classes in:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEBINF\classes

and

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEBINF\lib\mail.jar

The Java class path must also be set to include the runtime Jar file for the installed web server, for example:

weblogic.jar for a WebLogic installation

Click to jump to parent topicUnderstanding the Code Examples in this Appendix

This appendix features code examples to help illustrate using the PeopleSoft Integration Broker SDK. The code examples are for illustrative purposes only and are not intended to be used in a production environment.

Click to jump to parent topicUnderstanding Connector Development and Implementation

This section discusses connector development and implementation.

Click to jump to top of pageClick to jump to parent topicUnderstanding Developing Connectors

You can produce new connectors in different ways, based on whether you want to create a listening connector or a target connector.

Listening connectors use standard connector interface and gateway services to link to the integration gateway. Although a Java interface object is not used for listening connectors, the listening connectors still must adhere to a standard scheme of logic to drive requests to, and to process responses from, the integration gateway.

Target connectors must implement a Java interface to become valid target connectors in the integration gateway. This ensures a standard interface for the gateway manager so that it can manage each target connector in a streamlined way.

To develop connectors, you:

  1. Develop a connector class.

  2. Install the connector class.

  3. Register the connector.

Click to jump to top of pageClick to jump to parent topicUnderstanding General Connector Class Development Considerations

While implementations vary greatly, when you develop connector classes, you should incorporate specific functionality.

Input and Output Formats That Are Exchanged Through Connectors

For a target connector to handle input and output formats that are exchanged with its intended recipient, it must transform the PeopleSoft Integration Broker request (IBRequest) into a message that is formatted for the intended external system.

For instance, the HTTP target connector that is delivered with PeopleSoft Integration Broker gathers HTTP headers and cookies from the IBRequest and formulates the appropriate HTTP message, complete with the actual message content, so that it can be delivered to its destination. When the response comes back, the connector creates a PeopleSoft Integration Broker response (IBResponse) by using the response string.

For a listening connector to handle input and output formats that are exchanged with its requestor, it must transform the incoming message into an IBRequest. For example, the HTTP listening connector that is delivered with PeopleSoft Integration Broker recognizes SOAP messages and retrieves query string arguments, HTTP headers, and cookies. It then formats all of this information to create the IBRequest so that PeopleSoft Integration Broker can converse with it. When the response comes back, the HTTP listening connector reads the IBResponse and sends its output message content back to the requesting system.

Interaction Between Local and External Systems

A target connector interacts with an external system by sending it information and by retrieving the response.

For example, to accomplish this interaction, the HTTP target connector that is delivered with PeopleSoft Integration Broker uses various HTTP-specific classes to send messages through HTTP and to handle the external system being down, security (through HTTPS), and so forth.

A listening connector interacts with an external system by receiving requests from the external system and returning responses that the external system understands. For example, to accomplish this interaction, the HTTP listening connector that is delivered with PeopleSoft Integration Broker uses a servlet to receive and reply to incoming HTTP messages.

Click to jump to parent topicDeveloping Target Connector Classes

This section discusses target connector class development and discusses how to:

Click to jump to top of pageClick to jump to parent topicUsing the Target Connector Interface

As with PeopleSoft-provided target connectors, the integration gateway dynamically invokes custom target connectors through the gateway manager. Target connectors must adhere to a standard structure as defined in the target connector interface.

public interface TargetConnector { IBResponse send(IBRequest request) throws GeneralFrameworkException, DuplicateMessageException, InvalidMessageException, ExternalSystemContactException, ExternalApplicationException, MessageMarshallingException, MessageUnmarshallingException; IBResponse ping(IBRequest request) throws GeneralFrameworkException, DuplicateMessageException, InvalidMessageException, ExternalSystemContactException, ExternalApplicationException, MessageMarshallingException, MessageUnmarshallingException; ConnectorDataCollection ​introspectConnector();

Use the Send method to send a request to an external system and to retrieve its response. The gateway manager passes the request to this method and expects a response to be returned.

The Ping method enables PeopleSoft Integration Broker to verify the availability of a site. The Integration Broker Monitor can also invoke the Ping method explicitly.

The following diagram shows how the Send method connector code generates and sends message requests to integration participants and returns responses:

Message send scenario

The following diagram shows how the Ping method connector code pings external systems.

Ping scenario

ConnectorDataCollection invokes introspection and the introspectConnector method is used by the application server to discover the connector properties that are used with the given target connector.

Click to jump to top of pageClick to jump to parent topicBuilding Introspection into Target Connectors

PeopleSoft Integration Broker can introspect (query) the capabilities of target connectors that are installed on a local or remote integration gateway by using introspection. Load all target connectors that are delivered with PeopleSoft Integration Broker by clicking the Load button on the Connectors page in the Gateways component.

You can build introspection into custom-built connectors. When you do so, you can load the connector and its properties with the click of a button.

For the introspection process to gather information about a custom target connector, you must implement the IntrospectConnector method.

The following example shows the connector properties that are available for use with the SMTP target connector:

public ConnectorDataCollection introspectConnector() { //Creates the ConnectorDataCollection that will be returned //by this method. This object will contain all the //necessary information about this Connector's properties. ConnectorDataCollection conCollection = new ConnectorDataCollection(); //Create ConnectorData Object and stipulating the name of //the connector as seen from the Gateway Component. ConnectorData conData = new ConnectorData("SMTPTARGET"); conData.addConnectorField("DestEmailAddress", true, "", ""); conData.addConnectorField("SourceEmailAddress", true, "", ""); conData.addConnectorField("CC", false, "", ""); conData.addConnectorField("BCC", false, "", ""); conData.addConnectorField("HEADER", Content-type”, false, "", "text/plain|text/html"); conData.addConnectorField("HEADER","sendUncompressed",true, "Y","Y|N"); //Add the ConnectorData to your ConnectorDataCollection //Object. Typically, you would only //add one ConnectorData into your ConnectorDataCollection. conCollection.addConnectorData(conData); return conCollection; }

Use the addConnectorField method to add connector fields:

addConnectorField([PropertyID] PropertyName,Required,DefaultValue,PossibleValues)

Use the following parameters for this method:

Parameter

Description

Property ID

Identifies different property types, such as HEADER for HTTP or SMTP. PeopleSoft software also uses the HEADER property ID to allow a message to be sent in either compressed or clear format through the sendUncompressed property. If this parameter is not supplied, the property ID is the connector name.

Property Name

Identifies the name of the connector property.

Required 

Determines whether the information is required for the target connector to deliver its message. Values are:

  • Y: True

  • N:False

Default Value

Identifies the default value for the property. Typically, you set the Required parameter to True when you specify a default value so that this information carries to the node configuration in the integration engine.

Possible Values

Identifies a list of the possible values that the property can take, separated by the | character.

The following definition shows how these properties function:

conData.addConnectorField("HEADER","sendUncompressed",true,"Y, "Y|N");

In this case, the property name is sendUncompressed and its property ID is HEADER. The sendUncompressed property is required (the third parameter is set to true), so that whenever you create a node in the node definition component and specify SMTPTARGET as the target connector, this property appears on the page automatically. Further, because the default value is set to Y, this is the default value. Possible values have been identified as Y or N. If you click the list box (search box) for this property on the Connectors tab in the Node Definition component, you can select from those two values.

The following diagram shows how connector code accomplishes introspection.

Introspection scenario

Click to jump to top of pageClick to jump to parent topicBuilding Error Handling and Logging into Target Connectors

The following code example demonstrates how to build error handling and logging into target connectors:

package com.peoplesoft.pt.integrationgateway.targetconnector; import ... public class SampleTargetConnector implements TargetConnector { public IBResponse ping(IBRequest request) public IBResponse send(IBRequest request)throws GeneralFrameworkException, InvalidMessageException, ExternalSystemContactException, ExternalApplicationException, MessageMarshallingException, MessageUnmarshallingException, DuplicateMessageException { PSHttp httpObj = null; try { // Get handle on rootnode XmlNode root = dom.GetDocumentElement(); // Cast the IBRequest back to an InternalIBRequest InternalIBRequest request = (InternalIBRequest)requestOrig; // Populate App Msg XML Dom Object from IBRequest ... // Get the URL from either the IBRequest or from the //prop file (default) String URL = request.getConnectorInfo().getFieldValue("URL"); // Log the request Logger.logMessage("SampleTargetConnector: Application Message Request", dom.GenerateXmlString(), Logger.STANDARD_INFORMATION); // Send the request DOM Document httpObj.setRequestProperty("content-type", "text/plain"); httpObj.send(dom.GenerateXmlString().getBytes()); // Get the response and convert to a String responseString = new String(httpObj.getContent()); // Log the response Logger.logMessage("SampleTargetConnector: Application Message Response", responseString, Logger.STANDARD_INFORMATION); // Construct the IBResponse response = new IBResponse(); ... // Return the successful IBResponse return response; } catch (XmlException xe) { httpObj.disconnect(); throw new GeneralFrameworkException ("SampleTargetConnector:Failed while parsing XML"); } catch (org.w3c.www.protocol.http.HttpException httpe) { throw new ("SampleTargetConnector:HTTP Protocol exception",httpe); } catch (java.io.IOException ioe) { throw new ExternalSystemContactException ("SampleTargetConnector:I/O Exception",ioe); } finally { httpObj.disconnect(); } } // end send() }

Click to jump to parent topicDeveloping Listening Connector Classes

This section discusses listening connector class development and discusses how to:

Click to jump to top of pageClick to jump to parent topicBuilding Servlet-Based and Nonservlet-Based Listening Connectors

If you require a listening connector that services HTTP requests, build a servlet-based listening connector. A servlet-based listening connector runs in the Servlet container on the web server.

See SDK Connector Examples.

This PeopleBook does not discuss how to install servlets on web servers.

See The servlet documentation for your web server.

Click to jump to top of pageClick to jump to parent topicInvoking Listening Connectors

Listening connectors must invoke PeopleSoft Integration Broker through the gateway manager Connect method.

IBResponse ​connect(IBRequest) throws GeneralFrameworkException DuplicateMessageException InvalidMessageException MessageMarshallingException MessageUnmarshallingException ExternalSystemContactException ExternalApplicationException

Click to jump to top of pageClick to jump to parent topicControlling Message Routing

By accessing and modifying key information on the IBRequest, you can control the behavior of transactions as they flow through the integration gateway.

This section describes several dispatching features that you can use to control message routing by modifying the IBRequest from the listening connector, including routing messages to:

You can control the routing of a message to another integration gateway by specifying the uniform resource locator (URL) of the gateway in the IBRequest. You might need to forward messages to another gateway so that they can be processed by a remote PeopleSoft Integration Broker system. To do so, specify the URL of this integration gateway as follows:

. . . IBRequest ibRequest = new IBRequest(); IbRequest.setOperationName("RemoteRoutingTest"); IbRequest.setRequestingNode("SourceSystem"); IbRequest.setPassword("myPassword"); . . . //Specify the processing of the message to occur from //anotherIntegration Gateway. ibRequest.setRemoteFrameworkURL("https://hostName/PSIGW/ PeopleSoftListeningConnector");

You can also route a message to a specific target connector by modifying the request's ConnectorInfo object as follows:

. . . IBRequest ibRequest = new IBRequest(); . . . // Send a message through the HttpTargetConnector for example. ConnectorInfo connectorInfo = ibRequest.getConnectorInfo(); connectorInfo.setConnectorClassName("HttpTargetConnector"); connectorInfo.setField("URL","http://www.externalsite.com"); connectorInfo.setField("Method","POST"); . . .

Click to jump to top of pageClick to jump to parent topicBuilding Error Handling and Logging into Listening Connectors

This is sample code for building error handling and logging into listening connectors:

package com.peoplesoft.pt.integrationgateway.listeningconnector; import ... public class HttpListeningConnector extends HttpServlet { public void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { } public void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { String actualResponse =""; IBRequest request = null; IBResponse response = null; try { String inputString = MiscUtil.readerToString(new InputStreamReader(req.getInputStream())); // Log the actual Input String Logger.logMessage("HttpListeningConnector: HTTP Request", inputString, Logger.STANDARD_INFORMATION); HttpListeningConnectorUtility util = new HttpListeningConnectorUtility(); request = util.createIBRequest("XML", req, inputString); // Use the GatewayManager to invoke the Integration // Server and return its response. GatewayManager conMgr = new GatewayManager(); response = conMgr.connect(request); // Need to get the actual response from the //IBResponse actualResponse = response.getContentSectionAt(0); } catch (InvalidMessageException ime) { ime.printStackTrace(); actualResponse = getErrorXml(ime); Logger.logError("HTTPListeningConnector: InvalidMessageException", request, response, Logger.STANDARD_GATEWAY_EXCEPTION, ime); } catch (ExternalSystemContactException esce) { esce.printStackTrace(); actualResponse = getErrorXml(esce); Logger.logError("HTTPListeningConnector: ExternalSystemContactException", request, response, Logger.STANDARD_GATEWAY_EXCEPTION, esce); } catch (ExternalApplicationException esee) { esee.printStackTrace(); actualResponse = getErrorXml(esee); Logger.logError("HTTPListeningConnector: ExternalApplicationException", request, response, Logger.STANDARD_GATEWAY_EXCEPTION, esee); } catch (MessageMarshallingException mme) { mme.printStackTrace(); actualResponse = getErrorXml(mme); Logger.logError("HTTPListeningConnector: MessageMarshallingException", request, response, Logger.STANDARD_GATEWAY_EXCEPTION, mme); } catch (MessageUnmarshallingException mue) { mue.printStackTrace(); actualResponse = getErrorXml(mue); Logger.logError("HTTPListeningConnector: MessageUnmarshallingException", request, response, Logger.STANDARD_GATEWAY_EXCEPTION, mue); } catch (GeneralFrameworkException gfe) { gfe.printStackTrace(); actualResponse = getErrorXml(gfe); Logger.logError("HTTPListeningConnector: GeneralFrameworkException", request, response, Logger.STANDARD_GATEWAY_EXCEPTION, gfe); } // Return the message to the original requestor that //invoked the Servlet HttpListeningConnectorUtility. sendResponseBackToRequestor(actualResponse, resp); // Log the actual output String Logger.logMessage("HttpListeningConnector: HTTP Response", actualResponse, Logger.STANDARD_INFORMATION); } // end doPost() }

Click to jump to parent topicInstalling Connector Classes

Install connector classes on the local web server.

Click to jump to top of pageClick to jump to parent topicInstalling Target Connector Classes

To install a target connector class, copy the class from the Java Classes directory to the following location on the local web server:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF\classes\com\peoplesoft\pt\integrationgateway\targetconnector

Click to jump to top of pageClick to jump to parent topicInstalling Listening Connector Classes

To install a listening connector class, copy the class to the following location on the local web server:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF\classes\com\peoplesoft\pt\integrationgateway\listeningconnector

Click to jump to parent topicRegistering Connectors

Before you can use a target connector, you must register it on the integration engine. To register a connector, load the connector information in the Gateways component by using the Load button. Loading the connector makes its capabilities known to PeopleSoft Integration Broker.

Then, assign the connector to the intended node on the Connector page in the Node Definition component. Enter the connector ID that corresponds to the new connector and edit the properties, as needed.

Servlet based listening connectors need to be registered with the web server. The mechanism for doing so is web server-specific. For Weblogic, this involves adding entries for the servlet and mapping to the web.xml file found in the following location:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF

See Also

Loading Target Connectors