3
Design Time and Runtime Concepts

This chapter describes the design time and runtime concepts for the Hypertext Transfer Protocol (HTTP) adapter.

This chapter contains these topics:

• HTTP Adapter Design Time Concepts

• HTTP Adapter Runtime Concepts

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: Oracle9iAS InterConnect User's Guide 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 Oracle9iAS 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) are performed before sending or receiving an XML document to or from Oracle9iAS 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: Oracle9iAS InterConnect User's Guide for additional information on D3L and common view datatypes

HTTP Adapter Runtime Concepts

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

This section contains these topics:

• HTTP Receiver (Incoming Messages from HTTP Client to Oracle9iAS InterConnect)

• HTTP Sender (Outgoing Messages from Oracle9iAS InterConnect to HTTP Web Server)

• HTTP Adapter Message Format

• HTTP Message Headers

• HTTP Receiver Diagnostics

• Customizable Messages

• Starting the HTTP Adapter

• Stopping the HTTP Adapter

• HTTP Error Codes

  See Also: Oracle9iAS InterConnect User's Guide for an example use case involving an Oracle adapter, the Advanced Queuing adapter, and D3L

HTTP Receiver (Incoming Messages from HTTP Client to Oracle9iAS InterConnect)

The HTTP adapter receives incoming messages from a single receiving endpoint, which is a servlet serving the POST requests from HTTP clients.

In a typical deployment, the servlet runs in Oracle9iAS 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 Oracle9iAS 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 Oracle9iAS InterConnect for further routing and processing.

Once the message is successfully sent to Oracle9iAS 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: Oracle9iAS InterConnect User's Guide for additional information on D3L name/value pair and magic value message header attributes "Customizable Messages" Figure 1-1, "Incoming Messages" "HTTP Adapter-Specific Parameters"

HTTP Sender (Outgoing Messages from Oracle9iAS InterConnect to HTTP Web Server)

The HTTP adapter supports sending outgoing messages 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 set in the adapter.ini file

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

See Also: Figure 1-2, "Outgoing Messages" "HTTP Adapter-Specific Parameters" Chapter 4 of the Oracle9iAS 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 Oracle9iAS 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	Oracle9iAS 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.

Customizable Messages

The HTTP adapter enables you to customize the message to send to the HTTP client. For a status 200 message reply, for example, you can provide a more useful message informing the user that the message has been accepted by a company.

To customize the HTTP response message:

1. Implement the following interface:

   oracle.oai.agent.adapter.transport.basic.HTTPCustomizedResponse.
   

   HTTPCustomizedResponse. has one method called createReplyMessage() to customize reply messages to an HTTP client.

   public interface HTTPCustomizedResponse {
     public String createReplyMessage(int status);
   }
   

2. Add the following parameter to the adapter.ini file:

   http.receiver.customized_class=class_name 
   

3. Compile and create a jar file containing the class.

4. Add the jar file in the CLASSPATH of the HTTP adapter.

   The following example shows how to customize the 200 and 500 HTTP responses to better inform the user of their requests:

   import oracle.oai.adapter.agent.transport.TransportResponse; 
   public class MyBanner implements HTTPCustomizedResponse { 
      public String createReplyMessage(int status) { 
         switch(status) { 
             // OAI indicates to the transport layer that the message 
             // has been processed successfully. 
             case TransportResponse.TRANSPORT_ACK: 
                   return "Request has been processed succuessfully."; 
             break; 
             // OAI 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."; 
             break; 
         } 
         return "Message has unknown status."; 
     } 
   } 
   

Starting the HTTP Adapter

Start the adapter using the start script located in the directory named after the Oracle HTTP application. On Windows NT or Windows 2000, you can also start it 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 OracleHome9iASInterConnectAdapter-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

Verify startup status by viewing the oailog.txt files. These files are located in the appropriate timestamped subdirectory of the logs 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\ora902\oai\9.0.2\adapters\httpapp>D:\oracle\ora902\oai\9.0.2\bin\JavaS
ervice.exe -debug "Oracle OAI Adapter 9.0.2
-httpapp" D:\oracle\ora9021\oai\9.0.2\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

Stop the HTTP adapter using the stop script located in the directory named after the Oracle HTTP application. On Windows NT or Windows 2000, you can also stop it 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 OracleHome9iASInterConnectAdapter-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.

   Verify stop status by viewing the oailog.txt files. These files are located in the appropriate timestamped subdirectory of the logs directory of the HTTP adapter directory.

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

HTTP 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/