3 Design-Time and Run-Time Concepts

XML Payload Type

You can import a Document Type Definition (DTD) or XML Schema Definition (XSD) in iStudio to determine how the HTTP adapter parses a received XML document into an OracleAS Integration InterConnect application view event. In addition, you can use the DTD or XSD to describe how an inbound application view message is converted to an XML document. Use the message type option XML when defining a new integration point in any of the event wizards.

Ensure that the ota.type parameter in the adapter.ini file is set to XML or XML_NVP, instead of D3L. Both the XML and XML_NVP settings operate with XML messages.

XML and XML_NVP differ in that XML_NVP supports legacy applications where the body of the HTTP message is prepended with the string, message=.

When the HTTP adapter operates in the XML payload mode, no transformations are performed on the messages between native view and application view. Any Extensible Stylesheet Language Transformations (XSLT) should be performed either before sending or receiving an XML document to or from OracleAS Integration InterConnect.

D3L Payload Type

The HTTP adapter supports both XML and D3L data types. The HTTP adapter performs a two-way conversion and transformation of messages between application view and native format.

An application based on the HTTP adapter can use the iStudio Message Type D3L and the iStudio D3L Data Type Import options when importing a data type. In this case, messages received or sent by the HTTP adapter must adhere to the fixed byte-level layout defined in a D3L XML file.

The D3L Data Type Import option can also define common view data types.

HTTP Receiver

The HTTP adapter receives incoming messages from a single receiving endpoint, which is a servlet provided by the HTTP adapter, serving the POST requests from HTTP clients to OracleAS Integration InterConnect.

In a typical deployment scenario, the servlet runs in Oracle Application Server Containers for J2EE (OC4J). The servlet processes the HTTP client requests and sends them to the HTTP receiver through RMI. When the message is received, the HTTP receiver passes the message to the HTTP bridge.

The HTTP bridge uses the D3L XML file based on name/value pairs or magic value message header attributes (a sequence of bytes in the native format message header). The HTTP bridge uses this information to parse from the native message to an OracleAS Integration InterConnect message object and translate it to an application view event. The agent converts the application view event to a common view event and sends it to OracleAS Integration InterConnect for further routing and processing.

In the publish/subscribe mode, after the message is successfully sent to OracleAS Integration InterConnect, the HTTP adapter returns an acknowledgment message of type 200.

In the synchronous request/reply mode, if the incoming message is a request, then the adapter will send back a reply instead of sending an acknowledgment message, whereas in the asynchronous request/reply mode, the adapter will send the acknowledgment message and the reply will go to the send endpoint defined by the ota.send.endpoint parameter.

The properties for the HTTP receiver are defined in the adapter.ini file in http.receiver.* format.

HTTP Sender

The HTTP adapter comprises of a HTTP bridge and a run-time agent. When the agent has a message to send to an endpoint, the bridge is notified. The bridge then uses D3L XML to translate the common view object to the native format message. The native format message is then sent through the HTTP transport layer to an HTTP endpoint. In the request/reply mode, if the outgoing message from the hub is a request, then the bridge will wait for a reply from the remote HTTP server. After the reply is received, it will be passed on to the hub. If there is no reply within 60 seconds, which is the default time, then the request will be timed out. The default time can be modified using the http.sender.timeout parameter. The properties for the HTTP sender are defined in the adapter.ini file in http.sender.* format.

The HTTP adapter supports sending outgoing messages from OracleAS Integration InterConnect to multiple HTTP endpoints. The multiple endpoints feature enables sending messages to various remote Web servers.

An endpoint is associated with a subscribing event in iStudio by adding the transport properties such as the HTTP endpoint as metadata for the event. This is done using the Modify Fields function of the Subscribe Wizard - Define Application View dialog box. After associating an endpoint and an event, the message from the subscribing event is sent to the HTTP endpoint.

When using the multiple endpoint feature with XML data type, use the Generic event type instead of XML. Using the Generic event type enables you to enter the metadata for the endpoints using the Modify Fields feature associated with iStudio.

Table 3-1 shows how metadata is associated with an event called sendOrder that sends an order to an HTTP server at foo.com with a path, /servlet/test.

If no metadata is associated with an event, then the endpoint specified by the ota.send.endpoint parameter in the adapter.ini file is used as the default endpoint.

HTTP Adapter Message Format

This section describes how to extract or send messages from and to the HTTP adapter by using different payload types. The HTTP adapter expects all payload types to be sent using the POST method, which does not have the GET method's data length limitations. This section includes the following topics:

• D3L Payload Type

• XML Payload Type

• XML_NVP (XML Name-Value Pair) Payload Type

application= ..&...&message=<?xml ...>

HTTP Message Headers

The HTTP adapter uses custom message headers, in addition to the default message headers. Example 3-1 shows the HTTP message header types and the data sent by the HTTP adapter:

OAI-MV = QA/V1 (Message Version)
CONNECTION = Keep-Alive, TE
CONTENT-TYPE = application/octet-stream
USER-AGENT = RPT-HTTPClient/0.3-2S
OAI-T = 0  
OAI-BO = Persona 
OAI-EV = QA/V1  
TE = trailers, deflate, gzip, compress
ACCEPT-ENCODING = deflate, gzip, x-gzip, compress, x-compress
OAI-EN = newPerson1a (Event name)
CONTENT-LENGTH = 76
HOST = cc-sun.us.oracle.com:8888
OAI-APPLICATION = HTTP1A

HTTP Receiver Diagnostics

To determine whether the HTTP receiver is functioning properly, perform the following steps:

1. Open a Web browser.

2. Enter the URL specified for the ota.receive.endpoint parameter in the adapter.ini file.

   If the servlet is deployed properly, then the Web browser displays information similar to the following:

This page helps identify information that the servlet reads from the web.xml file. The rmiHost, rmiPort, and instance name must match the corresponding parameters in the adapter.ini file.

The ReceiverCustomizer Interface

You can use the ReceiverCustomizer interface to customize the TransportMessage object that the HTTP adapter receives. The TransportMessage object represents the native message that the transport layer receives or sends.

• To customize the TransportMessage object itself, use the customizeTransportMessage() method. This method is called before the before the adapter processes the TransportMessage object.

• To modify the message itself, implement the customizeTransportMessage() method. You must also implement the createReplyMessage() method and ensure that it returns a null value.

The following code describes the file structure of the ReceiverCustomizer interface.

package oracle.oai.agent.adapter.technology;
import oracle.oai.agent.adapter.transport.TransportMessage;
import oracle.oai.agent.adapter.sdk.Agent;
public interface ReceiverCustomizer {
public void customizeTransportMessage(Agent agent, int receiverType,
TransportMessage transportMessage);
public String createReplyMessage(Agent agent,int status, TransportMessage receivedTransportMessage, String response)
}

The following table summarizes the ReceiverCustomizer interface.

customizes the MyReceiverCustomizer class to remove the first line in the native message.

import oracle.oai.agent.adapter.sdk.Agent;
import oracle.oai.agent.adapter.transport.TransportMessage;
import oracle.oai.agent.adapter.transport.TransportException;
import oracle.oai.agent.adapter.technology.ReceiverCustomizer;

public class MyReceiverCustomizer implements ReceiverCustomizer {

// This example describes how to remove an extra line from a file that
// OracleAS Integration InterConnect does not understand.

public void customizeTransportMessage(Agent agent, int receiverType,
                                      TransportMessage transportMessage) {
   String payload = transportMessage.getBodyAsString();

//For debugging purposes only, the following syntax removes the first line from the payload. Details of removeFirstLine() is not provided.

      agent.logTraceMessage("payload received = " + payload, null, null, null);
      String newPayload = removeFirstLine(payload);
         try {
            transportMessage.setBody(newPayload); 
         }
         catch(TransportException te) {
         . . . . 
      }
   }

   public String createReplyMessage(Agent agent, int status, TransportMessage receivedTransportMessage, String response) {
      String response = Message has unknown status.";
      switch (status) {

//OracleAS Integration InterConnect indicates to the transport layer that the 
// message has been processed successfully.

      case TransportResponse.TRANSPORT_ACK:
         return "Request has been processed successfully.";

//OracleAS Integration InterConnect indicates to the transport layer that the 
// message cannot be processed successfully.

      case TransportResponse.TRANSPORT_ERROR:
         return "Please try again. The server cannot process your request.";
   }
   return "Message has unknown status.";
}

List of Methods for the TransportMessage Class

The following table provides a list of methods you can select for the TransportMessage class.

The HTTPSenderCustomizer Interface

You can use the HTTPSenderCustomizer interface to customize the subject name and payload of the TransportMessage object that is sent to the transport layer. The HTTPSenderCustomizer interface extends the SenderCustomizer interface.

package oracle.oai.agent.adapter.technology;
import oracle.oai.agent.adapter.sdk.MessageObject;
import oracle.oai.agent.adapter.sdk.AttributeObject;
import java.util.Properties;
import oracle.oai.agent.adapter.sdk.Agent;
import oracle.oai.agent.adapter.transport.TransportMessage;

public interface SenderCustomizer {

public void customizeTransportMessage(Agent agent, 
                                      TransportMessage transportMessage,
                                      MessageObject mobj,
                                      AttributeObject aobj);

}

package oracle.oai.agent.adapter.technology;
import oracle.oai.agent.adapter.sdk.MessageObject;
import oracle.oai.agent.adapter.sdk.AttributeObject;

   public interface HTTPSenderCustomizer extends SenderCustomizer{

}

Log File of HTTP Adapter

You can verify the startup status of the HTTP adapter by viewing the log.xml files. The files are located in the time-stamped subdirectory of the log directory of the HTTP adapter. Subdirectory names have the following form:

timestamp_in_milliseconds

The following is an example of the information about an HTTP adapter that started successfully:

The Adapter service is starting.. 
Registering your application (HTTPAPP).. 
Initializing the Bridge oracle.oai.agent.adapter.technology.TechBridge.. 
Starting the Bridge oracle.oai.agent.adapter.technology.TechBridge.. 
Service started successfully.