3
Design Time and Runtime Concepts

This chapter describes the design time and runtime concepts for the HTTP adapter.

This chapter contains these topics:

• HTTP Adapter Design Time Concepts

• HTTP Adapter Runtime Concepts

• Customizing the HTTP Adapter

• Starting the HTTP Adapter

• Stopping the HTTP Adapter

• HTTP Adapter Error Codes

HTTP Adapter Design Time Concepts

The HTTP adapter can handle XML and data definition description language (D3L) structured payload. For example:

• Pure XML data--string beginning with <?xml . . .

• Fixed layout, typically binary data described by a D3L XML file

  See Also: Oracle Application Server InterConnect User's Guide, Appendix B, for additional information on D3L

XML Payload Type

You can import a document type definition (DTD) in iStudio that determines how the HTTP adapter parses a received XML document into an OracleAS InterConnect application view event. In addition, the DTD describes how an inbound application view message is converted into an XML document. Use the message type option XML when defining a new integration point in any of the Event Wizards.

You must also ensure that the parameter ota.type 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 XML payload mode, no translations are performed on the messages (between native view and application view) sent or received through the HTTP adapter. This is apart from the implied straight ASCII to Java object conversion (parsing). Any Extensible Stylesheet Language transformations (XSLT) should be performed before sending or receiving an XML document to or from OracleAS InterConnect.

D3L Payload Type

The HTTP adapter supports both XML and D3L datatypes. The HTTP adapter converts and translates application view messages to native format and vice versa.

An application based on the HTTP adapter can use the iStudio Message Type D3L and the iStudio D3L Data Type Import option when importing a datatype. In doing so, 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 datatypes.

See Also: Oracle Application Server InterConnect User's Guide, Appendix B, for additional information on D3L and common view data types

HTTP Adapter Runtime Concepts

This section describes the key runtime components of the HTTP adapter.

This section contains these topics:

• HTTP Receiver

• HTTP Sender

• HTTP Adapter Message Format

• HTTP Message Headers

• HTTP Receiver Diagnostics

  See Also: Oracle Application Server InterConnect User's Guide, Appendix B, for an example involving an Oracle adapter, the Advanced Queuing adapter, and D3L

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

In a typical deployment, the servlet runs in Oracle Application Server Containers for J2EE (OC4J). The servlet processes the HTTP client requests and relays them to the HTTP receiver through remote method invocation (RMI). Upon receiving the message, the HTTP receiver passes the message to the HTTP bridge.

The HTTP bridge uses the D3L XML file based on name/value pair 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 native format message into an OracleAS InterConnect message object and translate to an application view event. The agent converts the application view event into a common view event and sends it to OracleAS InterConnect for further routing and processing.

Once the message is successfully sent to OracleAS InterConnect, the HTTP adapter returns a 200 message acknowledgment.

The properties for the HTTP receiver are defined in the adapter.ini file and take the form of http.receiver.*.

See Also: Oracle Application Server InterConnect User's Guide, Appendix B, for additional information on D3L name/value pair and magic value message header attributes Figure 1-1, "Incoming Messages" "HTTP Adapter-Specific Parameters"

HTTP Sender

The HTTP adapter supports sending outgoing messages from OracleAS InterConnect to multiple HTTP endpoints. The multiple endpoints feature provides flexibility for sending messages to different 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 through the Modify Fields button of the Subscribe Wizard - Define Application View dialog. Once the association of endpoint and event is established, the message from the subscribing event is sent out to the HTTP endpoint.

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

Table 3-1 SendOrder Event Metadata

Parameter	Description
ota.endpoint=sendOrderAppEP	Specifies a unique endpoint name set in iStudio
ota.send.endpoint=http://foo.com/servlet/test	Specifies the HTTP adapter's sending endpoint

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

The HTTP adapter consists of the HTTP bridge and runtime agent. When the agent has a message to send to an endpoint, the bridge is notified. The bridge then uses D3L XML to perform the translation of common view object to native format message. The native format message is then sent through the HTTP transport layer to an HTTP endpoint. The properties for the HTTP sender are defined in the adapter.ini file and take the form of http.sender.*.

Note: When using the multiple-endpoint feature with XML data type, you must choose the event type of Generic, instead of XML. Using the Generic event type allows you to enter the metadata for the endpoints via the Modify Fields feature associated with iStudio.

Note: The sender properties are not inherited from the adapter.ini file.

See Also: Figure 1-2, "Outgoing Messages" "HTTP Adapter-Specific Parameters" Chapter 4 of the Oracle Application Server InterConnect User's Guide for information on adding transport properties as metadata in iStudio

HTTP Adapter Message Format

This section describes how to extract or send messages to the HTTP adapter 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.

D3L Payload Type

You must ensure that the ota.type parameter in the adapter.ini file is set to D3L to use this payload type. The HTTP adapter expects to receive a message from an HTTP client using the POST method. The data received with the POST method is interpreted as the payload. The HTTP adapter sends the payload with the POST method to either of the following:

• The endpoint associated with the event (if one is given)

• The default endpoint specified by the ota.send.endpoint parameter in the adapter.ini file

XML Payload Type

You must ensure that the ota.type parameter in the adapter.ini file is set to XML to use this payload type. The sending and receiving operation for the XML payload type is similar to D3L. With XML, the D3L transformation is not performed.

XML_NVP (XML Name-Value Pair)

You must ensure that the ota.type parameter in the adapter.ini file is set to XML_NVP to use this payload type. The HTTP adapter expects the payload to be packaged in the following manner:

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

The value of the message name-value pair contains the payload. During the receiving operation, the HTTP adapter extracts the message name-value pair from the POST data and converts it to an OracleAS InterConnect object. During the sending operation, the adapter packages the name-value pair and sends it through the POST method.

See Also: The ota.type parameter description for information on setting the payload message type in the adapter.ini file

HTTP Message Headers

Example 3-1 shows the HTTP message header types and data sent by the HTTP adapter:

Example 3-1 HTTP Header Types and Data

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

The OAI-* headers are associated with a specific HTTP adapter. This information is useful in debugging and tracking. Table 3-2 lists and describes key OAI-* headers.

Table 3-2 OAI-* Headers

Header	Description
OAI-MV	Message version to which this message corresponds, as created in iStudio
OAI-T	Possible values are: 0 (publish) 1 (request) 2 (reply) Only publish is supported in this release.
OAI-BO	Business object name to which this message corresponds
OAI-EV	Event version to which this message corresponds, as created in iStudio
OAI-EN	OracleAS InterConnect event name
OAI-APPLICATION	HTTP adapter application name

HTTP Receiver Diagnostics

This section describes how to determine if the HTTP receiver is functioning properly.

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, the Web browser displays information similar to the following:

   

   Text description of the illustration ipsever.gif

   This page is useful for identifying information that the servlet reads from the web.xml file. The rmiHost, rmiPort and instance name have to match the corresponding parameters in the adapter.ini file.

Customizing the HTTP Adapter

You can customize some of the adapter behaviors by implementing the following two interfaces:

• oracle.oai.adapter.agent.technology.ReceiverCustomizer

• oracle.oai.adapter.agent.technology.HTTPSenderCustomizer

You can use the ReceiverCustomizer interface to customize the message that the HTTP adapter receives. The ReceiverCustomizer interface replaces the following customizing interface, which is from the previous release and is currently deprecated, oracle.oai.agent.adapter.transport.basic.HTTPCustomizedResponse.

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

ReceiverCustomizer Interface

File Structure

The following is the file structure of this 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);
}

File Summary

The following table summarizes the ReceiveCustomizer interface

Method	Description
customizeTransportMessage();	This method allows the user to customize the transport message received by the adapter, Message. It contains the following parameters: agent--Used to log a message. receiverType--Provides information on the type of adapter. transportMessage--Used to customize the transport message received by the adapter.
createReplyMessage();	This method creates a reply message, Message, based on the status and the message received. It contains the following parameters: agent--Used to log a message. status--The status of the message process. If the value is TransportResponse.TRANSPORT_ACK, the message is processed successfully. If the value is TransportResponse.TRANSPORT_ERROR, the message is processed unsuccessfully. receivedTransportMessage--The transport message is received by the adapter. This parameter is used to transport headers in the transport message to create a meaningful HTTP message. The return string contains the reply message. This method is included for backward compatibility.

Example 3-2 Example of ReceiverCustomizer

This MyReceiverCustomizer class removes 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 InterConnect does not understand.

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

Note: 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(int status) {
      String response = Message has unknown status.";
      switch (status) {

Note: OracleAS InterConnect indicates to the transport layer that the message has been processed successfully.

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

Note: OracleAS 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.";
}

Example 3-3 List of Methods for the TransportMessage Class

This example provides a list of methods users may choose for the TransportMessage class.

Method	Description
public String toString();	Dump message and headers.
public void setTransportHeader(String name, String value);	Set a transport specific header.
public Properties getTransportHeaders();	Get all transport specific header and return a Properties object that contains all the transport headers.
public void setBody(String body) throws TransportException;	Set the body of the message. The body type will be set to STRING. Parameter includes: body--body of the message It throws a TransportException.
public void setBody(InputStream in) throws TransportException;	Set the body of the message. The body type will be set to BYTES. Parameter includes: InputStream--Contains the message. It throws a TransportException.
public String getBodyAsString();	Get the body of the message as String object. Return the message in String object.
public byte[] getBodyAsBytes();	Get the body of the message as byte array. Return the message in byte[].
public InputStream getBodyAsInputStream();	Get the body of the message and return an InputStream object representing the body of the message.

HTTPSenderCustomizer Interface

You can use the THHPSenderCustomizer 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.

SenderCustomizer Interface

File Structure

The following is the file structure of 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);

}

File Summary

The following table summarizes the customizerTransportMessage method.

Method

Description

customizerTransportMessage();

This method specifies how to customize the transport message for transport sender. The adapter creates a TransportMessage for the transport layer to send based on the MessageObject sent by OracleAS InterConnect. You can use this method to further customize the transport message to be sent out by the transport layer. This method contains the following parameters: agent--Used to log messages. transportMessage--Indicates the TransportMessage object that the adapter has created for sending. mobj--Indicates the MessageObject from OracleAS InterConnect. aobj--Indicates the AttributeObject from OracleAS InterConnect. This method does not return anything. You can change the payload with the transportMessage parameter.

HTTPSenderCustomizer Interface

The following is the structure of the HTTPSenderCustomizer interface.

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{

}

Starting the HTTP Adapter

On UNIX, start the HTTP adapter using the start script located in the following directory:

ORACLE_HOME/oai/9.0.4/adapters/Application

Type start, then press Enter.

On Windows, start the HTTP adapter from the Services window available from the Start menu.

1. Access the Services window from the Start menu:

   On...	Choose...
   Windows NT	Start > Settings > Control Panel > Services
   Windows 2000	Start > Settings > Control Panel > Administrative Tools > Services

   The Services window appears.

2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

3. Start the service based on the operating system:

   On...	Choose...
   Windows NT	Choose Start.
   Windows 2000	Right-click the service and choose Start from the menu that appears.

   See Also: "HTTP Adapter Configuration Parameters" for the location of the start script

Log File Example of Successfully Started HTTP Adapter

You can verify the startup status by viewing the oailog.txt files. These files are located in the appropriate timestamped subdirectory of the log directory of the HTTP adapter directory. Subdirectory names take the following form:

timestamp_in_milliseconds

The following file displays information about an HTTP adapter that started successfully:

D:\oracle\ora904\oai\9.0.4\adapters\httpapp>D:\oracle\ora904\oai\9.0.4\bin\JavaS
ervice.exe -debug "Oracle OAI Adapter 9.0.4
-httpapp" D:\oracle\ora9041\oai\9.0.4\adapters\httpapp adapter.ini 
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. 

Stopping the HTTP Adapter

On UNIX, stop the HTTP adapter using the stop script located in the following directory named after the Oracle HTTP application.

ORACLE_HOME/oai/9.0.4/adapters/Application

Type stop, then press Enter.

On Windows, stop the HTTP adapter from the Services window available from the Start menu.

1. Access the Services window from the Start menu:

   On...	Choose...
   Windows NT	Start > Settings > Control Panel > Services
   Windows 2000	Start > Settings > Control Panel > Administrative Tools > Services

   The Services window appears.

2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

3. Stop the service based on the operating system:

   On...	Choose...
   Windows NT	Choose Stop.
   Windows 2000	Right-click the service and choose Stop from the menu that appears.

   You can verify the stop status by viewing the oailog.txt files. These files are located in the appropriate timestamped subdirectory of the log directory of the HTTP adapter directory.

   See Also: "HTTP Adapter Configuration Parameters" for the location of the stop script

HTTP Adapter Error Codes

The HTTP adapter returns the standard HTTP status codes as outlined in Request For Comments (RFC) 2068. See Section 6.1.1 "Status Code and Reason Phrase" of this document.

See Also: The following URL for access to RFC 2068: http://www.w3.org/Protocols/