3 Design-Time and Run-Time Concepts

This chapter describes the design-time and run-time concepts for the FTP adapter. It contains the following topics:

• FTP Adapter Design-Time Concepts

• FTP Adapter Run-Time Concepts

• Customizing the FTP Adapter

• Starting the FTP Adapter

• Stopping the FTP Adapter

FTP Adapter Design-Time Concepts

The FTP 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.

XML Payload Type

You can import a Document Type Definition (DTD) or XML Schema Definition in iStudio, which determines how the FTP 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, instead of D3L.

When the FTP 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 an XML document to OracleAS Integration InterConnect or after receiving one from OracleAS Integration InterConnect.

D3L Payload

The FTP adapter performs a two-way conversion and transformation of messages between application view and native format.

An application based on the FTP 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 FTP 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.

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

FTP Adapter Run-Time Concepts

This section describes the key run-time components of the FTP adapter. This section contains the following topics:

• FTP Receiver

• FTP Sender

FTP Receiver

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

The agent converts the application view event into a common view event and passes it to OracleAS Integration InterConnect for further routing and processing. Once the message is successfully passed to OracleAS Integration InterConnect, the corresponding FTP file on the remote FTP server or local file system is removed. 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, then the file will be discarded. 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 available in the adapter.ini in file.receiver.* format:

Note: The value of the exception directory should be a URL which represents either an FTP directory or a file location. An FTP URL can be specified for the exception directory if the receiving endpoint is also an FTP URL. The host name in the URL is 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. Ensure that 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.

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.

FTP Sender

The FTP adapter comprises the FTP bridge and the run-time 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 an FTP endpoint. The FTP endpoint is written as follows:

ftp://host name/directory path

The file name at the destination site is automatically generated by the adapter and is in the following syntax:

ftp adapter name partition-time stamp

You 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, add the parameter file.sender.file_name_rule to the adapter.ini file. The adapter recognizes the following tokens:

• %APP%: application name

• %BO%: business object name

• %EVENT%: corresponding event name

• %MV%: message version

• %PART%: partition number

• %TIME%: time stamp

• %TYPE%: message type

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

your app name_event name_current time stamp.xml

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

An endpoint can be associated with a subscribing event in iStudio by adding transport properties such as FTP endpoint, FTP user name, and endpoint password 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 FTP endpoint.

When using the multiple-endpoint feature with XML data type, select the Generic event type instead of XML. 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 to an event called SendOrder that sends an order to an FTP server at foo.com in the /private/user/test directory.

Table 3-1 SendOrder Event Metadata

Parameter	Description
file.sender.user=joe	Defines the FTP user name
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 FTP adapter

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

See Also: Oracle Application Server Integration InterConnect User's Guide

To avoid external applications picking up partial files, files that are not completely transferred, specify a staging directory. Set the file.sender.staging_dir parameter in the adapter.ini file. This parameter should contain only 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 an FTP server, then the path specified is a directory on the FTP server. Ensure that the path for the staging directory is valid.

The properties for the FTP receiver are available in the adapter.ini file in file.sender.* format.

Customizing the FTP Adapter

You can customize the adapter by implementing the following interfaces:

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

• oracle.oai.adapter.agent.technology.FileSenderCustomizer

The ReceiverCustomizer Interface

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

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

• To modify the message, 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);
}

The following table summarizes ReceiverCustomizer interface.

Methods	Description
createReplyMessage();	Creates a reply message based on the status of the message received. It contains the following parameters: agent: Log a message status: Status of the message process. If the value is TransportResponse.TRANSPORT_ACK, then the message is processed successfully. If the value is TransportResponse.TRANSPORT_ERROR, then the message has not been processed unsuccessfully. receivedTransportMessage: Transport message is received by the adapter. This parameter is used to transport headers in the transport message to create a meaningful message. The return string contains the reply message. This method is used for backward compatibility for the FTP adapter. However, for the FTP adapter, you should return a null value in this method.
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

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

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

      agent.logTraceMessage("payload received = " + payload, null, null, null);
//the following syntax removes the first line from the payload.
      String newPayload = removeFirstLine(payload);

      try {
         transportMessage.setBody(newPayload); 
      }
      catch(TransportException te) {
      . . . . 
      }
   }

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

List of Methods for the TransportMessage Class

The following table provides a list of methods you may choose for the TransportMessage class.

Method	Description
public byte[] getBodyAsBytes();	Get the body of the message as a 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.
public Properties getTransportHeaders();	Get all transport-specific headers and return a Properties object that contains all the transport headers.
public String getBodyAsString();	Get the body of the message as String object. Return the message in String object.
public String toString();	Dump messages and headers.
public void setBody(InputStream in) throws TransportException;	Set the body of the message. The body type will be set to bytes. Parameters: InputStream: Contains the message. It throws an exception of TransportException type.
public void setBody(String body) throws TransportException;	Set the body of the message. The body type will be set to String. Parameters: body: body of the message It throws an exception of TransportException type

The 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 implementing the following two methods:

• FileSenderCustomizer.customizeTransportMessage()

• FileSenderCustomizer.generateFileName()

If you do not want to implement the generateFileName() method, then 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 need to implement only the customizeTransportMessage() method.

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

This method specifies how to customize the transport message for transporting the sender. The adapter creates a TransportMessage object for the transport layer to send, based on the MessageObject object sent by OracleAS Integration InterConnect.

This method contains the following parameters:

• agent: Log messages

• transportMessage: The TransportMessage object that the adapter has created for sending

• mobj: The MessageObject from OracleAS Integration InterConnect

• aobj: The AttributeObject from OracleAS Integration InterConnect

  This method does not return anything. You can change the payload with the transportMessage parameter.

This method does not return anything. You can change the payload with the transportMessage parameter.

The FileSenderCustomizer Interface

The following code describes 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);
}

The generateFileName method

This method generates a file name for sending a file. It contains the following parameters:

• agent: Use the Agent object to log message

• rule: Rule for generating subject. This parameter is read from file.sender.file_name_rule in the adapter.ini file

• app: The application name

• partition: Partition

• time: The time the OracleAS Integration InterConnect object is received

• mobj: A MessageObject passed from OracleAS Integration InterConnect

• aobj: An AttributeObject passed from OracleAS Integration InterConnect

  This method returns a string representing the file name

Starting the FTP Adapter

The process for starting the adapter varies based on the operating system.

• To start the FTP adapter on UNIX:

  1. Change to the directory containing the start script.

     cd ORACLE_HOME/integration/interconnect/adapters/Application
     
     

  2. Type start and press Enter.

• To start the FTP adapter from Services on Windows:

  1. Access the Services window from the Start menu.

  2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

  3. Start the service based on the operating system.

     
     

     Note: You can also start and stop the FTP adapter using the IC Manager. Refer to Oracle Application Server Integration InterConnect User's Guide for more details.

     
     

Log File of FTP Adapter

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

timestamp_in_milliseconds

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

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

Stopping the FTP Adapter

The process for stopping the adapter varies based on the operating system.

• To stop the FTP adapter on UNIX:

  1. Change to the directory containing the stop script.

     cd ORACLE_HOME/integration/interconnect/adapters/Application
     
     

  2. Type stop and press Enter.

• To stop the FTP adapter from Services on Windows:

  1. Access the Services window from the Start menu.

  2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

  3. Stop the service based on the operating system.

  You can verify the stop status of the FTP adapter by viewing the log.xml files. These files are located in the time-stamped subdirectory of the log directory of the FTP adapter.