Skip Headers
Oracle® Application Server Adapters for Files, FTP, Databases, and Enterprise Messaging User's Guide
10g Release 3 (10.1.3.1.0)

Part Number B28994-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

2 Oracle Application Server Adapter for Files/FTP

This chapter describes how to use the Oracle Application Server Adapter for Files/FTP (file and FTP adapters), which work in conjunction with Oracle BPEL Process Manager and Oracle Enterprise Service Bus as an external service. References to use cases for the file and FTP adapters are also provided.

This chapter contains the following sections:


Note:

The term Oracle Application Server Adapter for Files/FTP is used for the file and FTP adapters, which are separate adapters with very similar functionality.

2.1 Introduction to File and FTP Adapters

Oracle BPEL Process Manager and Oracle Enterprise Service Bus include the file and FTP adapters. The file and FTP adapters enable a BPEL process or an ESB service to exchange (read and write) files on local file systems and remote file systems (through use of the file transfer protocol (FTP)). The file contents can be both XML and non-XML data formats.

This section contains the following topics:

2.1.1 File and FTP Adapters Features

The file and FTP adapters enable you to configure a BPEL process or an ESB service to interact with local and remote file system directories. This section explains the following features of the file and FTP adapters:

2.1.1.1 File Formats

The file and FTP adapters can read and write the following file formats and use the adapter translator component at both design time and run time:

  • XML (both XSD- and DTD-based)

  • Delimited

  • Fixed positional

  • Binary data

  • COBOL Copybook data

The file and FTP adapters can also treat file contents as an opaque object and pass the contents in their original format (without performing translation). The opaque option handles binary data, such as JPGs and GIFs, whose structure cannot be captured in an XSD or data you do not want to have translated.

The translator enables the file and FTP adapters to convert native data in various formats to XML. The native data can be simple (just a flat structure) or complex (with parent-child relationships). The translator can handle both XML as well as non-XML (native) format of data.

2.1.1.2 FTP Servers

The FTP adapter supports Solaris and Windows FTP servers. The FTP adapter also supports the use of FTP over SSL (FTPS) on Solaris.

2.1.1.3 Inbound and Outbound Interactions

The file and FTP adapters exchange files in the inbound and outbound directions. Based on the direction, the file and FTP adapters perform a different set of tasks.

For inbound files sent to Oracle BPEL Process Manager or Oracle Enterprise Service Bus, the file and FTP adapters perform the following operations:

  1. Poll the file system looking for matches

  2. Read and translate the file content based on the native schema (NXSD) defined at the design time

  3. Publish the translated content as an XML message

This functionality of the file and FTP adapters is referred to as the file read operation and the component that provides this function as the file reader. This operation is known as a Java Connector Architecture (JCA) inbound interaction.

For outbound files sent from Oracle BPEL Process Manager or Oracle Enterprise Service Bus, the file and FTP adapters perform the following operations:

  1. Receive messages from BPEL

  2. Format the XML contents as specified at design time

  3. Produce output files. The output files can be created based on following criterias: time elapsed, file size, and number of messages. You can also specify combination of these criterias for output files.

This functionality of the file and FTP adapters is referred to as the file write operation and the component that provides this functionality as the file writer. This operation is known as a JCA outbound interaction.

For the inbound and outbound directions, the file and FTP adapters use a set of configuration parameters. For example:

  • The inbound file and FTP adapters have parameters for the inbound directory where the input file appears and the frequency with which to poll the directory.

  • The outbound file and FTP adapters have parameters for the outbound directory in which to write the file and the file naming convention to use.

The file writer offers several conditions for output file creation. The output files can be created based on time elapsed, file size, and number of messages received.

The file reader supports polling conventions and offers several postprocessing options. You can specify to delete, move, or leave the file as it is after processing the file. The file reader can split the contents of a file and publish it in batches, instead of as a single message. This feature can be used for performance tuning of the file and FTP adapters. The file reader guarantees once and once-only delivery.

See the following sections for details about the read and write functionality of the file and FTP adapters:

2.1.1.4 File Debatching

When a file contains multiple messages, you can select to publish messages in a specific number of batches. This is referred to as debatching. During debatching, the file reader, upon restart, proceeds from where it left off in the previous run, thereby avoiding duplicate messages.

2.1.1.5 Dynamic Outbound Directory and File Name Specification

The file and FTP adapters enable you to dynamically specify the logical or physical name of the outbound file or outbound directory. For information about how to specify dynamic outbound directory, refer to Section 2.2.2.2, "Outbound File Directory Creation".

2.1.1.6 Security

The FTP adapter supports secure FTP and SFTP to enable secure file transfer over the network.

Refer to Section 2.3, "Using Secure FTP with the FTP Adapter" and Section 2.4, "Using SFTP with the FTP Adapter" for more information.

2.1.1.7 Proxy Support

The proxy support feature of the FTP adapter can be used to transfer and retrieve data to and from the FTP servers that are located outside a firewall or can only be accessed through a proxy server. A proxy server enables the hosts in an intranet to indirectly connect to hosts on the Internet. Figure 2-1 shows how a proxy server creates connections to simulate a direct connection between the client and the remote FTP server.

Figure 2-1 Remote FTP Server Communication Through a Proxy Server

Description of Figure 2-1 follows
Description of "Figure 2-1 Remote FTP Server Communication Through a Proxy Server"

To use the HTTP proxy feature, your proxy server must support FTP traffic via HTTP Connect. In addition, only passive data connections are supported with this feature. For information about how to configure the FTP adapter, refer to Section 2.5, "Configuring the FTP Adapter for HTTP Proxy".

2.1.1.8 No Payload Support

For Oracle BPEL Process Manager, the file and FTP adapters provide support for publishing only file metadata such as filename and directory to a BPEL process and exclude the payload. The BPEL process can use this metadata for subsequent processing. For example, the BPEL process can call another partner link and pass the file and directory name for further processing. So, the file and FTP adapters can be used as a notification service to notify a BPEL process whenever a new file appears in the inbound directory. To use this feature, you need to specify the value of the UseHeaders parameter, which is an activation spec parameter. Set the UseHeaders parameter as true in the file adapter WSDL file as shown in the following example:

UseHeaders="true"

A sample wsdl file is shown in the following example:

<jca:operation
          PhysicalDirectory="E:\Customer\In"
          ActivationSpec="oracle.tip.adapter.file.inbound.FileActivationSpec"
          PhysicalArchiveDirectory="E:\Customer\Archive"
          DeleteFile="true"
          IncludeFiles=".*\.xml"
          ExcludeFiles=".*\.txt"
          PollingFrequency="3"
          MinimumAge="0"
          OpaqueSchema="false" >
          UseHeaders="true"
      </jca:operation>

2.1.1.9 File-Based Triggers

The file and FTP adapters provide support for file-based triggers which can be used to control inbound adapter endpoint activation. For information about how to use file-based triggers, refer to Section 2.2.1.4, "File Polling".

2.1.1.10 High Availability

The file and FTP adapters support the high availability feature for the active-passive topology with Oracle BPEL Process Manager. Perform the following steps to configure the file and FTP adapters for this feature:

  1. Create a share folder on highly available file system. This folder should have the write permission and should be accessible from all the systems that are running the file and FTP adapters.

  2. Open the pc.properties file available in the ORAHOME\bpel\system\service\config directory.

  3. Set oracle.tip.adapter.file.controldirpath to the shared folder name or a UNC path.

    For example:

    oracle.tip.adapter.file.controldirpath := Z:\\myshare
    or
    oracle.tip.adapter.file.controldirpath := \\Myserver\Mydirectory
    
    
  4. Restart the Oracle BPEL Process Manager server.

2.1.2 File and FTP Adapters Architecture

The file and FTP adapters are based on JCA 1.5 architecture. JCA provides a standard architecture for integrating heterogeneous enterprise information systems (EIS). The adapter framework of the file and FTP adapters exposes the underlying JCA interactions as services (WSDL with JCA binding) for Oracle BPEL Process Manager integration. See Oracle Application Server Adapter Concepts Guide for details about OracleAS Adapter architecture.

2.1.3 File and FTP Adapters Integration with Oracle BPEL Process Manager

The file and FTP adapters are automatically integrated with Oracle BPEL Process Manager. When you create a partner link in JDeveloper BPEL Designer, the Adapter Configuration Wizard starts, as shown in Figure 1-2.

This wizard enables you to select and configure the file and FTP adapters or other OracleAS Adapters, as shown in Figure 1-3. The Adapter Configuration Wizard then prompts you to enter a service name, as shown in Figure 1-4. When configuration is complete, a WSDL file of the same name is created in the Applications Navigator section of Oracle JDeveloper. This WSDL file contains the configuration information you specify with the Adapter Configuration Wizard.

The Operations window of the Adapter Configuration Wizard prompts you to select an operation to perform. Based on your selection, different Adapter Configuration Wizard windows appear and prompt you for configuration information. Table 2-1 lists the available operations and provides references to sections that describe the configuration information you must provide.

Table 2-1 Supported Operations for Oracle BPEL Process Manager

Operation Section

File Adapter

-

  • Read File (inbound operation)

Section 2.2.1, "File Adapter Read File Concepts"


  • Write File (outbound operation)

Section 2.2.2, "File Adapter Write File Concepts"


FTP Adapter

-

  • Get File (inbound operation)

Section 2.2.3, "FTP Adapter for Get File Concepts"


  • Put File (outbound operation)

Section 2.2.4, "FTP Adapter for Put File Concepts"



See Oracle Application Server Adapter Concepts Guide for more information about OracleAS Adapter integration with Oracle BPEL Process Manager.

2.1.4 File and FTP Adapters Integration with Oracle Enterprise Service Bus

The file and FTP adapters are automatically integrated with Oracle Enterprise Service Bus. When you create a File or FTP adapter service in JDeveloper ESB Designer, the Adapter Configuration Wizard is started as shown in Figure 1-2.

This wizard enables you to select and configure the file and FTP adapters. When configuration is complete, a WSDL file of the same name is created in the Applications Navigator section of Oracle JDeveloper. This WSDL file contains the configuration information you specify with the Adapter Configuration Wizard.

The Operations window of the Adapter Configuration Wizard prompts you to select an operation to perform. Based on your selection, different Adapter Configuration Wizard windows appear and prompt you for configuration information. Table 2-2 lists the available operations and provides references to sections that describe the configuration information you must provide.

Table 2-2 Supported Operations for Oracle Enterprise Service Bus

Operation Section

File Adapter

-

  • Read File (inbound operation)

Section 2.2.1, "File Adapter Read File Concepts"


  • Write File (outbound operation)

Section 2.2.2, "File Adapter Write File Concepts"


FTP Adapter

-

  • Get File (inbound operation)

Section 2.2.3, "FTP Adapter for Get File Concepts"


  • Put File (outbound operation)

Section 2.2.4, "FTP Adapter for Put File Concepts"



See Oracle Application Server Adapter Concepts Guide for more information about OracleAS Adapter integration with Oracle Enterprise Service Bus.

2.2 File and FTP Adapters Concepts

This section contains the following topics:

2.2.1 File Adapter Read File Concepts

In the inbound direction, the file adapter polls and reads files from a file system for processing. This section provides an overview of the inbound file reading capabilities of the file adapter. You use the Adapter Configuration Wizard to configure the file adapter for use with a BPEL process or an ESB service. This creates an inbound WSDL file named after the service name you specify with the Adapter Configuration Wizard. An inbound header file named fileAdapterInboundheader.wsdl is also created.

This section contains the following topics:

2.2.1.1 Inbound Operation

For inbound operations with the file adapter, you select Read File operation as shown in Figure 2-2.

Figure 2-2 Selecting the Read File Operation

Description of Figure 2-2 follows
Description of "Figure 2-2 Selecting the Read File Operation"

2.2.1.2 Inbound File Directory Specifications

The File Directories window of the Adapter Configuration Wizard shown in Figure 2-3 enables you to specify information about the directory to use for reading inbound files and the directories in which to place successfully processed files.

Figure 2-3 Adapter Configuration Wizard-Specifying Incoming Files

Description of Figure 2-3 follows
Description of "Figure 2-3 Adapter Configuration Wizard-Specifying Incoming Files"

The following sections describe the file directory information to specify:

Specifying Inbound Physical or Logical Directory Paths in Oracle BPEL Process Manager

You can specify inbound directory names as physical or logical paths in Oracle BPEL Process Manager and Oracle Enterprise Service Bus. Physical paths are values such as c:\inputDir.

In Oracle BPEL Process Manager, logical properties are specified in the inbound WSDL file and their logical-physical mapping is resolved using partner link properties. You specify the logical parameters once at design time, and you can later modify the physical directory name as needed.

For example, the generated inbound WSDL file looks as follows for the logical input directory name InputFileDir.

<operation name="Read">
   <jca:operation
      LogicalDirectory="InputFileDir"
      ActivationSpec="oracle.tip.adapter.file.inbound.FileActivationSpec"
      IncludeFiles=".*"
      PollingFrequency="5"
      MinimumAge="0"
      DeleteFile="true"
      OpaqueSchema="true" >
   </jca:operation>

In the BPEL partner link of the bpel.xml file, you then provide the physical parameter values (in this case, the directory path) of the corresponding logical ActivationSpec or InteractionSpec. This resolves the mapping between the logical directory name and actual physical directory name.

<?xml version = '1.0' encoding = 'UTF-8'?>
<BPELSuitcase>
  <BPELProcess id="ComplexStructure" src="ComplexStructure.bpel">
    <partnerLinkBindings>
      <partnerLinkBinding name="InboundPL">
        <property name="wsdlLocation">ComplexStructureInbound.wsdl</property>
      </partnerLinkBinding>
      <partnerLinkBinding name="OutboundPL">
        <property name="wsdlLocation">ComplexStructureOutbound.wsdl</property>
      </partnerLinkBinding>
    </partnerLinkBindings>
      <activationAgents>
      <activationAgentclassName=
"oracle.tip.adapter.fw.agent.jca.JCAActivationAgent"partnerLink="InboundPL">
      <property name="InputFileDir">C:/ora_home/integration/bpm/samples/tutorials/
121.FileAdapter/ComplexStructure/InputDir/</property>
      <property name="portType">Read_ptt</property>
    </activationAgent>
   </activationAgents>
  /BPELProcess>
</BPELSuitcase>

Note:

Multiple file adapters polling one inbound directory are not supported. Ensure that each is polling its own unique directory.

Editing the Existing Logical Name Removes the Mapping in the bpel.xml File The File Directories window of the Adapter Configuration Wizard enables you to specify logical names instead of physical directory paths for both the incoming files directory and archive directory when using the FTP or File adapter. You must also provide corresponding property settings in the bpel.xml file (either manually or through the Property tab of the partner link activity).

If you later rerun the Adapter Configuration Wizard and change the logical name of either the physical directory path or the archive directory, both properties are removed from the bpel.xml file. You must update both these properties in the bpel.xml file.

Specifying Inbound Physical or Logical Directory Paths in Oracle Enterprise Service Bus

You can specify inbound directory names as physical or logical paths in Oracle Enterprise Service Bus. Physical paths are values such as c:\inputDir.

For logical names, you can specify the logical names at design time in the File Directories window shown in Figure 2-3 and then provide logical-physical mapping by using the Endpoint properties. For example, ReadFile is an inbound adapter service. You have specified InputFileDir as the logical directory name at design time. After completing the Adapter Configuration wizard, when you click the ReadFile_esbsvc file, the inbound file adapter window similar to the one shown in Figure 2-4 is displayed.

Figure 2-4 Sample Inbound File Adapter Window

Description of Figure 2-4 follows
Description of "Figure 2-4 Sample Inbound File Adapter Window"

When you click the plus sign (+) in Endpoint Properties section, the Endpoint Property Chooser dialog box shown in Figure 2-5 is displayed.

Figure 2-5 Endpoint Property Chooser Dialog Box

Description of Figure 2-5 follows
Description of "Figure 2-5 Endpoint Property Chooser Dialog Box"

Select the InputFileDir property and click OK. Now you can specify the physical directory name in the Value field as shown in Figure 2-6.

Figure 2-6 Endpoint Properties Section

Description of Figure 2-6 follows
Description of "Figure 2-6 Endpoint Properties Section"

Archiving Successfully Processed Files

This option enables you to specify a directory in which to place successfully processed files. You can also specify the archive directory as a logical name. In this case, you must follow the logical-to-physical mappings described in "Specifying Inbound Physical or Logical Directory Paths in Oracle BPEL Process Manager" and "Specifying Inbound Physical or Logical Directory Paths in Oracle Enterprise Service Bus".


Note:

Files that are 7MB or larger in size cannot be delivered. As an alternative, you can debatch large files (if they have multiple messages), and publish these files in messages of size less than 7 MB. This alternative is applicable only to structured files (comma-delimited or fixed position), which contain more than one message. It is not applicable to binary or XML files.

Deleting Files After Retrieval

This option enables you to specify whether or not to delete files after a successful retrieval. If this check box is not selected, processed files remain in the inbound directory, but are ignored. Only files with modification dates more recent than the last processed file are retrieved. If you place another file in the inbound directory with the same name as a file that has already been processed, but the modification date remains the same, then that file is not retrieved.

2.2.1.3 File Matching and Batch Processing

The File Filtering window of the Adapter Configuration Wizard shown in Figure 2-7 enables you to specify details about the files to retrieve or ignore.

The file adapter acts as a file listener in the inbound direction. The file adapter polls the specified directory on a local or remote file system and looks for files that match a specified naming criteria.

Figure 2-7 Adapter Configuration Wizard-File Filtering

Description of Figure 2-7 follows
Description of "Figure 2-7 Adapter Configuration Wizard-File Filtering"

The following sections describe the file filtering information to specify:

Specifying a Naming Pattern

Specify the naming convention that the file adapter uses to poll for inbound files. You can also specify the naming convention for files you do not want to process. Two naming conventions are available for selection. The file adapter matches the files that appear in the inbound directory.

  • File wildcards (po*.txt)

    Retrieves all files that start with po and end with .txt. This convention conforms to Windows operating system standards.

  • Regular expressions (po.*\.txt)

    Retrieves all files that start with po and end with .txt. This convention conforms to Java Development Kit (JDK) regular expression (regex) constructs.


Notes:

  • If you later select a different naming pattern, ensure that you also change the naming conventions you specify in the Include Files and Exclude Files fields. The Adapter Configuration Wizard does not automatically make this change for you.

  • Do not specify *.* as the convention for retrieving files.

  • Be aware of any file length restrictions imposed by your operating system. For example, Windows operating system file names cannot be more than 256 characters in length (the filename, plus the complete directory path). Some operating systems also have restrictions on the use of specific characters in file names. For example, Windows operating systems do not allow characters such as \, /, :, *, <, >, or |.


Including and Excluding Files

If you use regular expressions, the values you specify in the Include Files and Exclude Files fields must conform to JDK regular expression (regex) constructs. For both fields, different regex patterns must be provided separately. The Include Files and Exclude Files fields correspond to the IncludeFiles and ExcludeFiles parameters, respectively, of the inbound WSDL file.


Note:

The regex pattern complies with the JDK regex pattern. According to the JDK regex pattern, the correct connotation for a pattern of any characters with any number of occurrences is a period followed by a plus sign (.+). An asterisk (*) in a JDK regex is not a placeholder for a string of any characters with any number of occurrences.

If you want the inbound file adapter to pick up all file names that start with po and which have the extension txt, you must specify the Include Files field as po.*\.txt when the name pattern is a regular expression. In this regex pattern example:

  • A period (.) indicates any character

  • An asterisk (*) indicates any number of occurrences

  • A backslash followed by a period (\.) indicates the character period (.), as indicated with the backslash escape character

The Exclude Files field is constructed similarly.

If you have Include Files field and Exclude Files field expressions that have an overlap, then the exclude files expression takes precedence. For example, if Include Files is set to abc*.txt and Exclude Files is set to abcd*.txt, then you receive any files prefixed with abcd*.

Table 2-3 lists details of Java regex constructs.


Note:

Do not begin JDK regex pattern names with the following characters: +, ?, or *.

Table 2-3 Java Regular Expression Constructs

Matches Construct

Characters

-

The character x

x

The backslash character

\\


The character with octal value 0n (0 <= n <= 7)

\0n

The character with octal value 0nn (0 <= n <= 7)

\0nn

The character with octal value 0mnn (0 <= m <= 3, 0 <= n <= 7)

\0mnn

The character with hexadecimal value 0xhh

\xhh

The character with hexadecimal value 0xhhhh

\uhhhh

The tab character ('\u0009')

\t

The newline (line feed) character ('\u000A')

\n

The carriage-return character ('\u000D')

\r

The form-feed character ('\u000C')

\f

The alert (bell) character ('\u0007')

\a

The escape character ('\u001B')

\e

The control character corresponding to x

\cx

-

-

Character classes

-

a, b, or c (simple class)

[abc]

Any character except a, b, or c (negation)

[^abc]

a through z or A through Z, inclusive (range)

[a-zA-Z]

a through d, or m through p: [a-dm-p] (union)

[a-d[m-p]]

d, e, or f (intersection)

[a-z&&[def]]

a through z, except for b and c: [ad-z] (subtraction)

[a-z&&[^bc]]

a through z, and not m through p: [a-lq-z](subtraction)

[a-z&&[^m-p]]

-

-

Predefined character classes

-

Any character (may or may not match line terminators)

-

A digit: [0-9]

\d

A nondigit: [^0-9]

\D

A whitespace character: [ \t\n\x0B\f\r]

\s

A nonwhitespace character: [^\s]

\S

A word character: [a-zA-Z_0-9]

\w

A nonword character: [^\w]

\W

Greedy quantifiers

-

X, once or not at all

X?

X, zero or more times

X*

X, one or more times

X+

X, exactly n times

X{n}

X, at least n times

X{n,}

X, at least n, but not more than m times

X{n,m}


For details about Java regex constructs, go to

http://java.sun.com/j2se/1.4.2/docs/api

Debatching Multiple Inbound Messages

You can select if incoming files have more than one message, and specify the number of messages in one batch file to publish. When a file contains multiple messages and this check box is selected, this is referred to as debatching. Nondebatching is when the file contains only a single message and the check box is not selected. Debatching is not supported if the input file is in XML format.

2.2.1.4 File Polling

The File Polling window of the Adapter Configuration Wizard shown in Figure 2-8 enables you to specify the following inbound polling parameters:

  • The frequency with which to poll the inbound directory for new files to retrieve.

  • The minimum file age of files to retrieve. For example, this enables a large file to be completely copied into the directory before it is retrieved for processing. The age is determined by the last modified time stamp. For example, if you know that it takes three to four minutes for a file to be written, then set the minimum age to five minutes. If a file is detected in the input directory and its modification time is less than five minutes older than the current time, then the file is not retrieved because it is still potentially being written to.

Figure 2-8 Adapter Configuration Wizard-File Polling

Description of Figure 2-8 follows
Description of "Figure 2-8 Adapter Configuration Wizard-File Polling"

Using Trigger Files

By default, polling by inbound file and FTP adapters start as soon as the endpoint is activated. However, if you want more control over polling, then you can use a file-based trigger. Once the file and the FTP adapter finds the specified trigger file in local or remote directory, it starts polling for the files in the inbound directory.

For example, a BPEL process is writing files to a InOut directory. A second BPEL process is polling the same directory for files. If you want the second process to start polling the directory only after the first process has written all the files, then you can use a trigger file. You can configure the first process to create a trigger file at the end. The second process will start polling the inbound directory once it finds the trigger file.

The trigger file directory can be the same as the inbound polling directory or different from the inbound polling directory. However, if your trigger file directory and the inbound polling directory are the same, then you should ensure that the name of the trigger file is not similar to the file filter specified in the Adapter Configuration window shown in Figure 2-7.

The content of a trigger file is never read and therefore should not be used as payload for an inbound receive activity.

Table 2-4 lists the parameters that you need to specify in the inbound service WSDL file:

Table 2-4 Trigger File Parameters

Parameter Description Example

TriggerFilePhysicalDirectory

or

TriggerFileLogicalDirectory

The physical or logical name of the directory which the file and FTP adapters will look for the trigger file.

The TriggerFilePhysicalDirectory and TriggerFileLogicalDirectory parameters are optional. These parameters should be used only if the trigger file directory is different from the inbound polling directory. By default, the file and FTP adapters looks for the trigger file in the inbound polling directory.

The TriggerFileLogicalDirectory parameter is not supported in Oracle Enterprise Service Bus.

TriggerFilePhysicalDirectory="C:\foo"

TriggerFileLogicalDirectory= "TriggerFileDir"

TriggerFile

The name of the trigger file.

TriggerFile="Purchaseorder.trg"


A sample inbound service WSDL is shown in the following example:

<jca:operation
         
         PhysicalDirectory="C:\ORAHOME\integration\jdev\jdev\mywork\triggers_
         proj\inputDir"
         ActivationSpec="oracle.tip.adapter.file.inbound.FileActivationSpec"
         IncludeFiles="Order.*\.xml"
         PollingFrequency="30"
         MinimumAge="0"
         DeleteFile="false"
         OpaqueSchema="true" 
         TriggerFilePhysicalDirectory="C:\foo"
         TriggerFile="Purchaseorder.trg"
</jca:operation>


Note:

The file and FTP adapters look for the trigger file in the trigger file directory each time the endpoint gets activated.

2.2.1.5 File Processing

The file adapter prepares the files for processing and delivers them to the adapter translator for translation and debatching (if necessary).

If you have many inbound files to process or very large files of more than 1 MB, you may need to increase the config timeout value in the transaction-manager.xml file as shown in the following example:

<transaction-timeout="30000"/>

The location of the transaction-manager.xml file depends on your installation type. Table 2-5 lists the installation type and the corresponding transaction-manager.xml file location.

Table 2-5 Transaction-manager.xml File Location

Installation Type File Location

SOA Basic Installation

Oracle_Home\j2ee\home\config

Oracle Enterprise Service Bus on Oracle Application Server Middle tier

Oracle_Home\j2ee\homemid\config

Oracle BPEL Process Manager on Oracle Application Server Middle tier

Oracle_Home\j2ee\homemid\config


2.2.1.6 Postprocessing

The file adapter supports several postprocessing options. After processing the file, files are deleted if specified in the File Polling window shown in Figure 2-8. Files can also be moved to a completion (archive) directory if specified in the File Directories window shown in Figure 2-3.

2.2.1.7 Native Data Translation

The next Adapter Configuration Wizard window that appears is the Messages window shown in Figure 2-9. This window enables you to select the XSD schema file for translation.

Figure 2-9 Specifying the Schema

Description of Figure 2-9 follows
Description of "Figure 2-9 Specifying the Schema"

If native format translation is not required (for example, a JPG or GIF image is being processed), then select the Native format translation is not required check box. The file is passed through in base-64 encoding.

XSD files are required for translation. If you want to define a new schema or convert an existing data type definition (DTD) or COBOL Copybook, then select Define Schema for Native Format. This starts the Native Format Builder Wizard. This wizard guides you through the creation of a native schema file from file formats such as comma-separated value (CSV), fixed-length, DTD, and COBOL Copybook. After the native schema file is created, the Messages window is displayed with the Schema File URL and Schema Element fields filled in. See Section 7.1, "Creating Native Schema Files with the Native Format Builder Wizard" for more information.


Note:

Ensure that the schema you specify includes a namespace. If your schema does not have a namespace, then an error message is displayed.

2.2.1.8 Error Handling

The file adapter provides several inbound error handling capabilities:

rejectedMessageHandlers Property

This property is specific to Oracle BPEL Process Manager. You can configure your BPEL process to process the correct records of a file and write only the rejected records to an archive directory by setting the rejectedMessageHandlers property. For example, assume that you have a file with four records. If three records are processed successfully and one record is not, then the file is processed with the three correct records. The errored record is written to a rejected messages directory. If a file has only message, the entire message is rejected.

You first define the rejectedMessageHandlers property as an activationAgent property in the bpel.xml file so that it applies to inbound WSDL operations only:

<BPELSuitcase>
  <BPELProcess src="ErrorTest.bpel" id="ErrorTest">
    <activationAgents>
       <activationAgent
          className="oracle.tip.adapter.fw.agent.jca.JCAActivationAgent"
                        partnerLink="inboundPL">
         <property name="rejectedMessageHandlers">
            file://C:/orabpel/samples/test/errorTest/rejectedMessages
         </property>

This causes errored messages to be written to the configured directory using the following naming pattern:

INVALID_MSG_ + process-name + operation-name + current-time



The rejection handlers can be other BPEL processes, WSIF handlers, or Oracle Advanced Queue handlers.



fatalErrorFailoverProcess Property


This property is specific to Oracle BPEL Process Manager and not for Oracle Enterprise Service Bus. If the file adapter (or any OracleAS Adapter) encounters an unrecoverable system error (such as no more memory or a full disk), it can instruct the adapter framework to shut down the BPEL process. 



You can optionally configure a standby (or failover) BPEL process to be invoked when the adapter starts the shutdown request of the (main) BPEL process.



You configure this failover BPEL process by setting the fatalErrorFailoverProcess property as an activationAgent property in the bpel.xml file.
<property name="fatalErrorFailoverProcess"> bpel://bpel-domain:password|process-name|operation-name|
input-message-part-name
</property>

where password (which can be omitted if it is bpel) can be encrypted.

For example:

<property name="fatalErrorFailoverProcess">

  bpel://default|JCA-FatalErrorHandler|handleError|message
</property>

or

<property name="fatalErrorFailoverProcess"> 
 bpel://default:C23487CFA591952D3ED0B81F0961F65A|JCA-FatalErrorHandler|handleError|message</property>

where the bpel password was specified in encrypted form (using the encrypt.bat (for Windows) or encrypt.sh (for UNIX) command line utility).

The fatal error BPEL process must use a specific input (WSDL) message type. This message type is defined in the system-provided WSDL file FatalErrorMessageWSDL.wsdl. This WSDL can be referenced (imported) using the following:

<import namespace="http://xmlns.oracle.com/pcbpel/fatalErrorHandler"         location="http://localhost:9700/orabpel/xmllib/jca/FatalErrorMessage.wsdl"/>

The XML schema type for this message is as follows:

<complexType name="FatalErrorMessageType">
  <sequence>
    <element name="Reason" type="string"/>
    <element name="Exception" type="string"/>
    <element name="StackTrace" type="string"/>
  </sequence>
</complexType>

The purpose of the failover BPEL process can be to undertake error compensating actions, alert someone through e-mail or short message service (SMS), or restart some other process.

uniqueMessageSeparator Property

In the case of debatching (multiple messages in a single file), messages from the first bad message to the end of the file are rejected. If each message has a unique separator and that separator is not part of any data, then rejection can be more fine-grained. In these cases, you can define a uniqueMessageSeparator in the schema element of the native schema to have the value of this unique message separator. This property controls how the adapter translator works when parsing through multiple records in one file (debatching). This property enables recovery even when detecting bad messages inside a large batch file; when a bad record is detected, the adapter translator skips to the next unique message separator boundary and continues from there. If you do not set this property, then all records that follow the errored record are also rejected.

The following schema file provides an example of using uniqueMessageSeparator.

<?xml version="1.0" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
            targetNamespace="http://TargetNamespace.com/Reader"
            xmlns:tns="http://TargetNamespace.com/Reader"
            elementFormDefault="qualified" attributeFormDefault="unqualified"
            nxsd:encoding="US-ASCII" nxsd:stream="chars" 
            nxsd:version="NXSD" nxsd:uniqueMessageSeparator="${eol}">
  <xsd:element name="emp-listing">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="emp" minOccurs="1" maxOccurs="unbounded">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="GUID" type="xsd:string" nxsd:style="terminated"
                           nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Designation" type="xsd:string"
                           nxsd:style="terminated" nxsd:terminatedBy=","
                           nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Car" type="xsd:string" nxsd:style="terminated"
                           nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Labtop" type="xsd:string"
                           nxsd:style="terminated" nxsd:terminatedBy=","
                           nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Location" type="xsd:string"
                           nxsd:style="terminated" nxsd:terminatedBy=","
                           nxsd:quotedBy="&quot;">
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>
<!--NXSDWIZ:D:\work\jDevProjects\Temp_BPEL_process\Sample2\note.txt:-->
<!--USE-HEADER:false:-->

Default Error Directory

If you do not set the rejectedMessageHandlers property in Oracle BPEL Process Manager, then errored records during translation are placed by default in the following directory:

Oracle_Home\bpel\domains\domain_name\jca\project_directory\rejectedMessages

If you do not set the rejectedMessageHandlers property in Oracle Enterprise Service Bus, errored records during translation are placed by default in the following directory:

Oracle_Home\j2EE\jca\event_name\rejectedMessages

2.2.1.9 Guaranteed Delivery and Recovery from Server Failures

For Oracle BPEL Process Manager, the file and FTP adapters guarantee once-only delivery of inbound files. This includes guaranteed delivery of large files through FTP. If your system has to shut down for some reason, then the read functionality of the file adapter upon restart avoids creating duplicate messages.

In case of debatching, the file and FTP adapters internally stores the line, column, or byte position of the files being processed and in case of a BPEL server failure, the file and FTP adapters start reading from where it had left off. If the FTP server fails, the inbound adapter goes into an error-recovery mode and keeps checking if the server is up periodically.

For FTP adapter, in case of non-debatching, the file being processed gets deleted only after it has been retrieved from the FTP server and published to Oracle BPEL Process Manager. In case of failure, the file is either rejected or it does not get deleted. If the file gets rejected, it goes to the default or user-specified rejected directory as mentioned in the rejectedMessageHandlers Property and Default Error Directory sections. However, if the file is not deleted, it is picked up again when the server restarts.

If your system server shuts down while inbound messages are being processed, you must manually perform recovery when the server restarts to ensure that all message records are recovered. For example, a file has ten messages and the server shuts down after three messages have been processed. This causes the fourth message to go undelivered. When the server restarts and begins processing with message five (the offset of the last successfully rejected message), you must manually recover message four to ensure that all messages are preserved.

Perform the following procedures to recover the rejected message record.

  1. Log in to Oracle BPEL Control.

  2. Click the BPEL Processes tab.

  3. Click Perform Manual Recovery under the Related Tasks section.

  4. Click Recover.

2.2.1.10 Inbound Service Name WSDL File

When you finish configuring the file adapter, a WSDL file is generated for the inbound direction. The file is named after the service name you specified on the Service Name window of the Adapter Configuration Wizard shown in Figure 1-4. You can rerun the wizard at any time to change your operation definitions.

The ActivationSpec parameter holds the inbound configuration information. The ActivationSpec and a set of inbound file adapter properties are part of the inbound WSDL file.

The inbound WSDL contains the following information:

<pc:inbound_binding />
  <operation name="Read">
    <jca:operation
      PhysicalDirectory="C:/ora_home/integration/bpm/samples/tutorials/121.FileAdapter/ComplexStructure/inputDir/"
      ActivationSpec="oracle.tip.adapter.file.inbound.FileActivationSpec"
      PhysicalArchiveDirectory="C:/ora_home/integration/bpm/samples/tutorials/121.FileAdapter/ComplexStructure/archiveDir/"
      DeleteFile="true"
      IncludeFiles=".+\.txt"
      PollingFrequency="5"
      MinimumAge="0"
      OpaqueSchema="false" >
    </jca:operation>
    <input>
      <jca:header message="hdr:InboundHeader_msg" part="inboundHeader"/>
    </input>
  </operation>
</binding>

The ActivationSpec parameters are specified in the Adapter Configuration Wizard during design time and appear in the binding element of the inbound WSDL. The inbound file adapter uses the following configuration parameters:

  • PollingFrequency

    This parameter specifies how often to poll a given input directory for new files. The parameter is of type int and is mandatory. The default value is 1.

  • PhysicalDirectory

    This parameter specifies the physical input directory to be polled. The parameter is of type String. The inbound directory where the files appear is mandatory. You must specify the physical directory or logical directory.

  • LogicalDirectory

    This parameter specifies the logical input directory to be polled. The parameter is of type String.

  • PublishSize

    This parameter indicates whether the file contains multiple messages, and how many messages to publish to the BPEL process at a time. The parameter is of type int and is not mandatory. The default value is 1.


    Note:

    Do not enter a negative value for the number of batches in which to publish messages in the adapter service WSDL file. For example, PublishSize="-1". This causes a validation error when you attempt to deploy your process from Oracle JDeveloper. Note that the Adapter Configuration Wizard does not allow you to enter negative values for this parameter.

  • PhysicalArchiveDirectory

    This parameter specifies where to archive successfully processed files. The parameter is of type String and is not mandatory.

  • LogicalArchiveDirectory

    This parameter specifies the logical directory in which to archive successfully processed files. The parameter is of type String and is not mandatory.

  • IncludeFiles

    This parameter specifies the pattern for types of files to pick up during polling. The parameter is of type String and is not mandatory.

  • ExcludeFiles

    This parameter specifies the pattern for types of files to be excluded during polling. The parameter is of type String and is not mandatory.

2.2.1.11 Inbound Header WSDL File

The WSDL file shown in Section 2.2.1.10, "Inbound Service Name WSDL File" includes two attributes that indicate which message and part define the operation headers:

<jca:header message="hdr:InboundHeader_msg" part="inboundHeader"/>

The fileAdapterInboundHeader.wsdl file defines these attributes. This file also provides information such as the name of the file being processed and its directory path. This file is created along with the service name WSDL file and is displayed in the Applications section of Oracle JDeveloper.

<definitions
     name="fileAdapter"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/" 
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/file/"   
     xmlns="http://schemas.xmlsoap.org/wsdl/" >
    <types>
        <schema attributeFormDefault="qualified" elementFormDefault="qualified" 
                targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/"
                xmlns="http://www.w3.org/2001/XMLSchema" 
                xmlns:FILEAPP="http://xmlns.oracle.com/pcbpel/adapter/file/">
          <element name="InboundFileHeaderType">
                <complexType>
                    <sequence>
                        <element name="fileName" type="string"/>
                        <element name="directory" type="string"/>
                    </sequence>
                </complexType>
            </element> 
        </schema>
    </types>
   
    <!-- Header Message --> 
    <message name="InboundHeader_msg"> 
      <part element="tns:InboundFileHeaderType" name="inboundHeader"/> 
   </message> 
</definitions>

Refer to the online help of an invoke activity in Oracle JDeveloperfor more information about header variables. Click Help as shown in the Figure 2-10.

Figure 2-10 Edit Invoke Dialog Box

Description of Figure 2-10 follows
Description of "Figure 2-10 Edit Invoke Dialog Box"

2.2.1.12 Synchronous File Reading Capabilities

The file adapter can also synchronously read a single file using an invoke activity. For reading a file synchronously, you select Synchronous Read File operation as shown in Figure 2-2.

Figure 2-11 Synchronous Read Operation Window

Description of Figure 2-11 follows
Description of "Figure 2-11 Synchronous Read Operation Window"

All the windows of the Adapter Configuration Wizard are similar to the Read File operation except the File Name window shown in Figure 2-12. You can specify the name of the file to be read in the File Name field.

Figure 2-12 File Name Window

Description of Figure 2-12 follows
Description of "Figure 2-12 File Name Window"

2.2.2 File Adapter Write File Concepts

In the outbound direction, the file adapter receives messages from the BPEL process or ESB service and writes the messages to a file in a file system. This section provides an overview of the outbound file writing capabilities of the file adapter. You use the Adapter Configuration Wizard to configure the file adapter for use with a BPEL process or an ESB Service. This creates an outbound WSDL file named after the service name you specify with the Adapter Configuration Wizard. An outbound header file named fileAdapterOutboundheader.wsdl is also created.

This section contains the following topics:

2.2.2.1 Outbound Operation

For outbound operations with the file adapter, you select Write File operation. Figure 2-13 shows this selection.

Figure 2-13 Selecting the Write File Operation

Description of Figure 2-13 follows
Description of "Figure 2-13 Selecting the Write File Operation"

2.2.2.2 Outbound File Directory Creation

For the outbound operation, you can specify the outbound directory, outbound file naming convention to use, and, if necessary, the batch file conventions to use.

The File Configuration Window of the Adapter Configuration Wizard shown in Figure 2-14 enables you to specify the directory for outgoing files and the outbound file naming convention.

Figure 2-14 Adapter Configuration Wizard-Parameters for Outgoing Files

Description of Figure 2-14 follows
Description of "Figure 2-14 Adapter Configuration Wizard-Parameters for Outgoing Files"

The following sections describe the file configuration information to specify:

Specifying Outbound Physical or Logic Directory Paths in Oracle BPEL Process Manager

You can specify outbound directory names as physical or logical paths. Physical paths are values such as c:\outputDir.

If you specify logical parameters, then the generated WSDL file looks as follows for the logical outbound directory name OutputFileDir.

<jca:binding />
  <operation name="Write">
    <jca:operation
      InteractionSpec="oracle.tip.adapter.file.outbound.FileInteractionSpec"
      LogicalDirectory="OutputFileDir"
      FileNamingConvention="po_%SEQ%.xml">
    </jca:operation>
  .....

In the BPEL partner link in the bpel.xml file, you then specify an outbound partner link binding property by using the Property tab of the partner link. This resolves the mapping between the logical directory name and the actual physical directory name.

<?xml version = '1.0' encoding = 'UTF-8'?>
<BPELSuitcase>
  <BPELProcess id="ComplexStructure" src="ComplexStructure.bpel">
    <partnerLinkBindings>
      <partnerLinkBinding name="InboundPL">
        <property name="wsdlLocation">ComplexStructureInbound.wsdl</property>
      </partnerLinkBinding>
    <partnerLinkBinding name="OutboundPL">
      <property name="wsdlLocation">ComplexStructureOutbound.wsdl</property>
      <property name="OutputFileDir">C:/ora_home/integration/bpm/samples/tutorials/ 
121.FileAdapter/ComplexStructure/outputDir/</property> 
  </partnerLinkBinding>
</partnerLinkBindings>
    <activationAgents>
    <activationAgentclassName=
"oracle.tip.adapter.fw.agent.jca.JCAActivationAgent"partnerLink="InboundPL">
    <property name="portType">Read_ptt</property>
   </activationAgent>
  </activationAgents>
 </BPELProcess>
</BPELSuitcase>

Note:

Ensure that you limit the length of outbound file names (the file name, plus the complete directory path) to 200 characters. This is not an exact limit, but rather a recommendation. When an outbound file name is long (for example, 215 characters), a blank file with that name is created in the outbound directory.

Specifying Outbound Physical or Logical Directory Paths in Oracle Enterprise Service Bus

You can specify outbound directory names as physical or logical paths in Oracle Enterprise Service Bus. Physical paths are values such as c:\inputDir.

You can specify the logical names at design time in the File Directories window shown in Figure 2-3 and then provide logical-physical mapping by using the Endpoint properties. For example, WriteFile is an outbound adapter service. You have specified OutDir as the logical directory name at design time. After completing the Adapter Configuration Wizard, when you click the WriteFile_esbsvc file, an outbound file adapter window similar to the one shown in Figure 2-4 is displayed.

Figure 2-15 Sample Outbound File Adapter Window

Description of Figure 2-15 follows
Description of "Figure 2-15 Sample Outbound File Adapter Window"

When you click the plus sign (+) in Endpoint Properties section, the Endpoint Property Chooser dialog box shown in Figure 2-5 is displayed.

Figure 2-16 Endpoint Property Chooser Dialog Box

Description of Figure 2-16 follows
Description of "Figure 2-16 Endpoint Property Chooser Dialog Box"

Select the OutDir property and click OK. Now, you can specify the physical directory name in the Value field as shown in Figure 2-6.

Figure 2-17 Endpoint Properties Section

Description of Figure 2-17 follows
Description of "Figure 2-17 Endpoint Properties Section"

Specifying Dynamic Outbound Directory Name

For outbound operation, you can specify a dynamic outbound directory name. You can use variables to specify dynamic outbound directory names through use of the directory parameter in the fileAdapterOutboundHeader.wsdl as shown in the following example.

<definitions
     name="fileAdapter"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/"
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/file/"
     xmlns="http://schemas.xmlsoap.org/wsdl/" >
    <types>
        <schema attributeFormDefault="qualified" elementFormDefault="qualified"
                targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/"
                xmlns="http://www.w3.org/2001/XMLSchema"
                xmlns:FILEAPP="http://xmlns.oracle.com/pcbpel/adapter/file/">
            <element name="OutboundFileHeaderType">
                <complexType>
                    <sequence>
                        <element name="fileName" type="string"/>
                        <element name="directory" type="string"/>
                    </sequence>
                </complexType>
            </element>
        </schema>
    </types>
    <!-- Header Message -->
    <message name="OutboundHeader_msg">       <part element="tns:OutboundFileHeaderType" name="outboundHeader"/>    </message>
</definitions>

You need to add the directory parameter in the fileAdapterOutboundHeader.wsdl file. The fileAdapterOutboundHeader.wsdl file is read only and cannot be modified in Oracle JDeveloper. So, you need to open the file and modify it separately.

After modifying the fileAdapterOutboundHeader.wsdl file, create a variable of message type OutboundHeader_msg and assign it a value. Perform the following steps for this:

  1. Double-click the invoke activity.

  2. Click the Adapters tab.

  3. Click the Browse Variables icon.

  4. In the Variable Chooser dialog box, click the Create an Object icon.

    Description of file_adptr_icon.gif follows
    Description of the illustration file_adptr_icon.gif

  5. In the Create Variable dialog box shown in Figure 2-18, select Message Type and click the Browse Message Type icon.

    Figure 2-18 Create Variable dialog box

    Description of Figure 2-18 follows
    Description of "Figure 2-18 Create Variable dialog box"

  6. Select OutboundHeader_msg as shown in Figure 2-19 and click OK till you exit the invoke activity dialog box.

    Figure 2-19 Type Chooser Dialog Box

    Description of Figure 2-19 follows
    Description of "Figure 2-19 Type Chooser Dialog Box"

  7. Double-click the assign activity and click the Copy Operation tab.

  8. Click Create and then Copy Operation.

  9. In the Create Copy Operation dialog box, you can either select a variable or an expression. For expression, select Expression from Type and specify the directory name and path as shown in Figure 2-20. The output file will be written to this directory.

    Figure 2-20 Create Copy Operation Dialog Box

    Description of Figure 2-20 follows
    Description of "Figure 2-20 Create Copy Operation Dialog Box"

  10. Click OK till you exit the assign activity dialog box.


Note:

When using dynamic directories, ensure that parameters such as NumberMessages, ElapsedTime, and FileSize are not defined in the outbound adapter service wsdl file. These parameters are not supported with dynamic directories.

Specifying the Outbound File Naming Convention

Specify the naming convention to use for outgoing files. You cannot enter completely static names such as po.txt. This is to ensure the uniqueness of outgoing files names, which prevents files from being inadvertently overwritten. Instead, outgoing file names must be a combination of static and dynamic portions.

The prefix and suffix portions of the file example shown in Figure 2-14 are static (for example, po_ and .xml). The %SEQ% variable of the name is dynamic and can be a sequence number or a time stamp (for example, po_%yyMMddHHmmss%.xml to create a file with a time stamp).

The sequence number is written to a file if the system shuts down unexpectedly. If you choose a name starting with po_, followed by a sequence number and the extension txt as the naming convention of the outgoing files, then you must specify po_%SEQ%.txt.

If you choose a name starting with po_, followed by a time stamp with the pattern yyyy.MM.dd and the extension txt as the naming convention of the outgoing file, then you must specify po_%yyyy.MM.dd%.txt. For example, the outgoing file name can be po_2004.11.29.txt.

You cannot use a regular expression for outbound synchronous reads. In these cases, the exact file name must be known.

A time stamp is specified by date and time pattern strings. Within date and time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as pattern letters representing the components of a date or time string. Text can be quoted using single quotes (') to avoid interpretation. The characters "''" represent a single quote. All other characters are not interpreted.

The Java pattern letters are defined in Table 2-6.

Table 2-6 Java Pattern Letters

Letter Date or Time Component Presentation Examples

G

Era designator

Text

AD

y

Year

Year

1996; 96

M

Month in year

Month

July; Jul; 07

w

Week in year

Number

27

W

Week in month

Number

2

D

Day in year

Number

189

d

Day in month

Number

10

F

Day of week in month

Number

2

E

Day in week

Text

Tuesday; Tue

a

AM/PM marker

Text

PM

H

Hour in day (0-23)

Number

0

k

Hour in day (1-24)

Number

24

K

Hour in AM/PM (0-11)

Number

0

h

Hour in AM/PM (1-12)

Number

12

m

Minute in hour

Number

30

s

Second in minute

Number

55

S

Millisecond

Number

978

z

Time zone

General Time Zone

Pacific Standard Time; PST; GMT-08:00

Z

Time zone

RFC 822 Time Zone

-0800


Different presentations in the pattern are as follows:

  • Text

    For formatting, if the number of pattern letters is four or more, then the full form is used; otherwise, a short or abbreviated form is used if available. For parsing, both forms are accepted, independent of the number of pattern letters.

  • Number

    For formatting, the number of pattern letters is the minimum number of digits, and shorter numbers are zero-padded to this amount. For parsing, the number of pattern letters is ignored unless it is needed to separate two adjacent fields.

  • Year

    For formatting, if the number of pattern letters is two, then the year is truncated to two digits; otherwise, it is interpreted as a number.

For parsing, if the number of pattern letters is more than two, then the year is interpreted literally, regardless of the number of digits. Using the pattern MM/dd/yyyy, 01/11/12 parses to Jan 11, 12 A.D.

For parsing with the abbreviated year pattern (y or yy), the abbreviated year is interpreted relative to some century. The date is adjusted to be within 80 years before and 20 years after the time instance is created. For example, using a pattern of MM/dd/yy and Jan 1, 1997 is created; the string 01/11/12 is interpreted as Jan 11, 2012, while the string 05/04/64 is interpreted as May 4, 1964. During parsing, only strings consisting of exactly two digits are parsed into the default century. Any other numeric string, such as a one-digit string, a three-or-more-digit string, or a two-digit string that is not all digits (for example, -1), is interpreted literally. So 01/02/3 or 01/02/003 is parsed, using the same pattern, as Jan 2, 3 AD. Likewise, 01/02/-3 is parsed as Jan 2, 4 BC.

  • Month

    If the number of pattern letters is 3 or more, then the month is interpreted as text; otherwise, it is interpreted as a number.

  • General time zone

    Time zones are interpreted as text if they have names. For time zones representing a GMT offset value, the following syntax is used:

GMTOffsetTimeZone:
GMT Sign Hours : Minutes
Sign: one of
+ -
Hours:
Digit
Digit Digit
Minutes:
Digit Digit
Digit: one of
0 1 2 3 4 5 6 7 8 9

Hours must be between 0 and 23, and Minutes must be between 00 and 59. The format is locale-independent and digits must be taken from the Basic Latin block of the Unicode standard.

For parsing, RFC 822 time zones are also accepted.

For formatting, the RFC 822 4-digit time zone format is used:

RFC822TimeZone:
Sign TwoDigitHours Minutes
TwoDigitHours:
Digit Digit

TwoDigitHours must be between 00 and 23. Other definitions are the same as for general time zones.

For parsing, general time zones are also accepted.

Specifying a Dynamic Outbound File Name

You can also use variables to specify dynamic outbound file names through use of the OutboundHeader_msg message name in the fileAdapterOutboundHeader.wsdl.

<definitions
     name="fileAdapter"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/"
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/file/"
     xmlns="http://schemas.xmlsoap.org/wsdl/" >
    <types>
        <schema attributeFormDefault="qualified" elementFormDefault="qualified"
                targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/"
                xmlns="http://www.w3.org/2001/XMLSchema"
                xmlns:FILEAPP="http://xmlns.oracle.com/pcbpel/adapter/file/">
            <element name="OutboundFileHeaderType">
                <complexType>
                    <sequence>
                        <element name="fileName" type="string"/>
                    </sequence>
                </complexType>
            </element>
        </schema>
    </types>
    <!-- Header Message -->
    <message name="OutboundHeader_msg">
      <part element="tns:OutboundFileHeaderType" name="outboundHeader"/>
   </message>
</definitions> 

Create a variable of message type OutboundHeader_msg, assign it a value, and use it in the Adapter tab of an invoke activity. For example:

<variables>
      <variable name="fileHeader" messageType="file:OutboundHeader_msg"/>
    [..]

    <assign>
      <copy>
        <from>*testfile.txt*</from>
        <to variable="fileHeader" part="outboundHeader"
            query="/file:OutboundFileHeaderType/file:fileName"/>
      </copy>
    </assign>     <invoke name="FileSend" partnerLink="outboundPL"
             portType="out:FileWrite_PortType" operation="Write"
             inputVariable="payload"
    bpelx:inputHeaderVariable="fileHeader"/> 

See the online Help that is included with the Adapter tab in JDeveloper BPEL Designer for more information.

Batching Multiple Outbound Messages

In the simplest scenario, you specify writing a single file to a single message. You can also specify the outbound method for batch file writing. This enables you to specify the number of messages in one batch file to publish. The following batch file settings are provided in the File Configuration window shown in Figure 2-14:

  • Number of messages equals

    Specify a value that, when equaled, causes a new outgoing file to be created.

  • Elapsed time exceeds

    Specify a time that, when equaled, causes a new outgoing file to be created.

  • File size exceeds

    Specify a file size that, when equaled, causes a new outgoing file to be created. For example, assume that you specify a value of three for the number of messages received and a value of 1 MB for the file size. When you receive two messages that when combined equal or exceed 1 MB, or three messages that are less than 1 MB, an output file is created.

If the file adapter encounters some problem during batching, then it starts batching at the point at which it left off on recovery.

Purging Files

You cannot purge control files specific to a BPEL process. For example, you cannot start anew with sequence number 1 for outbound files or reprocess a (debatching) file with errors from the beginning instead of from the last published message.

2.2.2.3 Native Data Translation

The next Adapter Configuration Wizard window that appears is the Messages window shown in Figure 2-21. This window enables you to select the XSD schema file for translation.

Figure 2-21 Specifying the Schema

Description of Figure 2-21 follows
Description of "Figure 2-21 Specifying the Schema"

As with specifying the schema for the inbound direction, you can perform the following tasks in this window:

  • Specify if native format translation is not required

  • Select the XSD schema file for translation

  • Start the Native Format Builder Wizard to create an XSD file from file formats such as CSV, fixed-length, DTD, and COBOL Copybook

See Section 2.2.1.7, "Native Data Translation" for more information about the Messages window.

2.2.2.4 Outbound Error Handling

As with inbound files, the file adapter guarantees once-only delivery of outbound files. This includes guaranteed delivery of large files through FTP. If your system shuts down unexpectedly, then the write functionality of the file adapter on restart has the information to proceed from where it left off in the previous run, thereby avoiding duplicate messages. If the target host is unavailable, the file adapter supports retrying to send documents. For example, if the directory to which it is trying to write is read-only, then the file adapter tries to write again.

For Oracle BPEL Process Manager, you must configure two partner link retry properties from the Property tab of the partner link (updates the bpel.xml file):

<partnerLinkBinding name="WriteFile">
  <property name="wsdlLocation">WriteFile.wsdl</property>
  <property name="retryMaxCount">10</property>
  <property name="retryInterval">60</property>

The write operation eventually succeeds (if the problem is resolved in a timely fashion). If the problem is not resolved within the retry period, then a binding fault is sent back to the BPEL process.

For Oracle Enterprise Service Bus, you can configure the following endpoint properties:

  • OutboundRetryCount

  • OutboundRetryInterval

  • OutboundRetryEnabled

These properties can be configured through the esb_config.ini file, through ESB Console, or through the endpoint properties section of an outbound adapter service as shown in Figure 2-6. Following are the default values as specified in the esb_config.ini file:

OutboundRetryCount = 3
OutboundRetryInterval = 5
OutboundRetryEnabled = true

2.2.2.5 Outbound Service Name WSDL File

When you complete configuration of the file adapter with the Adapter Configuration Wizard, a WSDL file is generated for the outbound direction. The file is named after the service name you specified on the Service Name window of the Adapter Configuration Wizard shown in Figure 1-4. You can rerun the wizard at any time to change your operation definitions.

The InteractionSpec parameters in the WSDL file contain the outbound configuration information that you specified with the Adapter Configuration Wizard during design time. The InteractionSpec parameters and a set of outbound file adapter properties are part of the outbound WSDL file. The outbound WSDL includes the following information:

<jca:binding />
  <operation name="Write">
    <jca:operation
      PhysicalDirectory="E:\Customer\out"
      InteractionSpec="oracle.tip.adapter.file.outbound.FileInteractionSpec"
      FileNamingConvention="po_%SEQ%.xml"
      NumberMessages="1"
      ElapsedTime="60"
      FileSize="1000000"
      OpaqueSchema="false" >
    </jca:operation>
    <input>
      <jca:header message="hdr:OutboundHeader_msg" part="outboundHeader"/>
    </input>
  </operation>
</binding>

The outbound file adapter uses the following configuration parameters:

  • PhysicalDirectory

    This parameter specifies the physical directory in which to write output files. The parameter is of type String. The outbound directory where the outgoing files are written is mandatory. You must specify the physical directory or logical directory.

  • LogicalDirectory

    This parameter specifies the logical directory in which to write output files. The parameter is of type String.

  • NumberMessages

    This parameter is used for outbound batching. The outgoing file is created when the number of messages condition is met. The parameter is of type String and is not mandatory. The default value is 1.

  • ElapsedTime

    This parameter is used for outbound batching. When the time specified elapses, the outgoing file is created. The parameter is of type String and is not mandatory. The default value is 1.

  • FileSize

    This parameter is used for outbound batching. The outgoing file is created when the file size condition is met. The parameter is of type String and is not mandatory. The default value is 1000 KB.

  • FileNamingConvention

    This parameter is for the naming convention for the outbound write operation file. The parameter is of type String and is mandatory.

2.2.2.6 Outbound Header WSDL File

The WSDL file shown in Section 2.2.2.5, "Outbound Service Name WSDL File" includes two attributes that indicate which message and part define the operation headers:

<jca:header message="hdr:OutboundHeader_msg" part="outboundHeader"/>

The fileAdapterOutboundHeader.wsdl file defines these attributes, as well as information about the outbound file name. This file is created along with the service name WSDL file, and is displayed in the Applications navigator of Oracle JDeveloper.

<definitions
     name="fileAdapter"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/" 
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/file/"   
     xmlns="http://schemas.xmlsoap.org/wsdl/" >
    <types>        <schema attributeFormDefault="qualified" elementFormDefault="qualified" 
                targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/"
                xmlns="http://www.w3.org/2001/XMLSchema" 
                xmlns:FILEAPP="http://xmlns.oracle.com/pcbpel/adapter/file/">
            <element name="OutboundFileHeaderType">
                <complexType>
                    <sequence>
                        <element name="fileName" type="string"/>
                    </sequence>
                </complexType>
            </element>  
        </schema>
    </types>
   
    <!-- Header Message --> 
    <message name="OutboundHeader_msg"> 
      <part element="tns:OutboundFileHeaderType" name="outboundHeader"/> 
   </message> 
</definitions>

2.2.3 FTP Adapter for Get File Concepts

In the inbound direction, the FTP adapter works the same way as the Read File operations of the file adapter in that it polls and gets files from a file system for processing. The major difference is that the FTP adapter is used for remote file exchanges. Because of this, the Adapter Configuration Wizard asks for connection information to an FTP server to be used later, as shown in Figure 2-22.

Figure 2-22 Specifying FTP Server Connection Information

Description of Figure 2-22 follows
Description of "Figure 2-22 Specifying FTP Server Connection Information"

To create the FTP server connection that you specify in Figure 2-22, you must edit the oc4j-ra.xml deployment descriptor file for adapter instance JNDI name and FTP server connection information. The location of the oc4j-ra.xml file depends on the installation type. Table 2-7 lists the installation type and corresponding oc4j-ra.xml file location.

Table 2-7 oc4j-ra.xml File Location

Installation Type File Location

SOA Basic Installation

Oracle_Home\j2ee\home\application-deployments\default\FtpAdapter

Oracle Enterprise Service Bus on Oracle Application Server Middle tier

Oracle_Home\j2ee\homemid\application-deployments\default\FtpAdapter

Oracle BPEL Process Manager on Oracle Application Server Middle tier

Oracle_Home\j2ee\homemid\application-deployments\default\FtpAdapter


A sample of oc4j-ra.xml is as follows:

<?xml version="1.0"?>
<!DOCTYPE oc4j-connector-factories PUBLIC "-//Oracle//DTD Oracle Connector
  9.04//EN" "http://xmlns.oracle.com/ias/dtds/oc4j-connector-factories-9_04.dtd">

<oc4j-connector-factories>
    <connector-factory location="eis/Ftp/FtpAdapter" connector-name="FTP Adapter">
        <config-property name="host" value="stada55.us.oracle.com"/>
        <config-property name="port" value="21"/>
        <config-property name="username" value="anonymous"/>
        <config-property name="password" value="password"/>
    </connector-factory>
</oc4j-connector-factories>

The adapter instance JNDI name is specified as eis/Ftp/FtpAdapter and connection information such as host, port, username, and password are provided as configuration properties.


Note:

The FTP adapter does not support the FTP commands RESTART and RECOVERY during the transfer of large files.

After logging in, you select the Get File (read) operation and the type of file to deliver. Figure 2-23 shows this selection.

Figure 2-23 Selecting the Get File Operation

Description of Figure 2-23 follows
Description of "Figure 2-23 Selecting the Get File Operation"

For inbound and outbound file transfers, the ra.xml file includes a serverType property. The location of the ra.xml file depends on the installation type. Table 2-8 lists the installation type and corresponding ra.xml file location.

Table 2-8 ra.xml File Location

Installation Type File Location

SOA Basic Installation

Oracle_Home\j2ee\home\connectors\FtpAdapter\FtpAdapter\META-INF

Oracle Enterprise Service Bus on Oracle Application Server Middle tier

Oracle_Home\j2ee\homemid\connectors\FtpAdapter\FtpAdapter\META-INF

Oracle BPEL Process Manager on Oracle Application Server Middle tier

Oracle_Home\j2ee\homemid\connectors\FtpAdapter\FtpAdapter\META-INF


The serverType property is automatically used to determine line separators when you transfer data. You can specify unix, win, or mac as property values. These values represent the operating system on which the FTP server is running. By default, the serverType property contains unix.

<config-property-name>serverType</config-property-name>
<config-property-type>java.lang.String</config-property-type> 
<config-property-value>unix</config-property-value>

When you specify mac as the value, \r is used as line separator. For unix, \n is used and for win, \r\n is used.

From this point onward, the windows of the Adapter Configuration Wizard for the Get File operation are the same as those for the Read File operation of the FTP adapter. Table 2-9 lists the windows that are displayed and provides references to sections that describe their functionality.

Table 2-9 Adapter Configuration Wizard Windows for Get File Operation

Window See Section...

File Directories (Figure 2-3)

Section 2.2.1.2, "Inbound File Directory Specifications"


File Filtering (Figure 2-7)

Section 2.2.1.3, "File Matching and Batch Processing"


File Polling (Figure 2-8)

Section 2.2.1.4, "File Polling"


Messages (Figure 2-9)

Section 2.2.1.7, "Native Data Translation"



An additional Adapter Configuration Wizard window is also available for advanced users. This window is shown in Figure 2-24 and appears only after you make either or both of the following selections on the File Polling window shown in Figure 2-8:

  • Do not select the Delete Files After Successful Retrieval check box.

  • Set the value of the Minimum File Age field to a value greater than 0.

Figure 2-24 File Modification Time

Description of Figure 2-24 follows
Description of "Figure 2-24 File Modification Time"

This window enables you to specify one of the following methods for obtaining the modification time of files on the remote FTP server:

  • File System

    This option enables you to obtain the date/time format of the file modification time with the file system listing command. However, this option is rarely used and is not supported by all FTP servers. See your FTP server documentation to determine whether your server supports the file system listing command, which command-line syntax to use, and how to interpret the output.

    For example, if the file system listing command quote mdtm filename is supported and returns the following information:

    213 20050602102633
    
    

    specify the start index, end index, and date/time format of the file modification time in the Data/Time Format field as a single value separated by commas (for example, 4,18,yyyyMMddHHmmss).

    Where:

    • 4 is the start index of the file modification time.

    • 18 is the end index of the file modification time.

    • yyyyMMddHHmmss is the data/time format of the file modification time obtained with the quote mdtm filename command.

    The resulting service_name.wsdl file includes the following parameters and values:

    FileModificationTime="FileSystem"
    ModificationTimeFormat="4,18,yyyyMMddHHmmss"
    
    

    To handle the time zone issue, you must also be aware of the time stamp difference. The time zone of the FTP server is determined by using the Windows date/time properties (for example, by double-clicking the time being displayed in the Windows task bar). You must then convert the time difference between the FTP server and the system on which the FTP adapter is running to milliseconds and add the value as a property in the bpel.xml file:

    <activationAgents> 
      <activationAgent ...> 
        <property name="timestampOffset">2592000000</property>
    
    
  • Directory Listing

    This option enables you to obtain the date/time format from the file modification time with the FTP directory listing command. For example, if the directory listing command (ls -l) returns the following information:

    12-27-04  07:44AM                 2829 NativeData2.txt
    
    

    specify the start index, end index, and date/time format of the file modification time as a single value separated by commas in either the Old File Date/Time Format field or the Recent File Date/Time Format field (for example, 0,17, MM-dd-yy hh:mma).

    Where:

    • 0 is the start index of the file modification time.

    • 17 is the end index of the file modification time.

    • MM-dd-yy hh:mma is the date/time format of the file modification time obtained with the ls -l command. For this example, the value is entered in the Recent File Date/Time Format field. This field indicates that the format is obtained from the most recent file adhering to the naming convention, whereas the Old File Date/Time Format field obtains the format from the oldest file.

    The resulting service_name.wsdl file includes the following parameters and values:

    FileModificationTime="DirListing"
    ModificationTimeFormat="0,17, MM-dd-yy hh:mma"
    
    

    To handle the time zone issue, you must also be aware of the time stamp difference. The time zone of the FTP server is determined by using the Windows date/time properties (for example, by double-clicking the time being displayed in the Windows task bar). You must then convert the time difference between the FTP server and the system on which the FTP adapter is running to milliseconds and add the value as a property in the bpel.xml file:

    <activationAgents> 
      <activationAgent ...> 
        <property name="timestampOffset">2592000000</property>
    
    
  • File Name Substring

    This option enables you to obtain the modification time from the file name. For example, if the name of the file is fixedLength_20050324.txt, you can specify the following values:

    • The start index in the Substring Begin Index field (for example, 12).

    • The end index in the End Index field (for example, 20).

    • The date and time format in the Date/Time Format field conforming to the Java SimpleDateFormat to indicate the file modification time in the file name (for example, yyyyMMdd).

    The resulting service_name.wsdl file includes the following parameters and values:

    FileModificationTime="Filename"
    FileNameSubstringBegin="12"
    FileNameSubstringEnd="20"
    ModificationTimeFormat="yyyyMMdd"
    
    

After the completion of Adapter Configuration Wizard, configuration files are created in the Applications section of Oracle JDeveloper.

The inbound service WSDL file name that is created is also similar to that of the file adapter. The main differences include the operation type and the file type.

<pc:inbound_binding />
   <operation name="Get">
<jca:operation
   FileType="binary"

The inbound header WSDL file named ftpAdapterInboundHeader.wsdl looks as follows:

<definitions
     name="fileAdapter"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/ftp/"
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/ftp/"  
     xmlns="http://schemas.xmlsoap.org/wsdl/" >
    <types>        <schema attributeFormDefault="qualified" elementFormDefault="qualified"
                targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/ftp/"
                xmlns="http://www.w3.org/2001/XMLSchema"
                xmlns:FTPAPP="http://xmlns.oracle.com/pcbpel/adapter/ftp/">
            <element name="InboundFTPHeaderType">
                <complexType>
                    <sequence>
                        <element name="fileName" type="string"/>
                     </sequence>
                </complexType>
            </element>
        </schema>
    </types>
  
    <!-- Header Message -->
    <message name="InboundHeader_msg">
      <part element="tns:InboundFTPHeaderType" name="inboundHeader"/>
   </message>
</definitions>

See Section 2.2.1.8, "Error Handling" and Section 2.2.1.9, "Guaranteed Delivery and Recovery from Server Failures" for more information about error handling and guaranteed delivery capabilities.

2.2.4 FTP Adapter for Put File Concepts

In the outbound direction, the FTP adapter works the same as the Write File operations of the file adapter. The FTP adapter receives messages from a BPEL process or ESB service and writes the messages in a file to a file system (in this case, remote). Because of this, the Adapter Configuration Wizard prompts you to connect to the FTP server with the adapter instance JNDI name, as shown in Figure 2-22.

After logging in, you select the Put File (write) operation and the type of file to deliver. Figure 2-25 shows this selection.

Figure 2-25 Selecting the Put File Operation

Description of Figure 2-25 follows
Description of "Figure 2-25 Selecting the Put File Operation"

From this point onward, the windows of the Adapter Configuration Wizard window for the Put File operation are the same as those for the Write File operation of the file adapter. Table 2-10 lists the windows that display and provides references to sections that describe their functionality.

Table 2-10 Adapter Configuration Wizard Windows for Put File Operation

Window See Section...

File Configuration (Figure 2-14)

Section 2.2.2.2, "Outbound File Directory Creation"


Messages (Figure 2-21)

Section 2.2.2.3, "Native Data Translation"



After the completion of the Adapter Configuration Wizard, configuration files are created in the Applications section of Oracle JDeveloper.

The outbound service WSDL file name that is created is also similar to that of the file adapter. The main differences include the operation type and the file type.

<pc:inbound_binding />
   <operation name="Put">
<jca:operation
   FileType="binary"

The outbound header WSDL file named ftpAdapterOutboundHeader.wsdl looks as follows:

<definitions
     name="fileAdapter"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/ftp/"
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/ftp/"  
     xmlns="http://schemas.xmlsoap.org/wsdl/" >
    <types>
        <schema attributeFormDefault="qualified" elementFormDefault="qualified"
                targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/ftp/"
                xmlns="http://www.w3.org/2001/XMLSchema"
                xmlns:FTPAPP="http://xmlns.oracle.com/pcbpel/adapter/ftp/">
            <element name="OutboundFTPHeaderType">
                <complexType>
                    <sequence>
                        <element name="fileName" type="string"/>
                    </sequence>
                </complexType>
            </element>
        </schema>
    </types>
  
    <!-- Header Message -->
    <message name="OutboundHeader_msg">
      <part element="tns:OutboundFTPHeaderType" name="outboundHeader"/>
   </message>
</definitions>

See Section 2.2.2.4, "Outbound Error Handling" for more information about error handling capabilities.

2.3 Using Secure FTP with the FTP Adapter

The FTP adapter supports the use of the secure FTP feature on Solaris. This section provides an overview of secure FTP functionality and describes how to install and configure this feature.

This section contains the following tasks:


Note:

The FTP adapter supports the secure FTP feature on Solaris only.

2.3.1 Secure FTP Overview

In environments in which sensitive data is transferred to remote servers (for example, sending credit card information to HTTP servers), the issue of security is very important. Security in these cases primarily refers to two requirements:

  • Trust in the remote server with which you are exchanging data

  • Protection from third parties trying to intercept the data

Secure socket layer (SSL) certificates and encryption focus on satisfying these two security requirements. When SSL is used in the context of FTP, the resulting security mechanism is known as FTPS (or FTP over SSL).

To gain the trust of clients in SSL environments, servers obtain certificates (typically, X.509 certificates) from recognized certificate authorities. When you set up the FTP server vsftpd in Section 2.3.3, "Installing and Configuring vsftpd", you use openSSL to create a certificate for the server. Every client trusts a few parties to begin. If the server is one of these trusted parties, or if the server's certificate was issued by one of these parties, you have established trust, even indirectly. For example, if the server's certificate was issued by authority A, which has a certificate issued by authority B, and the client trusts B, that is good enough. For the setup shown in Figure 2-7, the server's certificate is directly imported into the client's certificate store (or Oracle Wallet) as a trusted certificate.

Figure 2-26 Establishing Trust

Description of Figure 2-26 follows
Description of "Figure 2-26 Establishing Trust"

You make the data being transferred immune to spying by encrypting it before sending it and decrypting it after receiving it. Symmetric encryption (using the same key to encrypt and decrypt data) is much faster for large amounts of data than the public key and private key approach. Symmetric encryption is the approach used by FTPS. However, before the client and server can use the same key to encrypt and decrypt data, they must agree on a common key. This is typically done by the client performing the following tasks:

  • Generating a session key (to be used to encrypt and decrypt data)

  • Encrypting this session key using the server's public key that is part of the server's certificate

  • Sending the key to the server

The server decrypts this session key using its private key and subsequently uses it to encrypt file data before sending it to the client.

The remaining subsections describe how to install and configure secure FTP.

2.3.2 Installing and Configuring OpenSSL

OpenSSL is an open source implementation of the SSL protocol. OpenSSL implements basic cryptographic functions and provides utility functions. Install and configure OpenSSL on the Solaris host to use as the FTP server.

  1. Go to the following URL:

    http://www.openssl.org/source
    
    
  2. Locate openssl-0.9.7g.tar.gz in the list of available files. For example:

    3132217 Apr 11 17:21:51 2005 openssl-0.9.7g.tar.gz (MD5) (PGP sign)
    
    
  3. Download the following files:

    • openssl-0.9.7g.tar.gz

    • openssl-0.9.7g.tar.gz.md5 (under the MD5 link)

    • openssl-0.9.7g.tar.gz.asc (under the PGP sign link

  4. Unzip the following file using gunzip.

    gunzip openssl-0.9.7g.tar.gz
    
    
  5. Untar the following file:

    tar xvf openssl-0.9.7g.tar
    
    
  6. Change directories to the following location:

    cd openssl-0.9.7g
    
    
  7. Run the following command:

    ./config --prefix=/usr --openssldir=/usr/local/openssl
    
    
  8. Change to the Bourne shell (if not already using it):

    sh
    
    
  9. Configure and export the PATH:

    PATH=${PATH}:/usr/ccs/bin; export PATH 
    
    
  10. Run the following command:

    make
    
    
  11. Exit the Bourne shell:

    exit
    
    
  12. Run the following command:

    make test
    
    
  13. Log in as the super user:

    msu
    
    
  14. Enter the password when prompted.

  15. Run the following command:

    make install
    

2.3.3 Installing and Configuring vsftpd

The vsftpd server is a secure and fast FTP server for UNIX systems. Install and configure vsftpd on the Solaris host to use as the FTP server.

  1. Go to the following location:

    ftp://vsftpd.beasts.org/users/cevans/
    
    
  2. Download vsftpd-2.0.3 (You need the tar and signature file (.asc file)). For example:

    [BINARY]     vsftpd-2.0.3.tar.gz. . . . . . . . . . .    [Mar 19 21:26]    149K
    [FILE]       vsftpd-2.0.3.tar.gz.asc. . . . . . . . .    [Mar 19 21:26]    189B
    
    
  3. Unzip the following file using gunzip.

    gunzip vsftpd-2.0.3.tar.gz
    
    
  4. Unzip the tar file:

    tar xvf vsftpd-2.0.3.tar
    
    
  5. Change directories to the following location:

    cd vsftpd-2.0.3
    
    
  6. Make the following change in the builddefs.h file:

    #undef VSF_BUILD_SSL
    
    

    to

    #define VSF_BUILD_SSL
    
    
  7. Log in as the super user:

    msu
    
    
  8. Enter the password when prompted.

  9. Create a file named vsftpd.conf with the following settings in the /etc directory:

    # Standalone mode
    listen=YES
    max_clients=200
    max_per_ip=4
    # Access rights
    anonymous_enable=YES
    #chroot_local_user=YES
    #userlist_enable=YES
    ftp_username=ftp
    local_enable=YES
    write_enable=YES
    anon_upload_enable=YES
    anon_mkdir_write_enable=YES
    anon_other_write_enable=YES
    chown_uploads=YES
    chown_username=ftp
    # Security
    anon_world_readable_only=NO
    allow_anon_ssl=YES
    ssl_enable=YES
    connect_from_port_20=YES
    hide_ids=YES
    pasv_min_port=50000
    pasv_max_port=60000
    # Features
    ftpd_banner="Welcome to the FTP Service"
    xferlog_enable=YES
    ls_recurse_enable=NO
    ascii_download_enable=NO
    async_abor_enable=YES
    # Performance
    one_process_model=NO
    idle_session_timeout=120
    data_connection_timeout=300
    accept_timeout=60
    connect_timeout=60
    anon_max_rate=50000
    
    

    Note:

    Copies of the vsftpd.conf file appear in several locations in the vsftpd-2.0.3 directory structure. If you use one of those files to create the vsftpd.conf file in the /etc directory, then ensure that it only includes the parameters and settings described in Step 9.

  10. Run the following commands:

    mkdir /var/ftp
    useradd -d /var/ftp ftp
    chown root /var/ftp
    chmod og-w /var/ftp 
    mkdir /usr/share/empty
    mkdir /usr/share/ssl 
    mkdir /usr/share/ssl/certs 
    
    
  11. Run the following command:

    openssl req -x509 -nodes -newkey rsa:1024 -keyout /usr/share/ssl/certs/vsftpd.pem -out /usr/share/ssl/certs/vsftpd.pem
    
    
  12. Run the vsftpd daemon from the vsftpd-2.0.3 directory:

    ./vsftpd
    

2.3.4 Creating an Oracle Wallet

Oracle Wallet Manager is an application for managing and editing security credentials in Oracle wallets. A wallet is a password-protected container that stores authentication and signing credentials, including private keys, certificates, and trusted certificates, all of which are used by SSL for strong authentication.

  1. Create a new wallet in Oracle Wallet Manager.

  2. Import vsftpd.pem from Step 11 of Section 2.3.3, "Installing and Configuring vsftpd" as a trusted certificate in this wallet.

  3. Save this wallet in PKCS # 12 (.p12) format.

See the Oracle Application Server Administrator's Guide for details about using Oracle Wallet Manager.

2.3.5 Setting Up the FTP Adapter

Perform the following tasks to set up the FTP adapter:

  1. On your Solaris host, run the following commands:

    mkdir /var/ftp/inDir 
    mkdir /var/ftp/outDir 
    chmod 777 /var/ftp/inDir /var/ftp/outDir
    
    
  2. Specify the FTP connection parameters in the FTP adapter oc4j-ra.xml file. The location of this file is based on the installation type you selected. Refer to Table 2-7 for information about location of the oc4j-ra.xml file.

    A sample oc4j-ra.xml is as follows:

    <connector-factory location="eis/Ftp/FtpAdapter" connector-name="FTP Adapter">
      <config-property name="host" value="usunnbf29.us.oracle.com"/>
      <config-property name="port" value="21"/> 
      <config-property name="username" value="ftp"/> 
      <config-property name="password" value="password"/>
      <config-property name="useFtps" value="true"/> 
      <config-property name="walletLocation" value="D:\wallet\ewallet.p12"/>
      <config-property name="walletPassword" value="welcome1"/> 
      <config-property name="channelMask" value="both"/> 
      <config-property name="securePort" value="990"/>
    </connector-factory>
    
    
    Where... Is...
    useFtps Set to True. This setting is required to use FTP over SSL. The default is False.
    walletLocation The location of the wallet created in Section 2.3.4, "Creating an Oracle Wallet"
    walletPassword The password of the wallet
    channelMask The type of channel: control channel or data channel. Possible values are both, control, data, or none. The default is both.
    securePort The port for FTP over SSL. The default is 990.

  3. Restart Oracle BPEL Server after changing the oc4j-ra.xml file.

    You have now installed and configured secure FTP and are ready to use this feature with the FTP adapter.

2.4 Using SFTP with the FTP Adapter

SSH file transfer protocol (SFTP) is a network protocol that enables secure file transfer over the network. The FTP adapter supports the use of the SFTP feature on Windows and Linux. This section provides an overview of SFTP functionality and describes how to install and configure this feature.

This section contains the following tasks:

2.4.1 SFTP Overview

SFTP is the network protocol that enables clients to securely transfer files over the underlying SSH transport. SFTP is not similar to FTP over SSH or File Transfer Protocol (FTP). Figure 2-27 displays the communication process between an SSH client and an SSH server.

Figure 2-27 SFTP Communication

Description of Figure 2-27 follows
Description of "Figure 2-27 SFTP Communication"

SFTP has the following features:

2.4.1.1 Encryption

The SSH protocol uses public key cryptography for encryption. The following list explains how the data is encrypted:

  1. The SSH subsystem uses one of the symmetric key ciphers such as Data Encryption Standard (DES) or Blowfish to generate a session key. The SSH protocol currently uses the Diffie-Hellman Key Exchange Algorithm to derive the symmetric key for the session.

  2. The data is encrypted using the session key

  3. The session key is encrypted using the recipient's public key. Because the recipient already has the private key, it can decrypt the message using its preferred PKI algorithm such as Rivest-Shamir-Adleman (RSA) or Digital Signature Algorithm (DSA).

2.4.1.2 Authentication

The SSH protocol inherently supports password authentication by encrypting passwords or session keys as they are transferred over the network. In addition, SSH protocol uses a mechanism known as 'known hosts' to prevent threats such as IP Spoofing. By using this mechanism, both the client and the server have to prove their identity to each other before any kind of communication exchange.

2.4.1.3 Integrity

The SSH protocol makes use of widely trusted bulk hashing algorithms such as Message Digest Algorithm 5 (MD5) or Secure Hash Algorithm (SHA-1) to prevent insertion attacks. Implementation of data integrity checksum by using the algorithms mentioned in Section 2.4.1.1, "Encryption", prevents deliberate tampering of data during transmission.

2.4.1.4 Data Compression

The SSH protocol supports zlib, an open-source cross-platform algorithm for data-compression. SSH uses zlib to compress in-flight data in order to reduce network bandwidth.

2.4.2 Install and Configure OpenSSH for Windows

OpenSSH for Windows is the free implementation of SSH protocol on Windows. Perform the following steps to install and configure OpenSSH on Windows XP:

  1. Login as a user with Administrator privileges.

  2. Download the setup.exe from the following location:

    http://www.cygwin.com
    
    
  3. Run setup.exe. The Cygwin Net Release Setup window is displayed.

  4. Click Next. The Choose Installation type window is displayed.

  5. Select Install from Internet as the download source and click Next. The Choose Installation Directory window is displayed.

  6. Leave the Root Directory as C:\cygwin. Also, keep the default options for the Install For and the Default Text File Type fields.

  7. Click Next. The Select Local Package Directory window is displayed.

  8. Click Browse and select C:\cygwin as the local package directory.

  9. Click Next. The Select Connection Type window is displayed.

  10. Select a setting for Internet connection and click Next. The Choose Download Site(s) window is displayed.

  11. Select a site from the Available Download Sites list and click Next. The Select Packages window is displayed.

  12. Click View to see the complete list of packages available for installation.

  13. Select openssh if it is not selected by default.

  14. Select the Binaries box for openssh.

  15. Click Next to start the installation.

  16. On Windows XP desktop, right -lick My Computer and select Properties.

  17. Click the Advanced tab and click Environment Variables.

  18. Click New and enter CYGWIN in the Variable Name field and ntsec in the Variable Value field.

  19. Add C:\cygwin\bin to the system path.

  20. Open the cygwin window.

  21. Type ssh-host-config.

  22. You will be prompted with following questions:

    1. Shall privilege separation be used? (yes/no)

      Enter yes.

    2. Shall this script create a local user 'sshd' on this machine?

      Enter yes.

    3. Do you want to install sshd as service?

      (Say "no" if it's already installed as service) (yes/no)

      Enter yes.

    4. Which value should the environment variable CYGWIN have when sshd starts? It's recommended to set at least "ntsec" to be able to change user context without password. Default is "binmode ntsec tty".

      Enter ntsec.

  23. Type net start sshd to start the sshd service.

  24. Run the following command in the cygwin window to replicate the Windows local user accounts to cygwin:

    mkpasswd --local > /etc/passwd
    mkgroup --local > /etc/group
    
    
  25. To test the setup, type ssh localhost in the cygwin window.

2.4.3 Set up the FTP Adapter for SFTP

To use the SFTP functionality, you need to modify the oc4j-ra.xml file. Refer to Table 2-7 for information about location of the oc4j-ra.xml file.

Table 2-11 lists the parameters for which you need to specify a value in the oc4j-ra.xml file. The values of these parameters depend on the type of authentication and the location of OpenSSH.

Table 2-11 SFTP Parameters

Parameter Description Example

useSftp

Specify true.

Mandatory: Yes

Default value: false

<config-property name="useSftp" value="false"/>

authenticationType

Specify PASSWORD for password-based authentication or PUBLICKEY for public key authentication.

For Password-based authentication, the user name and password specified in the oc4j-ra.xml file are used. Ensure that there is a Windows user with the same name and password as specified in the oc4j-ra.xml file. In addition, the user should have administrative privileges.

For Public key authentication, the privateKeyFile parameter must be set to the location of the private key file.

Mandatory: Yes

<config-property name="authenticationType" value="password"/>

preferredKey ExchangeAlgorithm

Specify diffie-hellman-group1-sha1 or diffie-hellman-group-exchange-sha1.

This is an optional parameter where the user can select the default key exchange protocol for negotiating the session key for encrypting the message.

Mandatory: No

Default value: diffie-hellman-group1-sha1

<config-property name="preferredKeyExchangeAlgorithm" value="diffie-hellman-group1-sha1"/>

preferred CompressionAlgorithm

Specify none or zlib.

This parameter enables the user to choose whether in-flight data should be compressed or not.

Mandatory: No

<config-property name="preferredCompressionAlgorithm" value="none"/>

preferred DataIntegrityAlgorithm

Specify hmac-md5 or hmac-sha1.

This parameter enables the user to select the bulk-hashing algorithm for data integrity checks.

Mandatory: No

Default value: hmac-md5

<config-property name="preferredDataIntegrityAlgorithm" value="hmac-md5"/>

preferredPKIAlgorithm

Specify ssh-rsa or ssh-dsa.

This parameter enables the user to configure the asymmetric cipher for the communication.

Mandatory: No

Default value: ssh-rsa

<config-property name="preferredPKIAlgorithm" value="ssh-rsa"/>

privateKeyFile

Specify the path to the private key file. This is required if the authenticationType parameter is set to PUBLICKEY.

Mandatory: No

<config-property name="privateKeyFile" value=""/>

preferredCipherSuite

Specify one of the following ciphers:

  • twofish192-cbc

  • cast128-cbc

  • twofish256-cbc

  • aes128-cbc

  • twofish128-cbc

  • 3des-cbc

  • blowfish-cbc

  • aes256-cbc

  • aes192-cbc

Mandatory: No

Default value: blowfish-cbc

<config-property name="preferredCipherSuite" value="blowfish-cbc"/>

transportProvider

Specify socket or HTTP.

Specify socket if the SSH server is inside the firewall. Specify HTTP if the SSH server is outside the firewall or the server is exposed through a HTTP server.

If you select HTTP, then you must provide values for the following parameters:

  • proxyHost

  • proxyPort

  • proxyUser

  • proxyPassword

  • useProxy

Mandatory: Yes

<config-property name="transportProvider" value="socket"/>


2.4.3.1 Configuring the FTP Adapter for Password Authentication

Perform the following steps to set up the FTP adapter for password authentication:

  1. In the oc4j-ra.xml file, specify the values of the parameters listed in Table 2-11. Ensure that the authenticationType parameter is set to password.

  2. Restart the server after modifying the oc4j-ra.xml file.

A sample oc4j-ra.xml file with password authentication parameters is shown in the following example:

<config-property name="useSftp" value="true"/>
<config-property name="authenticationType" value="password"/>
<config-property name="preferredKeyExchangeAlgorithm" value="diffie-hellman-group1-sha1"/>
<config-property name="preferredCompressionAlgorithm" value="none"/>
<config-property name="preferredDataIntegrityAlgorithm" value="hmac-md5"/>
<config-property name="preferredPKIAlgorithm" value="ssh-rsa"/>
<config-property name="privateKeyFile" value=""/>
<config-property name="preferredCipherSuite" value="blowfish-cbc"/>
<config-property name="transportProvider" value="socket"/>

2.4.3.2 Configuring the FTP Adapter for Public Key Authentication

For public key authentication, you first need to configure OpenSSH and then set up the FTP adapter. The FTP adapter set up depends on whether the OpenSSH is running inside the firewall or outside the firewall. If OpenSSH is running inside the firewall, then refer to the following sections:

If OpenSSH is running outside the firewall, then refer to the following sections:

Configuring the OpenSSH for Public-Key Authentication

Perform the following steps:

  1. Go to C:\cygwin\etc folder. If required, configure the sshd_config file to force public key authentication. Refer to openssh help or manual for the information.

  2. Go to the C:\cygwin\bin directory.

  3. Run the following command to generate the key pair:

    ssh-keygen -t rsa
    
    
  4. Enter /etc/id_rsa when prompted for the file in which the key should be saved.

  5. Enter the passphrase.

  6. Enter the passphrase again.

  7. Go to the /etc directory and verify that both the public key file (id_rsa.pub) and the private key file (id_rsa) are generated.

  8. Run the following command to create a copy of the public key file:

    cp id_rsa.pub authorized_keys
    
    
  9. Create a copy of the private key file to a secured location such as C:\my-secured-folder\. The FTP adapter configuration will refer to this private key file.

  10. Restart the OpenSSH server by running the following commands:

    net stop sshd
    net start sshd
    
    

Configuring the FTP Adapter for Public Key Authentication with OpenSSH Running Inside the Firewall

Perform the following steps to set up the FTP adapter for public key authentication:

  1. In the oc4j-ra.xml file, specify the values of the parameters listed in Table 2-11. Ensure that the authenticationType parameter is set to publickey and the transportProvider paramter is set to socket. The privateKeyFile parameters should contain the location of the private key file.

  2. Restart the server after modifying the oc4j-ra.xml file.

A sample oc4j-ra.xml file with public key authentication parameters is shown in the following example:

<config-property name="useSftp" value="true"/>
<config-property name="authenticationType" value="publickey"/>
<config-property name="preferredKeyExchangeAlgorithm" value="diffie-hellman-group1-sha1"/>
<config-property name="preferredCompressionAlgorithm" value="none"/>
<config-property name="preferredDataIntegrityAlgorithm" value="hmac-md5"/>
<config-property name="preferredPKIAlgorithm" value="ssh-rsa"/>
<config-property name="privateKeyFile" value="C:\my-secured-folder\id_rsa"/>
<config-property name="preferredCipherSuite" value="blowfish-cbc"/>
<config-property name="transportProvider" value="socket"/>

Configuring the FTP Adapter for Public Key Authentication with OpenSSH Running Outside the Firewall

Perform the following steps to set up the FTP adapter for public key authentication when OpenSSH is running outside the firewall:

  1. In the oc4j-ra.xml file, specify the values of the parameters listed in Table 2-11. Ensure that the authenticationType parameter is set to publickey and the transportProvider parameter is set to HTTP. The privateKeyFile parameter contains the location of the private key file.

  2. In the oc4j-ra.xml file, also specify the following proxy-related parameters:

    • proxyHost: The name of the proxy host.

    • proxyPort: The port number of the proxy.

    • proxyUsername: The user name for the proxy.

    • proxyPassword: The password for the proxy.

    • useProxy: Specify true to use proxy.

  3. Restart the server after modifying the oc4j-ra.xml file.

A sample oc4j-ra.xml file with public key authentication parameters and proxy parameters is shown in the following example:

<config-property name="proxyHost" value="proxy.host.com"/>
<config-property name="proxyPort" value="80"/>
<config-property name="proxyUsername" value="anonymous"/>
<config-property name="proxyPassword" value="tiger@scott.com"/>
<config-property name="useProxy" value="true"/>
<config-property name="useSftp" value="true"/>
<config-property name="authenticationType" value="publickey"/>
<config-property name="preferredKeyExchangeAlgorithm" value="diffie-hellman-group1-sha1"/>
<config-property name="preferredCompressionAlgorithm" value="none"/>
<config-property name="preferredDataIntegrityAlgorithm" value="hmac-md5"/>
<config-property name="preferredPKIAlgorithm" value="ssh-rsa"/>
<config-property name="privateKeyFile" value="C:\my-secured-folder\id_rsa"/>
<config-property name="preferredCipherSuite" value="blowfish-cbc"/>
<config-property name="transportProvider" value="HTTP"/>

2.5 Configuring the FTP Adapter for HTTP Proxy

The FTP adapter provides proxy support for HTTP proxy only. The HTTP proxy support is available in the following two modes: plain FTP mode and SFTP mode. This section explains how to configure the FTP adapter for running in plain FTP mode and SFTP mode. It contains following topics:

2.5.1 Configuring for Plain FTP Mode

For running the FTP adapter in plain FTP mode, you need to specify the value of certain parameters in the oc4j-ra.xml file. Refer to Table 2-7 for information about the location of the oc4j-ra.xml file. Table 2-12 lists the parameters that you need to modify.

Table 2-12 Plain FTP Mode Parameters

Parameter Description Example

host

The remote FTP server name.

<config-property name="host" value="my.host.com"/>

port

The FTP control port number.

<config-property name="port" value="21"/>

username

The FTP user name.

<config-property name="username" value="scott"/>

password

The FTP password.

<config-property name="password" value="password"/>

proxyHost

The proxy host name.

<config-property name="proxyHost" value="proxy.host.com"/>

proxyPort

The proxy port number.

<config-property name="proxyPort" value="80"/>

proxyUsername

The proxy user name.

<config-property name="proxyUsername" value="anonymous"/>

proxyPassword

The proxy password.

<config-property name="proxyPassword" value="tiger@scott.com"/>

proxyType

The proxy type. Only HTTP proxy type is supported.

<config-property name="proxyType" value="http"/>

proxyDefinitionFile

The absolute path of the proxy definition file.

This parameter is not mandatary.

See Section 2.5.1.1, "Proxy Definition File" for more information.

<config-property name="proxyDefinitionFile" value="c:\ proxydefinitions.xml"/>

useProxy

Specify true to use proxy.

<config-property name="useProxy" value="true"/>


A sample oc4j-ra.xml file is shown in the following example:

<connector-factory location="eis/Ftp/FtpAdapter" connector-name="Ftp Adapter">
<config-property name="host" value="my.host.com"/><config-property name="port" value="21"/>
<config-property name="username" value="user"/>
<config-property name="password" value="password"/>
<config-property name="proxyHost" value="proxy.host.com"/>
<config-property name="proxyPort" value="80"/>
<config-property name="proxyUsername" value="anonymous"/>
<config-property name="proxyPassword" value="tiger@scott.com"/>
<config-property name="proxyType" value="http"/>
<config-property name="proxyDefinitionFile" value="c:\proxydefinitions.xml"/>
<config-property name="useProxy" value="true"/>
</connector-factory>

2.5.1.1 Proxy Definition File

You can specify all proxy-specific information in a proxy definition file and configure the adapter to use this file with the proxyDefinitionFile parameter of the oc4j-ra.xml file. A proxy definition file is written in XML format and is based on XML schema. The XML schema for the proxy definition file is shown in Example 2-1. Your proxy definition file must be based on this XML schema.

Example 2-1 Proxy Definition File XML Schema

<?xml version = \"1.0\" encoding = \"UTF-8\"?>
<schema targetNamespace = "http://ns.oracle.com/ip/af/ftp/proxy" xmlns = "http://www.w3.org/2001/XMLSchema" xmlns:proxy="http://ns.oracle.com/ip/af/ftp/proxy">

         <element name="ProxyDefinitions" type="proxy:ProxyDefinitionsType"/>              <complexType name="ProxyDefinitionsType">
                      <sequence>
                           <element name="Proxy" type="proxy:ProxyDefinition"
                            minOccurs="0" maxOccurs="unbounded"/>
                      </sequence>
              </complexType>

              <complexType name="ProxyDefinition">
                      <sequence>
                           <element name="Step" type="proxy:StepType"
                            minOccurs="1" maxOccurs="unbounded"/>
                      </sequence>
                      <attribute name="key" type="ID" use="required"/>
                      <attribute name="description" type="string"
                       use="required"/>
                      <attribute name="type" type="proxy:Protocol"
                       use="optional"/>
              </complexType>

              <complexType name="StepType">
                  <simpleContent>
                     <extension base="string">
                         <attribute name="command" type="string" use="required"/>
                         <attribute name="args" type="string" use="required"/>
                     </extension>
                  </simpleContent>
              </complexType>

               <simpleType name="Protocol">
                    <restriction base="string">
                          <enumeration value="ftp" />
                          <enumeration value="http" />
                    </restriction>
               </simpleType>
</schema>

A sample proxy definition file, based on the XML schema in Example 2-1, would look as shown in Example 2-2:

Example 2-2 Proxy Definition File

<?xml version = '1.0' standalone = 'yes'?> 
<proxy:ProxyDefinitions xmlns:proxy="http://ns.oracle.com/ip/af/ftp/proxy"> 
<Proxy key="http" description="http" type="http"> 
<Step command="USER" args="remote_username" /> 
<Step command="PASS" args="remote_password" /> 
</Proxy>
</proxy:ProxyDefinitions>

When you use the file in Example 2-2, the FTP adapter sends the following sequence of commands to login:

  1. USER remote_username

  2. PASS remote_password

You can also direct the proxy definition file to pick values from the oc4j-ra.xml file. You can use the following expressions for this:

  • $proxy.user: This corresponds to the value of the proxyUsername parameter in the oc4j-ra.xml file.

  • $proxy.pass: This corresponds to the value of the proxyPassword parameter in the oc4j-ra.xml file.

  • $remote.user: This corresponds to the value of the username parameter in the oc4j-ra.xml file.

  • $remote.pass: This corresponds to the value of the password parameter in the oc4j-ra.xml file.

  • $remote.host: This corresponds to the value of the host parameter in the oc4j-ra.xml file.

  • $remote.port: This corresponds to the value of the port parameter in the oc4j-ra.xml file.

A sample proxy definition file based on the XML schema in Example 2-2 and taking values from the oc4j-ra.xml file is shown in Example 2-3:

Example 2-3 Proxy Definition File Taking Values from the oc4j-ra.xml File

<?xml version = '1.0' standalone = 'yes'?> 
<proxy:ProxyDefinitions xmlns:proxy="http://ns.oracle.com/ip/af/ftp/proxy"> 
<Proxy key="http" description="http" type="http"> 
<Step command="USER" args="$remote.user" /> 
<Step command="PASS" args="$remote.pass" /> 
</Proxy>
</proxy:ProxyDefinitions>

2.5.2 Configuring for SFTP Mode

For running the FTP adapter in SFTP mode, you need to specify the value of certain parameters in the oc4j-ra.xml file. Refer to Table 2-7 for information about the location of the oc4j-ra.xml file. Table 2-13 lists the parameters which you need to modify.

Table 2-13 SFTP Mode Parameters

Parameter Description Example

host

The remote FTP server name.

<config-property name="host" value="my.host.com"/>

port

The FTP control port number.

<config-property name="port" value="22"/>

username

The SFTP user name.

<config-property name="username" value="scott"/>

password

The SFTP password.

<config-property name="password" value="password"/>

proxyHost

The proxy sever host name.

<config-property name="proxyHost" value="proxy.host.com"/>

proxyPort

The proxy port number.

<config-property name="proxyPort" value="80"/>

proxyUsername

The proxy user name.

<config-property name="proxyUsername" value="anonymous"/>

proxyPassword

The proxy password.

<config-property name="proxyPassword" value="tiger@scott.com"/>

useSftp

Specify true for SFTP mode. This value is required to use the SFTP feature.

<config-property name="useSftp" value="true"/>

authenticationType

Specify either PASSWORD or PUBLICKEY.PASSWORD

Refer to Section 2.4.3, "Set up the FTP Adapter for SFTP"

<config-property name="authenticationType" value="password"/>

transportProvider

Specify http as value. Only HTTP transport provider is supported.

<config-property name="transportProvider" value="http"/>


A sample oc4j-ra.xml file is shown in the following example:

<connector-factory location="eis/Ftp/FtpAdapter" connector-name="Ftp Adapter">
<config-property name="host" value="my.host.com"/>
<config-property name="port" value="22"/>
<config-property name="username" value="user"/>
<config-property name="password" value="password"/>
>config-property name="proxyHost" value="proxy.host.com"/>
<config-property name="proxyPort" value="80"/>
<config-property name="proxyUsername" value="anonymous"/>
<config-property name="proxyPassword" value="password"/>
<config-property name="useSftp" value="true"/>
<config-property name="authenticationType" value="password"/>
<config-property name="transportProvider" value="http"/>
</connector-factory>

2.6 File and FTP Adapters Use Cases for Oracle BPEL Process Manager

Oracle BPEL Process Manager includes a number of demonstrations of file and FTP adapters. Some of these demonstrations are described in Readme files. Others are described in the Oracle BPEL Process Manager documentation set. This section provides an overview of these demonstrations and a reference to documentation that more fully describes the scenarios.

This section contains the following topics:

2.6.1 File Adapter Use Cases for Oracle BPEL Process Manager

This section provides an overview of file adapter demonstrations.

This section contains the following topics:

2.6.1.1 File Reading

Several file reading demonstrations are available:

  • A complex structure demonstration shows how to use the file read and write functionality of the file adapter. The sample for a complex structure is available at the following location:

    Oracle_Home\bpel\samples\tutorials\121.FileAdapter\ComplexStructure
    
    
  • A simple file reading demonstration is provided as part of a larger tutorial that guides you through the design and execution of a sophisticated process that uses synchronous and asynchronous services, parallel flows of execution, conditional branching logic, fault handling and exceptions management, transformations, the file adapter, the database adapter, human workflow, notification, and sensor functionality. In the file reading portion, you configure the file adapter to read an inbound purchase order request from a file in a directory. See Oracle BPEL Process Manager Order Booking Tutorial for a tutorial that uses the file reading functionality of the file adapter.

2.6.1.2 Message Debatching

This demonstration shows how the file adapter processes native data containing multiple messages defined in a custom format. The file adapter takes a single inbound file of two records and writes each record to its own file. For a demonstration of message debatching, go to

Oracle_Home\bpel\samples\tutorials\121.FileAdapter\Debatching

2.6.1.3 Reading Delimited Content Files

This demonstration shows how the file adapter reads CSV-formatted entries in an address book, transforms the file contents using XSLT, and stores the data in a fixed-length formatted file. For a demonstration of delimited content files, go to

Oracle_Home\bpel\samples\tutorials\121.FileAdapter\FlatStructure

2.6.1.4 Reading Positional (Fixed Length) Content Files

This demonstration shows how the file adapter reads CSV-formatted entries in an address book, transforms the file contents using XSLT, and stores the data in a fixed-length formatted file. For a positional (fixed length) demonstration, go to

Oracle_Home\bpel\samples\tutorials\121.FileAdapter\FlatStructure

2.6.1.5 File Writing

A simple file writing demonstration is provided as part of the larger tutorial described in Section 2.6.1.1, "File Reading". In the file writing portion, you configure the file adapter to write an outbound purchase order acknowledgment to a file in a directory.

See Oracle BPEL Process Manager Order Booking Tutorial for a demonstration that uses the file writing functionality of the file adapter.

2.6.2 FTP Adapter Use Case for Oracle BPEL Process Manager

This demonstration shows how the file adapter processes native data containing multiple messages defined in a custom format. The native data instance contains an invoice and purchase order.

In the inbound direction, the FTP adapter retrieves a remote file, processes the file, and publishes the invoice and purchase order separately to the debatching BPEL process.

In the outbound direction, only purchase orders are generated. The debatching BPEL process transforms an invoice to a purchase order. The purchase record is simply copied over. All purchase orders are then written in separate remote output files. For an FTP demonstration, go to

Oracle_Home\bpel\samples\tutorials\129.FTPAdapter\FTPDebatching

2.7 File and FTP Adapters Use Case for Oracle Enterprise Service Bus

In this use case, Oracle Enterprise Service Bus receives the customer data from a file system as a text file, through an inbound file adapter service named ReadFile. The ReadFile adapter service sends the message to a routing service named ReadFile_RS. The ReadFile_RS sends the message to the outbound adapter service WriteFTP. The WriteFTP service delivers the message to its associated external application.

This use case consists of following sections:

2.7.1 Prerequisites

This example assumes that you are familiar with basic ESB constructs, such as services, routing service, andOracle JDeveloper environment for creating and deploying ESB services.

To define the schema of the messages, you require an address-csv.xsd file. This file can be copied from the following location:

ORAHOME\bpel\samples\tutorials\121.FileAdapter\FlatStructure

2.7.2 Creating an Oracle Enterprise Service Bus Application and Project

To create an application and a project for the use case, follow these steps:

  1. In the Application Navigator of Oracle JDeveloper, right-click Applications and select New Application. The Create Application dialog box is displayed.

  2. Enter FileFTP_RW in the Application Name field and click OK. The Create Project dialog box is displayed.

  3. Click Cancel.

  4. In the Application window, select Applications and then right-click FileFTP_RW.

  5. Select New Project. The New Gallery dialog box is displayed.

  6. From Categories, select General and then Projects.

  7. From Items, select ESB Project and click OK. The Create ESB Project dialog box is displayed.

  8. Enter FileRead_FTPWrite in the Project Name field.

  9. Click OK.

2.7.3 Importing the Schema Definition (.XSD) Files

Perform the following steps to import the XSD files that will define the structure of the messages:

  1. Create a Schema folder and copy the address-csv.xsd file to this folder.

  2. In the Application Navigator, select FileRead_FTPWrite.

  3. From the File menu, select Import. The Import dialog box is displayed.

  4. From the Select What You Want to Import list, select Web Source, and then click OK. The Web Source dialog box is displayed.

  5. To the right of the Copy From field, click Browse. The Choose Directory dialog box is displayed.

  6. Navigate to the Schema folder and click Select.The Web Source dialog box with the directory selected is displayed.

  7. Click OK.

2.7.4 Creating the Inbound File Adapter Service

Perform the following steps to create an inbound file adapter service to read the file from a local directory

  1. Drag a File Adapter service from Components Palette to the design area. The Create File Adapter Service dialog box is displayed.

  2. Enter ReadFile in the Name field.

  3. Click the Configure adapter service wsdl icon next to the WSDL field. The Adapter Configuration Wizard Welcome window is displayed.

  4. Click Next. The Service Name window is displayed.

  5. Click Next. The Operations window is displayed.

  6. Select Read File and click Next. The File Directories window is displayed

  7. Select Physical Path option, and click Browse and select a polling directory.

  8. Click Next. The File Filtering window is displayed.

  9. Enter *.txt in the Include Files with Name Pattern field and click Next. The File Polling window is displayed.

  10. Click Next. The Messages window is displayed.

  11. Click Browse. The Type Chooser dialog box is displayed.

  12. Select Project Schema Files, address-csv.xsd, and then Root-Element.

  13. Click OK.

  14. Click Next in the Messages window.

  15. Click Finish. The Create File Adapter Service dialog box is displayed.

  16. Click OK. A routing service ReadFile_RS will be created along with the ReadFile adapter service.

2.7.5 Creating the Outbound FTP Adapter Service

Perform the following steps to create an outbound FTP adapter service which will write the file to an FTP server:

  1. Drag an FTP Adapter service from Components Palette to the design area. The Create FTP Adapter Service dialog box is displayed.

  2. Enter WriteFTP in the Name field.

  3. Click the Configure adapter service wsdl icon next to the WSDL field. The Adapter Configuration Wizard Welcome window is displayed.

  4. Click Next. The Service Name window is displayed.

  5. Click Next. The FTP Server Connection window is displayed.

  6. Specify the JNDI Name of the FTP Server in the FTP Server JNDI Name field and click Next. The Operations window is displayed.

  7. Select Ascii option as File Type.

  8. Select Put File option as the Operation Type and click Next. The File Configuration window is displayed.

  9. Specify the directory to which file will be written in the Directory for Outgoing Files(physical path) field.

  10. Specify the naming convention for the output file name in the File Naming Convention field. For example, po_%SEQ%.txt.

  11. Click Next. The Messages window is displayed.

  12. Click Browse. The Type Chooser dialog box is displayed.

  13. Select Project Schema Files, address-csv.xsd, and then Root-Element.

  14. Click OK.

  15. Click Next in the Messages window.

  16. Click Finish.

2.7.6 Creating the Routing Rule

Perform the following steps to create a routing service:

  1. Double-click the ReadFile_RS routing service.

  2. Click the Plus icon in the Routing rules area. The Browse Target Service Operation dialog box is displayed.

  3. Select ESB, Services in project, DefaultSystem, WriteFTP, and then Put.

  4. Click OK.

  5. Click the icon next to the <<Transformation Map>> box. The request Transformation Map dialog box is displayed.

  6. Select Create New Mapper File and click OK.

    A Root_To_Root.xsl tab is added to Oracle JDeveloper. This tab enables you to graphically create a document transformation file to convert the structure of the file data to a canonical data structure.

  7. Drag and drop the imp1:Address source element to the imp1:Address target element. The Auto Map Preferences dialog box is displayed.

  8. From the During Auto Map options, deselect Match Elements Considering Their Ancestor Names.

  9. Click OK.

  10. From the File menu, click Save.

2.7.7 Registering Services with Oracle Enterprise Service Bus

Perform the following steps to register the services with Oracle Enterprise Service Bus Server:

  1. In the Applications Navigator, right-click FileRead_FTPWrite, choose Register with ESB, and then click LocalIntegrationServer.

    A message is displayed to indicate that the following services were successfully registered:

    • System.WriteFTP Created

    • System.ReadFile_RS Created

    • System.ReadFile Created

  2. Click OK.

  3. View the Oracle Enterprise Service Bus configuration in the Oracle Enterprise Service Bus Control Console, as follows:

    • If the Oracle Enterprise Service Bus Control Console is currently open, then:

      Click the Refresh button, and then click ReadFile_RS.

    • If the Oracle Enterprise Service Bus Control Console is not open, then:

      Select Start, All Programs, Oracle - Oracle_Home, Oracle ESB, ESB Control, to open the Oracle Enterprise Service Bus Control Console.

2.7.8 Run-Time Task

At run time, copy a text file to the polling directory. Once the file adapter picks the file, the file will be written to the directory that you specified at design time.