3
Design Time and Runtime Concepts

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

• FTP Adapter Design Time Concepts

• FTP Adapter Runtime Concepts

• Customizing the FTP Adapter

• FTP Error Code

FTP Adapter Design Time Concepts

The FTP adapter can handle XML and D3L structured payloads. 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

Users can import a DTD in iStudio which governs how the FTP adapter will parse a received XML document into a OracleAS InterConnect application view event. In addition, the DTD describes how an inbound application view message will be converted into an XML document. Use the XML message type when defining a new integration point in any of the event wizards.

Note: The oracle.oai.agent.adapter.technology.type parameter in the adapter.ini file should be set to XML instead of D3L.

When the adapter operates in the XML payload mode, no transformations are performed on the messages between, native view and application view, that are sent or received through the FTP adapter. This is apart from the implied straight ASCII <-> Java object conversion or parsing. XSLT transformations should be performed either before sending an XML document to OracleAS InterConnect, or after receiving one from OracleAS InterConnect.

D3L Payload

The FTP adapter supports both XML and D3L data types. It converts and transforms application view messages to native format and back again.

When an application based on the FTP adapter is created in iStudio, the D3L message type and data type can be used. When these options are selected, messages received or sent by the FTP adapter must adhere to the fixed byte level layout defined in an D3L XML file.

When creating a common view in iStudio, the D3L import option can also be used.

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

FTP Adapter Runtime Concepts

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

How the FTP Adapter Works

This section describes the following components of the FTP adapter:

• FTP Receiver--From remote FTP server or local file system to OracleAS InterConnect functionality.

• FTP Sender--From OracleAS InterConnect to remote FTP server functionality.

FTP Receiver

On the receiving side, the FTP adapter can receive messages from a single receiving endpoint which is either a remote FTP server or a local file system. The receiving endpoint is in the following form:

• For an FTP protocol: ftp://<host name>/<directory path>

• For a local file system: file://localhost/<directory path>

Based on header name and value information, the FTP bridge uses D3L/XML to parse from native-format into an OracleAS InterConnect message object and generates an application view event. The agent converts the application view event into a common view event and hands it off to OracleAS InterConnect for further routing and processing. Once the message is successfully handled off to OracleAS InterConnect, the corresponding FTP file on the remote FTP server or local file system will be removed. If an error occurs, an exception directory on the remote FTP server or local file system can be specified for storing the unsuccessfully processed files. If no exception directory is specified, the file will be discarded.

Note: The value of the exception directory should be a URL which represents either an FTP directory or a file location. For this release, an FTP URL can only be specified for the exception directory if the receiving endpoint is also an FTP URL, and furthermore the host name in the URL has to be the same. When a processing exception occurs, the host name, user name, and password of the receiving endpoint will be used to log on to the FTP server to store the messages that are not processed successfully. The user should make sure this directory exists on the FTP server (or the local file system if file URL is used) and is writable by the FTP adapter process.

If the file.receiver.exception_dir is set, the unsuccessfully processed files will be moved to an exception directory. The archive of exception files of the FTP adapter is appended with a time stamp <original filename>_<timestamp>. This is to avoid the two incoming files having the same file name.

The properties for the FTP receiver are found in the adapter.ini file as file.receiver.*.

FTP Sender

The FTP adapter supports sending to multiple FTP endpoints. This feature provides flexibility for sending messages to different remote FTP servers. An endpoint can be associated with a subscribing event in the iStudio by adding transport properties such as FTP endpoint, FTP user name, and password for this endpoint as metadata or modified fields for the event. Once the association of the endpoint and event is established, the message from the subscribing event is sent out to the FTP endpoint.

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 entering the metadata for the endpoints via the Modify Fields feature associated with iStudio.

For example, the following metadata are associated to an event called SendOrder which sends an order to a FTP server at foo.com in the /private/user/test/directory.

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

Parameter	Description
ota.endpoint=sendOrderAppEP	Specifies a unique endpoint name.
ota.send.endpoint=ftp://foo.com/private/user/test	Defines the FTP endpoint.
file.sender.user=joe	Defines the FTP user credentials.
file.sender.password=welcome	Defines the FTP user credentials.

See Also: Oracle Application Server InterConnect User's Guide

The FTP adapter is comprised of the FTP bridge and the runtime agent. When the agent has a message to send to an endpoint, the bridge is notified. The bridge then uses D3L or XML to perform the conversion of the common view object to the native format. The native format message is then sent through the FTP transport layer to a FTP endpoint. The FTP endpoint is written as follows:

ftp://<host name>/<directory path>

The multi-endpoint feature provides the flexibility to send messages to different FTP servers. The file name at the destination site is automatically generated by the adapter and is in the following form:

<ftp adapter name><partition>-<time stamp>

The user can specify a rule for generating the file name when the FTP adapter sends a file to a directory or FTP server. To use this feature, the user has to add the parameter, file.sender.file_name_rule, in the adapter.ini file. The adapter recognizes the following tokens:

%APP%--application name

%PART%--partition number

%BO%--business object name

%TYPE%--message type

%EVENT%--corresponding event name

%TIME%--time stamp

%MV%--message version

For example, file.sender.file_name_rule=%APP%_%EVENT%_%TIME%.xml. This rule instructs the adapter to generate files with the following pattern:

<your app name>_<event name>_<current time stamp>.xml

If the above rule does not serve the user's needs, the user can write his own customization rule by implementing the following interface:

oracle.oai.adapter.agent.technology.FileSenderCustomizer interface

To avoid external applications picking up partial files, files that are not completely transferred, the user can specify a staging directory. The parameter file.sender.staging_dir in the adapter.ini file can be set. This parameter should only contain the directory name, for example, file.sender.staging_dir=/private/ipdev/test/staging.

Note: Do not use file or FTP URL such as (ftp://... or file://...). If the staging directory is used for a FTP server, the path specified is a directory on the FTP server. User must make sure that the path for the staging directory exists.

The properties for the FTP Receiver are in the adapter.ini file as file.sender.*.

Customizing the FTP 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.FileSenderCustomizer

ReceiverCustomizer Interface

You can use the ReceiverCustomizer interface to customize the TransportMessage object that FTP adapter receives, as illustrated below:

• With the customizeTransportMessage() method, you can customize the TransportMessage object before the adapter processes it. The TransportMessage object represents the native message that the transport layer receives or sends. For example, there is a header in the first line of the file that you must use to dynamically modify the contents of the file that you receive.

• You can modify the message by implementing the customizeTransportMessage() method. The createReplyMessage() method is required by the HTTP adapter. For the FTP adapter, you should return a null value in this method.

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 ReceiverCustomizer Interface.

Methods	Description
customizeTransportMessage();	This method allows you to customize the transport message, Message, received by the adapter. 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 used for backward compatibility for the HTTP adapter. However, for the FTP adapter, you should return a null value in this method.

Example 3-1 Example of ReceiverCustomizer

The 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 in the incoming files.

   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) {
      . . . . 
      }
   }

Note: For the FTP adapter, a null string from the following method will be returned.

   public String createReplyMessage(Agent agent, int status,
                                    TransportMessage receivedTransportMessage)
   {  
   return null;
   }
}

Example 3-2 List of Methods for the TransportMessage Class

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

Method	Description
public String toString();	Dump messages and headers.
public void setTransportHeader(String name, String value);	Set a transport-specific header.
public Properties getTransportHeaders();	Get all transport-specific headers 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.

FileSenderCustomizer Interface

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

The FileSenderCustomizer interface extends the SenderCustomizer interface. You must implement the FileSenderCustomizer interface by implement the following two methods:

• FileSenderCustomizer.customizeTransportMessage()

• FileSenderCustomizer.generateFileName()

However, if you do not want to implement the more complicated generateFileName() method, you can create a class that extends the oracle.oai.agent.adapter.technology.FileDefaultSenderCustomizer class, which is provided in the oai.jar file. In this case, you only need to implement the customizeTransportMessage() method.

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 customizeTransportMessage method.

Method

Description

customizeTransportMessage ();

This method specifies how to customize the transport message for transporting 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 that is 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. User can change the payload with the transportMessage parameter.

FileSenderCustomizer Interface

File Structure

The following is the file structure of the FileSenderCustomizer interface.

package oracle.oai.agent.adapter.technology;
import java.util.Date;
import oracle.oai.agent.adapter.sdk.MessageObject;
import oracle.oai.agent.adapter.sdk.AttributeObject;
import oracle.oai.agent.adapter.sdk.Agent;

public interface FileSenderCustomizer extends SenderCustomizer {
   public String generateFileName (Agent agent,
                                   String rule,
                                   String app,
                                   String partitition,
                                   Date time,
                                   MessageObject mobj,
                                   AttributeObject aobj);
}

File Summary

The following table summarizes the generateFileName method.

Method

Description

generateFileName ();

This method generates a file name for sending a file. It contains the following parameters: agent--Indicates that the user can use the Agent object to log message. rule--Indicates Rule for generating subject. This is read from file.sender.file_name_rule in adapter.ini. app--Indicates the application name. partition--Indicates Partition. time--This is a Date object which indicates the time the OracleAS InterConnect object is received. mobj--Indicates a MessageObject passed from OracleAS InterConnect. aobj--Indicates an AttributeObject passed from OracleAS InterConnect. This method returns a string representing the file name.

FTP Error Code

This section defines the error codes that the FTP adapter returns in the event of an exception.

The error code returned by the FTP adapter corresponds to the negative acknowledgment sent by the remote FTP server to the FTP adapter. The full list of the FTP reply codes can be found in Section 4.2.2 of RFC 959.

The FTP reply code consists of three digits. There are five possible values for the first digit.

The following is the interpretation of the reply code for the negative acknowledgment.

4xx:   Transient Negative Completion reply 
         The command is not accepted and the request action did not take place. 
         The error condition is transient and can be retried. 
5xx : Permanent Negative Completion reply 
         The command was not accepted and the request action did not take place. 
         The error condition is permanent and the user should  not retry. 

The second digit of the reply code corresponds to different functions:

x0x:  syntax error
x1x: Information
x2x: Connections
x3x: Authentication and accounting
x4x: Unspecified
x5x: File system

See Also: Oracle Application Server InterConnect User's Guide