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

• Starting the FTP Adapter

• Stopping 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: Oracle9iAS InterConnect User Guide

XML Payload

Users can import a DTD in iStudio which governs how the FTP adapter will parse a received XML document into a Oracle9iAS 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. Any XSLT transformations are performed before sending an XML document to Oracle9iAS InterConnect or after receiving one from Oracle9iAS 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: Oracle9iAS InterConnect User Guide

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 Oracle9iAS InterConnect functionality.

• FTP Sender--From Oracle9iAS 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 Oracle9iAS 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 Oracle9iAS InterConnect for further routing and processing. Once the message is successfully handled off to Oracle9iAS 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.

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.

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.

Parameter	Description
ota.endpoint=sendOrderAppEP	Specifies a unique endpoint name.
oracle.oai.agent.adapter.technology. 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

See Also: Oracle9iAS InterConnect User 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><instance number>-<time stamp>

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

Starting the FTP Adapter

Start the FTP adapter using the start script in the directory named after the FTP adapter. On Windows or Windows 2000, start it from the Service 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 displays.

2. Select the OracleHome9iASInterConnectAdapter-Application service.

3. Start the service based on your operating system:

   On...	Choose...
   Windows NT	Choose Start.
   Windows 2000	Right click the service and choose Start from the menu that displays.

   See Also: "FTP Adapter Configuration" for the location of the start script

Sample Log File of Successfully Started Advanced Queuing Adapter

The following file displays an FTP adapter that was started successfully:

D:\oracle\ora902\oai\9.0.2\adapters\ftpapp>D:\oracle\ora902\oai\9.0.2·in\JavaSer
vice.exe -debug "Oracle OAI Adapter 9.0.2 - ftpapp"
D:\oracle\ora9021\oai\9.0.2\adapters\ftpapp adapter.ini 
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

Stop the FTP adapter using the stop script in the directory named after the FTP adapter. On Windows NT or Windows 2000, stop the adapter 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 displays.

2. Select the OracleHome9iASInterConnectAdapter-Application service.

3. Start the service based on your operating system:

   On...	Choose...
   Windows NT	Choose Stop.
   Windows 2000	Right click the service and choose Stop from the menu that displays.

   Stop status can be verified by viewing the oailog.txt files in the appropriate timestamped subdirectory of the log directory of the adapter directory.

   See Also: "FTP Adapter Configuration" for the location of the start script

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

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: Oracle9iAS InterConnect User Guide