3 Design-Time and Run-Time Concepts

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.

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:

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.

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.

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

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.

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 {

   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.

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.

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);
}

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);
}

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.