|
Oracle® Application Server Integration InterConnect Adapter for HTTP Installation and User's Guide
10g Release 2 (10.1.2) B14074-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Integration InterConnect Adapter for HTTP Installation and User's Guide
10g Release 2 (10.1.2) B14074-02 |
|
|
Previous |
Next |
This chapter describes the design-time and run-time concepts for the HTTP adapter. It contains the following topics:
The HTTP adapter can handle XML and D3L structured payloads, such as pure XML data with strings beginning with <xml..., and binary data described by a D3L XML file.
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.
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.
This section describes the key run-time components of the HTTP adapter. This section contains the following topics:
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.
|
Note: The adapter subscribing to an event should be started before any other adapter can publish that event. If you publish an event before starting the subscribing adapter, then the event would not be delivered to the subscribing adapter. |
|
See Also:
|
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.
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 sending endpoint for the HTTP adapter |
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.
|
Note: Thesender properties are not inherited from the adapter.ini file.
|
|
See Also:
|
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:
The ota.type parameter in the adapter.ini file must be set to D3L to use this payload type. The HTTP adapter receives 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 using the POST method to one of the following endpoints:
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
The ota.type parameter in the adapter.ini file must be set to XML to use this payload type. The sending and receiving operation for the XML payload type is similar to that of D3L.
The ota.type parameter in the adapter.ini file must be 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 Integration InterConnect object. During the send operation, the adapter packages the name/value pair and sends it through the POST method.
|
See Also: Theota.type parameter description in Table 2-9 for information on setting the payload message type in the adapter.ini file
|
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:
Example 3-1 HTTP Message 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 describes the key OAI-* headers.
Table 3-2 OAI-* Headers
| Header | Description |
|---|---|
|
|
HTTP adapter application name |
|
|
Business object name to which this message corresponds |
|
|
Oracle Application Server Integration InterConnect event name |
|
|
Event version to which this message corresponds, as created in iStudio |
|
|
Message version to which this message corresponds, as created in iStudio |
|
|
Tag that represents the mode of the adapter that publishes, requests or responds to a message Possible values are:
|
To determine whether the HTTP receiver is functioning properly, perform the following steps:
Open a Web browser.
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.
You can customize the adapter behavior by implementing the following interfaces:
oracle.oai.adapter.agent.technology.ReceiverCustomizer
oracle.oai.adapter.agent.technology.HTTPSenderCustomizer
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.
| Method | Description |
|---|---|
customizeTransportMessage();
|
Enables you to customize the transport message received by the adapter. It uses the following parameters:
agent: Log a message receiverType: Information on the type of adapter transportMessage: Customize the transport message received by the adapter |
createReplyMessage();
|
Creates a reply message based on the status of message received. It contains the following parameters:
The return string contains the reply message. This method is included for backward compatibility. |
customizes the MyReceiverCustomizer class to remove the first line in the native message.
Example 3-2 Example of ReceiverCustomizer
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.
| Method | Description |
|---|---|
public byte[] getBodyAsBytes();
|
Get the body of the message as a byte array. Return the message in the byte array. |
public InputStream getBodyAsInputStream();
|
Get the body of the message and return an InputStream object representing the body of the message.
|
public Properties getTransportHeaders();
|
Get all transport specific header and return a Properties object that contains all the transport headers. |
public String getBodyAsString();
|
Get the body of the message as a String object. Return the message in the String object. |
public String toString();
|
Dump message and headers. |
public void setBody(InputStream in) throws TransportException;
|
Set the body of the message. The body type will be set to BYTES. The parameter is:
It throws an exception of type |
public void setBody(String body) throws TransportException;
|
Set the body of the message. The body type will be set to STRING. The parameter is:
It throws an exception of type |
public void setTransportHeader(String name, String value);
|
Set a transport specific header. |
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.
The following code describes 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);
}
The customizerTransportMessage Method
This method specifies how to customize the transport message for the transport sender. The adapter creates a TransportMessage object for the transport layer to send, based on the MessageObject object sent by OracleAS Integration InterConnect. You can use this method to further customize the transport message to be sent by the transport layer.
This method contains the following parameters:
agent: Log messages.
transportMessage: The TransportMessage object that the adapter has created for sending.
mobj: The MessageObject object parsed from OracleAS Integration InterConnect.
aobj: The AttributeObject object parsed from OracleAS Integration InterConnect.
This method does not return anything. You can change the payload with the TransportMessage parameter.
The following code describes the file 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{
}
The process for starting the adapter varies based on the operating system.
To start the HTTP adapter on UNIX:
Change to the directory containing the start script.
cd ORACLE_HOME/integration/interconnect/adapters/Application
Type start and press Enter.
To start the HTTP adapter from Services on Windows:
Access the Services window from the Start menu. The Services window is displayed.
Select the OracleHomeOracleASIntegrationInterConnectAdapter-Application service.
Start the service based on the operating system.
|
Note: You can also start and stop the HTTP adapter using the IC Manager. Refer to Oracle Application Server Integration InterConnect User's Guide for more details. |
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.
Based on the operating system, the process for stopping the adapter varies.
To stop the HTTP adapter on UNIX:
Change to the directory containing the stop script.
cd ORACLE_HOME/integration/interconnect/adapters/Application
Type stop and press Enter.
To stop the HTTP adapter from Services on Windows:
Access the Services window from the Start menu. The Services window is displayed.
Select the OracleHomeOracleASInterConnectAdapter-Application service.
Stop the service.
You can verify the stop status of the HTTP adapter by viewing the log.xml files. These files are located in the time-stamped subdirectory of the log directory of the HTTP adapter.
