1. Understanding Technology Adapters
  2. Oracle Technology Adapters
  3. Oracle JCA Adapter for Files/FTP

5 Oracle JCA Adapter for Files/FTP

Learn how to use the Oracle File and FTP Adapters, which work with Oracle BPEL Process Manager and Oracle Mediator. These are separate adapters with very similar functionality.

5.1 Introduction to Oracle File and FTP Adapters

Oracle BPEL PM and Mediator include the Oracle File and FTP Adapters.

The Oracle File and FTP Adapters enable a BPEL process or a Mediator 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.

5.1.1 Oracle File and FTP Adapters Architecture

The Oracle File and FTP Adapters are based on JCA 1.5 architecture. JCA provides a standard architecture for integrating heterogeneous enterprise information systems (EIS). The JCA Binding Component of the Oracle File and FTP Adapters expose the underlying JCA interactions as services (WSDL with JCA binding) for Oracle BPEL PM integration. For details about Oracle JCA Adapter architecture, see Introduction to Oracle JCA Adapters.

5.1.2 Oracle File and FTP Adapters Integration with Oracle BPEL PM

The Oracle File and FTP Adapters are automatically integrated with Oracle BPEL PM. When you drag and drop the File Adapter or FTP Adapter from the Components window of Oracle JDeveloper, the Adapter Configuration Wizard starts with a Welcome page.

This wizard helps you to select and configure the Oracle File and FTP Adapters. Enter a Service Name.

Figure 5-1 The Adapter Configuration Wizard - Service Name Page

Description of Figure 5-1 follows
Description of "Figure 5-1 The Adapter Configuration Wizard - Service Name Page"

When configuration is complete, a WSDL and JCA file pair is created in the Application Navigator section of Oracle JDeveloper. (JDeveloper) This JCA file contains the configuration information you specify in the Adapter Configuration Wizard.

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

Table 5-1 Supported Operations for Oracle BPEL Process Manager

Operation Section

Oracle File Adapter

-

  • Read File (inbound operation)

Read File Concepts

  • Write File (outbound operation)

Write File Concepts

  • Synchronous Read File (outbound operation)

Synchronous Read Concepts

  • List Files (outbound operation)

File Listing Concepts

  • Oracle FTP Adapter

-

  • Get File (inbound operation)

Get File Concepts

  • Put File (outbound operation)

Put File Concepts

  • Synchronous Get File (outbound operation)

Synchronous Get File Concepts

  • List Files (outbound operation)

File Listing Concepts

For more information about Oracle JCA Adapter integration with Oracle BPEL PM, see Introduction to Oracle JCA Adapters.

5.1.3 Oracle File and FTP Adapters Integration with Mediator

The Oracle File and FTP Adapters are automatically integrated with Mediator. When you create an Oracle File or FTP Adapter service in JDeveloper Designer, the Adapter Configuration Wizard is started.

This wizard enables you to select and configure the Oracle File and FTP Adapters. When configuration is complete, a WSDL, JCA file pair is created in the Application Navigator section of JDeveloper. This JCA file contains the configuration information you specify in the Adapter Configuration Wizard.

The Operation Type page of the Adapter Configuration Wizard prompts you to select an operation to perform. Based on your selection, different Adapter Configuration Wizard pages appear and prompt you for configuration information. Table 5-2 lists the available operations and provides references to sections that describe the configuration information you must provide. For more information about Adapters and Mediator, see Introduction to Oracle JCA Adapters.

Table 5-2 Supported Operations for Oracle Mediator

Operation Section

Oracle File Adapter

-

  • Read File (inbound operation)

Read File Concepts

  • Write File (outbound operation)

Write File Concepts

  • Synchronous Read File (outbound operation)

Synchronous Read Concepts

  • List Files (outbound operation)

File Listing Concepts

Oracle FTP Adapter

-

  • Get File (inbound operation)

Get File Concepts

  • Put File (outbound operation)

Put File Concepts

  • Synchronous Get File (outbound operation)

Synchronous Get File Concepts

  • List Files (outbound operation)

File Listing Concepts

5.1.4 Oracle File and FTP Adapters Integration with SOA Composite

A composite is an assembly of services, service components (Oracle BPEL PM and Mediator), wires, and references designed and deployed in a single application. The composite processes the information described in the messages. The details of the composite are stored in the composite.xml file. For more information about integration of the Oracle File and FTP Adapters with SOA composite, see Oracle SOA Composite Integration with Adapters.

5.2 Oracle File and FTP Adapters Features

The Oracle File and FTP Adapters enable you to configure a BPEL process or a Mediator to interact with local and remote file system directories.

Browse through the following features of Oracle File and FTP Adapters.

Note:

For composites with Oracle File and FTP Adapters, which are designed to consume very large number of concurrent messages, you must set the number of open files parameter for your operating system to a larger value. For example, to set the number of open files parameter to 8192 for Linux, use the ulimit -n 8192 command.

5.2.1 File Formats

The Oracle File and FTP Adapters can read and write the following file formats and use the adapter translator component at runtime:

  • XML (both XSD- and DTD-based)

  • Delimited

  • Fixed positional

  • Binary data

  • COBOL Copybook data

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

Note that opaque representation base-64 encodes the payload and increase the size of the payload in-memory by a third. Opaque/base-64 representation is usually used for passing binary data within XML. See also Large Payload Support, for a description of attachment support.

The translator enables the Oracle File and FTP Adapters to convert native data in various formats to XML, and from XML to other formats. The native data can be simple (just a flat structure) or complex (with parent-child relationships). The translator can handle both XML and non-XML (native) formats of data.

5.2.2 FTP Servers

Oracle FTP Adapter supports most RFC 959 compliant FTP servers on all platforms. It also provides a pluggable mechanism that enables Oracle FTP Adapter to support additional FTP servers. In addition, Oracle FTP Adapter supports FTP over SSL (FTPS) on Solaris and Linux. For Windows, Oracle FTP Adapter is certified on FileZilla FTP server with OpenSSL and Windows IIS FTP server.

Oracle FTP Adapter also supports SFTP (Secure FTP) using SSH transport.

Note:

Oracle FTP Adapter supports SFTP server version 3 or later.

5.2.3 Inbound and Outbound Interactions

The Oracle File and FTP Adapters exchange files in the inbound and outbound directions. Based on the direction, the Oracle File and FTP Adapters perform different sets of tasks.

For inbound files sent to Oracle BPEL PM or Mediator, the Oracle File and FTP Adapters perform the following operations:

  1. Poll the file system looking for matches.

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

  3. Publish the translated content as an XML message.

This functionality of the Oracle File and FTP Adapters is referred to as the file read operation.

For outbound files sent from Oracle BPEL PM or Mediator, the Oracle File and FTP Adapters perform the following operations:

  1. Receive messages from BPEL or Mediator.

  2. Format the XML contents as specified at design time.

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

This functionality of the Oracle File and FTP Adapters is referred to as the file write operation. This operation is known as a JCA outbound interaction.

For the inbound and outbound directions, the Oracle File and FTP Adapters use a set of configuration parameters. For example:

  • The inbound Oracle 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 Oracle File and FTP Adapters have parameters for the outbound directory in which to write the file and the file naming convention to use.

Note:

You must use the Adapter Configuration Wizard to modify the configuration parameters, such as publish size, number of messages, and polling frequency.

You must not manually change the value of these parameters in JCA files.

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. You can use this feature for performance tuning of the Oracle File and FTP Adapters. The file reader guarantees once and once-only delivery.

Review the following topics for details about the read and write functionality of the Oracle File and FTP Adapters:

5.2.4 File Debatching

You can define the batch size using the publishSize parameter in the .jca file.

This property specifies if the file contains multiple messages and how many messages to publish to the BPEL process at a time.

For example, if a certain file has 11 records and this parameter is set to 2, then the file processes 2 records at a time and the final record is processed in the sixth iteration.

When a file contains multiple messages, you can choose to publish messages in a specific number of batches. This is referred to as debatching. During debatching, the file reader, on restart, proceeds from where it left off in the previous run, thereby avoiding duplicate messages. File debatching is supported for files in XML and native formats.

You can register a batch notification callback (Java class) which is invoked when the last batch is reached in a debatching scenario. 

<service ...
  <binding.jca ...
    <property name="batchNotificationHandler">java://oracle.sample.SampleBatchCalloutHandler </property>

where the property value must be java://{custom_class} and where oracle.sample.SampleBatchCalloutHandler must implement 

package oracle.tip.adapter.api.callout.batch;
public interface BatchNotificationCallout extends Callout
{
    public void onInitiateBatch(String rootId,
                                String metaData)
        throws ResourceException;
    public void onFailedBatch(String rootId,
                              String metaData,
                              long currentBatchSize,
                              Throwable reason)
        throws ResourceException;
    public void onCompletedBatch(String rootId,
                                String metaData,
             			                   long finalBatchSize)
        throws ResourceException;

5.2.5 File Chunked Read

The File Chunked Read operation enables you to process large files and uses a BPEL Invoke activity within a while loop to process the target file.

Specifically, the File Adapter allows the BPEL process modeler to use an Invoke activity to retrieve a logical chunk from a huge file, enabling the file to stay within memory constraints. The process calls the chunked-interaction in a loop in order to process the entire file, one logical chunk at a time. The intent is to achieve debatchability on a file's outbound processing.

You use the File Adapter Configuration Wizard to define a chunked JCA file and the WSDL file.

5.2.5.1 Chunked Interaction File Adapter Processing

The File Adapter translates the native data for a Chunked Read operation to XML and returns it as a BPEL variable.

To perform a Chunked Read, you typically create an Invoke activity within BPEL.

You also select Chunked Synchronous Read as the WSDL operation, using the File Adapter Configuration Wizard; you optionally use the Configuration Wizard to configure the file input directory and the filename which are placed in the ChunkedInteractionSpec.

Each call to the Invoke activity returns header values in addition to the payload.

These header values include: line number, column number, and indicators that specify if the End of File has been reached. You must ensure to copy the line/column numbers from the return header to the outbound headers for the subsequent call to the File Adapter. You can also specify the input directory/filename as header values if you want to.

5.2.5.1.1 File Chunked Interaction BPEL Invocation

The File Adapter Chunked Interaction is invoked from BPEL. For native data files, line number and column number are additionally passed as header values.

The first time that the Chunked Interaction is called within the loop, the values for LineNumber and ColumnNumber are blank; for subsequent calls, these values come from the return values from the Invoke minus one (that is, the prior Invoke).

The BPEL Invoke calls Chunked Interaction with the parameters provided in Table 5-3.

Table 5-3 BPEL Invoke Parameters for Chunked Interaction

Parameter Where Obtained

Physical/LogicalDirectory

ChunkedInteractionSpec or from the BPEL header

FileName

ChunkedInteractionSpec or from BPEL header

ChunkSizeBatchSize

ChunkedInteractionSpec, analogous to PublishSize in de-batching

LineNumber

Header (optional)

ColumnNumber

Header (optional)

RecordNumber

Header (optional)
5.2.5.1.2 The ChunkSize Parameter

The ChunkSize parameter provides information related to the size of the file chunk for the Chunked Read operation; it defaults to 1 if you do not configure another value in ChunkedInteractionSpec (that is, using the File Adapter Configuration Wizard).

Specifically, the ChunkSize parameter governs the number of nodes or records (not lines) that are returned.

For example, if you have an address book as a native CSV file and you have specified a ChunkSize of 5, each call to the Invoke activity returns an XML file containing 5 address book nodes; that is, five rows of CSV records in XML format.

In that sense, the ChunkSize parameter is analogous to the PublishSize parameter used by the File Adapter for an inbound transaction.

5.2.5.1.2.1 Example Rejection Handler Binding for Chunked Read

The following example shows how to configure a rejection handler for the Chunked Read reference binding.

Example - Rejection Handler Binding for Chunked Read

<reference name="ReadAddressChunk"> 
    <interface.wsdl 
        interface="http://xmlns.oracle.com/pcbpel/adapter
          /file/ReadAddressChunk/
                #wsdl.interface(ChunkedRead_ptt)"/> 
       <binding.jca config="ReadAddressChunk_file.jca"> 
         <property name="rejectedMessageHandlers" source="" 
              type="xs:string" many="false" override="may"
                >file:///c:/temp</property> 
       </binding.jca> 
  </reference>
5.2.5.1.2.2 Using Line Number/Column Number or Record Number

After every Invoke, you must copy the return headers over to the outbound headers for the subsequent invoke. The LineNumber/ColumnNumber are used by the Adapter for book-keeping purposes only, and you must ensure that you copy these values from the return-headers back to the headers before the call to the Chunked Interaction.

RecordNumber, on the other hand, is used when the data is in XML format (as distinct from native data). In that sense, RecordNumber is mutually exclusive with LineNumber/ColumnNumber, which is used for native data book-keeping.

5.2.5.1.2.3 File Chunked Read Interaction Artifacts

The following example shows a JCA file for Chunked Read.

Example - JCA File for Chunked Read

<interaction-spec className="oracle.tip.adapter.file.
                 outbound.ChunkedInteractionSpec">
      <property name="PhysicalDirectory"
                     value="/tmp/chunked/in"/>
      <property name="FileName" value="dummy.txt"/>
      <property name="ChunkSize" value="10"/>
    </interaction-spec>

The following example shows the generated Adapter WSDL file for the Chunked Read interaction:

Example - Chunked Read WSDL File

<?xml version = '1.0' encoding = 'UTF-8'?>
<definitions name="ReadAddressChunk"
   targetNamespace="http://xmlns.oracle.com/pcbpel
        /adapter/file/ReadAddressChunk/" 
        xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/
               file/ReadAddressChunk/" xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" xmlns:imp1="http://xmlns.oracle.com/pcbpel/demoSchema/csv">
    <documentation>Returns a finite chunk from the target 
      file based on the chunk size parameter</documentation>
    <types>
        <schema targetNamespace="http://xmlns.oracle.com/
                  pcbpel/adapter/
             file/ReadAddressChunk/" 
             xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://xmlns.oracle.com/pcbpel
             /demoSchema/csv" 
               schemaLocation="xsd/address-csv.xsd"/>
              <element name="empty">
                <complexType/>
              </element>
        </schema>
    </types>
    <message name="Empty_msg">
        <part name="Empty" element="tns:empty"/>
    </message>
    <message name="Root-Element_msg">
        <part name=
         "Root-Element" element="imp1:Root-Element"/>
    </message>
    <portType name="ChunkedRead_ptt">
        <operation name="ChunkedRead">
            <input message="tns:Empty_msg"/>
            <output message="tns:Root-Element_msg"/>
        </operation>
    </portType>
    <plt:partnerLinkType name="ChunkedRead_plt">
        <plt:role name="ChunkedRead_role">
            <plt:portType 
             name="tns:ChunkedRead_ptt"/>
        </plt:role>
    </plt:partnerLinkType>
</definitions>
5.2.5.2 Using the File Adapter Configuration Wizard to Perform Chunked Read Interaction Modelling

You use the File Adapter Configuration Wizard to model Chunked Read interaction.

You can use the initial three screens of the wizard as you would to configure any other File Adapter operation.

  1. From the File Adapter Operation Screen, specify Chunked Read.

    Figure 5-2 File Adapter Configuration Wizard Operation Page with Chunked Read Selected

    Description of Figure 5-2 follows
    Description of "Figure 5-2 File Adapter Configuration Wizard Operation Page with Chunked Read Selected"
  2. On the File Directories, specifying the directory information for the Chunked Read operation.

    Figure 5-3 File Adapter Configuration Wizard Specifying the Directory Information for the Chunked Read Operation

    Description of Figure 5-3 follows
    Description of "Figure 5-3 File Adapter Configuration Wizard Specifying the Directory Information for the Chunked Read Operation"
  3. On the File Directory page, indicate if the directory path you specify is physical or logical. Indicate or browse to find the file. Check and provide a directory to indicate the name of a physical path for the archived file. Deleting files after a successful retrieval is the default. Select Next.
  4. The File Adapter Configuration Wizard File Name Page is displayed. Indicate the name of the file for the Chunked Read operation. Select Next.

    Figure 5-4 File Adapter Configuration Wizard File Name Page

    Description of Figure 5-4 follows
    Description of "Figure 5-4 File Adapter Configuration Wizard File Name Page"
  5. The File Adapter Configuration Wizard Messages Screen appears.

    Figure 5-5 File Adapter Configuration Wizard Messages Screen

    Description of Figure 5-5 follows
    Description of "Figure 5-5 File Adapter Configuration Wizard Messages Screen"
  6. The File Adapter Wizard Messages Screen enables you to define a message for the Chunked Read file operation. You can specify a file location and select the Schema Element that defines the messages for the incoming files. Use the browse button to find an existing schema definition. If you check Schema is Opaque, you do not must specify a Schema. Select Next or Finish to display the File Adapter Configuration Wizard and to display the directory path and name for the WSDL for the Chunked Read File operation.
5.2.5.2.1 Chunked Interaction Error Handling Summary

When a translation exception (that is, a bad record that violates the nXSD specification) is encountered, the return header is populated with the translation exception message that includes details such as the line/column where the error occurred.

However, a specific translation error does not result in a fault. Instead, it becomes a value in the return header. You must check the jca.file.IsMessageRejected and the jca.file.RejectionReason header values to check if rejection did happen. Additionally, you can also check the jca.file.NoDataFound header value

5.2.5.2.2 Skipping Bad Records

Using the nxsd:uniqueMessageSeparator construct enables the Adapter to skip bad records and continue processing the next set of records. (For more information on uniqueMessageSeparator, see Native Format Builder Wizard .)

If you do not use the uniqueMessageSeparator, the Adapter returns EndOfFile and thus causes the while loop to terminate.

Thus, the uniqueMessageSeparator construct is required if you want processing to continue and not assume an End of File situation. The absence of the uniqueMessageSeparator construct causes the rest of the file to be rejected as a single chunk-to reject the entire file.

5.2.5.2.3 Examples of Chunked Interaction Header and Rejected Chunked Interaction Messages

See Figure 5-6 for an example of the return header appearance in a scenario that employs the nxsd:uniqueMessageSeparator construct.

This scenario shows a Chunked Interaction with a file that had six records (each of which was complex) and each alternate record was malformed. In the scenario, the ChunkSize used was five.

The returnHeader shows that the messages have been rejected (isMessageRejected=true) and the rejection reason is populated for the three malformed records: specifically, the records at line 17, 37, and 57 were malformed.

The NoDataFound parameter is set to false, which means that the data for the remaining three records is returned.

Figure 5-6 Return Outbound Header Appearance when nxsd:uniqueMessageSeparator is Used

Description of Figure 5-6 follows
Description of "Figure 5-6 Return Outbound Header Appearance when nxsd:uniqueMessageSeparator is Used"

The same records are also rejected to the user-configured rejection folder (C:\foo in this case). See Figure 5-7.

Figure 5-7 Chunked Read Interaction Rejected Messages in Rejection Folder

Description of Figure 5-7 follows
Description of "Figure 5-7 Chunked Read Interaction Rejected Messages in Rejection Folder "

5.2.6 File Sorting

When files must be processed by Oracle File and FTP Adapters in a specific order, you can you use the File Sorting Functionality of the Adapter. For example, you can configure the sorting parameters for Oracle File and FTP Adapters to process files in ascending or descending order by time stamps.

If you use Oracle File and FTP Adapters to trigger a BPEL process, configure the BPEL process as a synchronous process. To configure, add <property name="bpel.config.oneWayDeliveryPolicy" type="xs:string" many="false">sync</property> to composite.xml. This ensures that BPEL runs in the same thread started by the Oracle File and FTP Adapters and BPEL too processes the files in the specified order. Ensure that BPEL does not encounter breakpoint activity. When the BPEL instance encounters a mid-process breakpoint activity (not including the initial receive), such as wait, receive, onMessage, onAlarm, call to an async WSDL, the BPEL instance is dehydrated (saved in a database) and a separate thread is started. This happens as the existing BPEL instance waits for an event, such as timer expiration or message arrival and when the event occurs (the alarm expires or the message arrives), the instance is loaded from the dehydration store and execution is resumed.

You must meet the following prerequisites for sorting scenarios of Oracle File and FTP Adapters:

  • Use a synchronous operation

  • Add the following property to the inbound JCA file:

    <property name="ListSorter" 
value="oracle.tip.adapter.file.inbound.listing.TimestampSorterAscending"/> 
<property name="SingleThreadModel" value="true"/>

5.2.7 Dynamic Outbound Directory and File Name Specification

The Oracle 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, see Outbound File Directory Creation.

5.2.8 Security

The Oracle FTP Adapter supports FTP over SSL (FTPS) and Secure FTP (SFTP) to enable secure file transfer over a network.

For more information, see Using Secure FTP with the Oracle FTP Adapter and Using SFTP with the Oracle FTP Adapter.

5.2.9 Nontransactional

The Oracle File Adapter picks up a file from an inbound directory, processes the file, and sends the processed file to an output directory. However, if a failover occurs in the Oracle RAC back end or in a SOA Managed erver during this process, then the file is processed twice because of the nontransactional nature of Oracle File Adapter. As a result, there can be duplicate files in the output directory.

5.2.10 Proxy Support

You can use the proxy support feature of the Oracle FTP Adapter 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 5-8 shows how a proxy server creates connections to simulate a direct connection between the client and the remote FTP server.

Figure 5-8 Remote FTP Server Communication Through a Proxy Server

Description of Figure 5-8 follows
Description of "Figure 5-8 Remote FTP Server Communication Through a Proxy Server"

To use the HTTP proxy feature, your proxy server must support FTP traffic through HTTP Connection. In addition, only passive data connections are supported with this feature. For information about how to configure the Oracle FTP Adapter, see Configuring for HTTP Proxy.

5.2.11 No Payload Support

For Oracle BPEL PM and Mediator, the Oracle File and FTP Adapters provide support for publishing only file metadata such as file name, directory, file size, and last modified time to a BPEL process or Mediator and excludes the payload. The process can use this metadata for subsequent processing. For example, the process can call another reference and pass the file and directory name for further processing.You can use the Oracle File and FTP Adapters as a notification service to notify a process whenever a new file appears in the inbound directory. To use this feature, select the Do not read file content check box in the JDeveloper wizard while configuring the "Read operation."

5.2.12 Large Payload Support

For Oracle BPEL PM and Mediator, the Oracle File Adapter provides support for transferring large files as attachments. To use this feature, select the Read File As Attachment check box in the JDeveloper Configuration wizard while configuring the Read operation.

This option opaquely transfers a large amount of data from one place to another as attachments. For example, you can transfer large MS Word documents, images, and PDFs without processing their content within the composite application. For information about how to pass large payloads as attachments, see Read File As Attachments.

Additionally, the Oracle File Adapter provides you with the ability to write files as an attachment. When you write files as attachments, and also have a normal payload, it is the attached file that is written, and the payload is ignored.

Note:

You must not pass large payloads as opaque schemas.

5.2.13 File-Based Triggers

You can use the Oracle File and FTP Adapters, which provide support for file-based triggers, to control inbound adapter endpoint activation. For information about how to use file-based triggers, see File Polling.

5.2.14 Pre-Processing and Post-Processing of Files

The process modeler may encounter situations where files must be pre-processed before they are picked up for processing or post-processed before the files are written out to the destination folder. For example, the files that the Oracle File and FTP adapters receive may be compressed or encrypted and the adapter must decompress or decrypt the files before processing. In this case, you must use a custom code to decompress or decrypt the files before processing. The Oracle File and FTP Adapters supports the use of custom code that can be plugged in for pre-processing or post-processing of files.

The implementation of the pre-processing and post-processing of files is restricted to the following communication modes of the Oracle File and FTP Adapters:

  • Read File or Get File

  • Write File or Put File

  • Synchronous Read File

  • Chunked Read

This section contains the following topics:

5.2.14.1 Mechanism For Pre-Processing and Post-Processing of Files

The mechanism for pre-processing and post-processing of files is configured as pipelines and valves. This section describes the concept of pipelines and valves.

A pipeline consists of a series of custom-defined valves. A pipeline loads a stream from the file system, subjects the stream to processing by an ordered sequence of valves, and after the processing returns the modified stream to the adapter.

A valve is the primary component of execution in a processing pipeline. A valve processes the content it receives and forwards the processed content to the next valve. For example, in a scenario where the Oracle File and FTP Adapters receive files that are encrypted and zipped, you can configure a pipeline with an unzip valve followed by a decryption valve. The unzip valve extracts the file content before forwarding it to the decryption valve, which decrypts the content and the final content is made available to the Oracle File or FTP Adapter as shown in Figure 5-9.

Figure 5-9 A Sample Pre-Processing Pipeline

Description of Figure 5-9 follows
Description of "Figure 5-9 A Sample Pre-Processing Pipeline"
5.2.14.2 Configuring a Pipeline

Configuring the mechanism for pre-processing and post-processing of files requires defining a pipeline and configuring it in the corresponding JCA file.

To configure a pipeline, you must perform the following steps:

5.2.14.2.1 Implementing and Extending Valves

  • All valves must implement Valve or StagedValve interface.

    Tip:

    You can extend either the AbstractValve or the AbstractStagedValve class based on business requirement rather than implementing a valve from the beginning.

    The below example is a sample valve interface.

    Example - The Valve Interface

    package oracle.tip.pc.services.pipeline;
 
import java.io.IOException;
/** <p>
 *  Valve component is resposible for processing the input stream
 *  and returning a modified input stream. 
 *  The <code>execute()</code> method of the valve gets invoked
 *  by the caller (on behalf) of the pipeline. This method must 
 *  return the input stream wrapped within an InputStreamContext.
 *  The Valve is also responsible for error handling specifically
 *  
 *  The Valve can be marked as reentrant in which case the caller
 *  must call the <code>execute()</code> multiple times and each
 *  invocation must return a new input stream. This is useful, if
 *  you are writing an UnzipValve since each iteration of the valve
 *  must return the input stream for a different zipped entry. 
 *  <b> You must note that only the first Valve in the pipeline can
 *  be reentrant </b>
 *  
 *  The Valve has another flavor <code>StagedValve</code> and if 
 *  the valve implements StagedValve, then the valve must store
 *  intermediate content in a staging file and return it whenever
 *  required.
 * </p>
 */
public interface Valve
{
    /**
     * Set the Pipeline instance. This parameter can be
     * used to get a reference to the PipelineContext instance. 
     * @param pipeline
     */
    public void setPipeline(Pipeline pipeline);
 
    /** Returns the Pipeline instance.
       * @return
       */
      public Pipeline getPipeline();
      
      /** Returns true if the valve has more input streams to return
       *  For example, if the input stream is from a zipped file, then
       *  each invocation of <code>execute()</code> returns a different
       *  input stream once for each zipped entry. The caller calls 
       *  <code>hasNext()</code> to check if more entries are available
       * @return true/false
       */
      public boolean hasNext();
      
      /** Set to true if the caller can call the valve
           multiple times
       *  e.g. in case of ZippedInputStreams
       * @param reentrant
       */
      public void setReentrant(boolean reentrant);
 
      /** Returns true if the valve is reentrant.
     * @return
     */
    public boolean isReentrant();
    
    /** The method is called by pipeline to
        return the modified input stream
     * @param in
     * @return InputStreamContext that wraps 
     * the input stream along with required metadata 
     * @throws PipelineException
     */
    public InputStreamContext execute(InputStreamContext
         in) throws 
            PipelineException, IOException;
    
      /**
       * This method is called by the pipeline after the caller 
       * publishes the 
       * message to the SCA container. 
       * In the case of a zipped file, this method 
       * gets called repeatedly, once
       * for each entry in the zip file.
       * This should be used by the Valve to do 
       * additional tasks such as
       * delete the staging file that has been processed 
       * in a reentrant 
       * scenario.
       * @param in The original InputStreamContext returned from 
<code>execute()</code>
       */
      public void finalize(InputStreamContext in);
 
    /**Cleans up intermediate staging files, input streams
     * @throws PipelineException, IOException
     */
    public void cleanup() throws PipelineException, IOException;
 }

    The StagedValve stores intermediate content in staging files. The example below shows the StagedValve interface extending the Valve interface.

    Example - The StagedValve Interface Extending the Valve Interface

    package oracle.tip.pc.services.pipeline;
 
import java.io.File;
 
/**
 * A special valve that stages the modified
 * input stream in a staging file.
 * If such a <code>Valve</code> exists, then
 * it must return the staging file containing 
 * the intermediate data.
 */
public interface StagedValve extends Valve {
      
      /**
       * @return staging file where the valve 
       * stores its intermediate results
       */
      public File getStagingFile();
}

    The below example is a sample of an AbstractValve class implementing the Valve interface.

    Example - The AbstractValve Class Implementing the Valve Interface

    package oracle.tip.pc.services.pipeline;
 
import java.io.IOException;
 
/**
 * A bare bone implementation of Valve. The user should 
 * extend from
 * AbstractValve rather than implementing a Valve from scratch
 * 
 */
public abstract class AbstractValve implements Valve {
 
      /**
       * The pipeline instance is stored as a member
       */
      private Pipeline pipeline = null;
 
      /**
       * If reentrant is set to true, then the Valve must adhere to the 
following:
       * i) It must the first valve in the pipeline ii)
       *  Must implement hasNext
       * method and return true if more input
       * streams are available A reentrant
       * valve will be called by the pipeline
       * more than once and each time the
       * valve must return a different input stream, 
       * for example Zipped entries 
       * within a zip file
       */
      private boolean reentrant = false;
 
      /*
       * Save the pipeline instance.
       * 
       * @see 
       * oracle.tip.pc.services.pipeline.Valve#setPipeline
       * (oracle.tip.pc.services.pipeline.Pipeline)
       */
      public void setPipeline(Pipeline pipeline) {
            this.pipeline = pipeline;
      }
 
      /*
       * Return the pipeline instance (non-Javadoc)
       * 
       * @see oracle.tip.pc.services.pipeline.
       * Valve#getPipeline()
       */
      public Pipeline getPipeline() {
            return this.pipeline;
      }
 
      /*
       * Return true if the valve is reentrant (non-Javadoc)
       * 
       * @see oracle.tip.pc.services.pipeline.
       * Valve#isReentrant()
       */
      public boolean isReentrant() {
            return this.reentrant;
      }
 
      /*
       * If set to true, the valve is reentrant (non-Javadoc)
       * 
       * @see oracle.tip.pc.services.pipeline.
       * Valve#setReentrant(boolean)
       * 
       */
      public void setReentrant(boolean reentrant) {
            this.reentrant = reentrant;
      }
 
      /*
       * By default, set to false For valves 
       * that can return more than one
       * inputstreams to callers, this parameter
       *  must return true/false depending
       * on the availability of input streams (non-Javadoc)
       * 
       * @see oracle.tip.pc.services.pipeline.Valve#hasNext()
       */
      public boolean hasNext() {
            return false;
      }
 
      /*
       * Implemented by concrete valve (non-Javadoc)
       * 
       * @see oracle.tip.pc.services.pipeline.
       * Valve#execute(InputStreamContext)
       */
      public abstract InputStreamContext 
             execute(InputStreamContext in)
                  throws PipelineException, IOException;
 
      /*
       * Implemented by concrete valve (non-Javadoc)
       * 
       * @see 
       *       oracle.tip.pc.services.pipeline.Valve#finalize
       *       (oracle.tip.pc.services.pipeline.In
       *                      putStreamContext)
       *        /
      public abstract void finalize(InputStreamContext in);
 
      /*
       * Implemented by concrete valve (non-Javadoc)
       * 
       * @see oracle.tip.pc.services.pipeline.
       * Valve#cleanup()
       */
      public abstract void cleanup() 
              throws PipelineException, IOException;
 
}

    The below example shows the AbstractStagedValve class extending the AbstractValve class.

    Example - The AbstractStagedValve Class Extending the AbstractValve Class

    package oracle.tip.pc.services.pipeline;
 
import java.io.File;
import java.io.IOException;
 
public abstract class AbstractStagedValve
           extends AbstractValve implements
            StagedValve {
 
      public abstract File getStagingFile();
 
      public abstract void cleanup() throws IOException, 
              PipelineException;
 
      public abstract InputStreamContext 
                    execute(InputStreamContext in)
                  throws IOException, PipelineException;
 
}

    For more information on valves, see Oracle JCA Adapter Valves.

5.2.14.2.2 Compiling the Valves

  • You must use the bpm-infra.jar file to compile the valves. The bpm-infra.jar file is located at $MW_HOME/AS11gR1SOA/soa/modules/oracle.soa.fabric_11.1.1/bpm-infra.jar.

    1. Reference the SOA project to the bpm-infra.jar file, by using the following procedure:

      1. In the Application Navigator, right-click the SOA project.

      2. Select Project Properties. The Project Properties dialog is displayed.

      3. Click Libraries and Classpath. The Libraries and Classpath pane is displayed as shown in Figure 5-10.

        Figure 5-10 The Project Properties Dialog

        Description of Figure 5-10 follows
        Description of "Figure 5-10 The Project Properties Dialog"

      4. Click Add Jar/Directory. The Add Archive or Directory dialog is displayed.

      5. Browse to select the bpm-infra.jar file. The Bpm-infra.jar file is located at $MW_HOME/AS11gR1SOA/soa/modules/oracle.soa.fabric_11.1.1/bpm-infra.jar.

      6. Click OK. The bpm-infra.jar file is listed under Classpath Entries.

    2. Compile the valves using the bpm-infra.jar file.

    3. Make the JAR file containing the compiled valves available to the Oracle WebLogic Server classpath by adding the jar file to the soainfra domain classpath. For example, $MW_HOME/user_projects/domains/soainfra/lib.

    Note:

    Ensure that you compile bpm-infra.jar with JDK 6.0 to avoid compilation error such as class file has wrong version 50.0, should be 49.0.

5.2.14.2.3 Creating a Pipeline

  • To configure a pipeline, you must create an XML file that conforms to the following schema:

    Example - XML for Pipeline Creation

    <?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.oracle.com/adapter/pipeline">  
  <xs:element name="pipeline">    
    <xs:complexType> 
      <xs:sequence>        
        <xs:element ref="valves">            
          <xs:complexType>                      
            <xs:sequence>                             
              <xs:element ref="valve"
                       maxOccurs="unbounded">
                <xs:complexType mixed="true">                                        
                <xs:attribute name="reentrant"
                   type="xs:NMTOKEN" 
                         use="optional" />
                </xs:complexType>                              
              </xs:element>                       
            </xs:sequence>            
          </xs:complexType>
        </xs:element>      
      </xs:sequence>    
    </xs:complexType>      
    <xs:attribute name="useStaging" 
              type="xs:NMTOKEN" use="optional" />      
    <xs:attribute name="batchNotificationHandler"
            type="xs:NMTOKEN" use=" 
optional" />    
  </xs:element>
</xs:schema

    The following is a sample XML file configured for a pipeline with two valves, SimpleUnzipValve and SimpleDecryptValve:

    Example - XML file configured for a Pipeline with two valves

    <?xml version="1.0"?>
<pipeline xmlns=
          "http://www.oracle.com/adapter/pipeline">
<valves>
        <valve>valves.SimpleUnzipValve</valve>
        <valve> valves.SimpleDecryptValve </valve>
</valves>
</pipeline>
5.2.14.2.4 Adding the Pipeline to the SOA Project Directory

  • You must add the pipeline.xml file to the SOA project directory. This step is required to integrate the pipeline with the Oracle File or FTP Adapter. Figure 5-11 shows a sample pipeline.xml file (unzippipeline.xml) added to the InboundUnzipAndOutboundZip project.

    Figure 5-11 Project with unzippipeline.xml File

    Description of Figure 5-11 follows
    Description of "Figure 5-11 Project with unzippipeline.xml File"
5.2.14.2.5 Registering the Pipeline

  • The pipeline that is a part of the SOA project must be registered by modifying the inbound JCA file, by adding the following property:

    <property name="PipelineFile" value="pipeline.xml"/>

    Note:

    Place the pipeline.xml file in the same directory where composite.xml is located or in the adapters subdirectory where .jca file is located.

    For example, in the JCA file shown in Figure 5-11, FileInUnzip_file.jca, the following property has been added to register an Unzip pipeline with an Oracle File Adapter: 

    <property name="PipelineFile" value="unzippipeline.xml"/>

    There may be scenarios involving simple valves. A simple valve is one that does not require additional metadata such as re-entrancy, and batchNotificationHandlers. If the scenario involves simple valves, then the pipeline can be configured as an ActivationSpec or an InteractionSpec property as shown in the following sample:

    Example - Pipeline Configuration with Simple Valves

    <?xml version="1.0" encoding="UTF-8"?>
<adapter-config name="FlatStructureIn"
                 adapter="File Adapter" 
xmlns="http://platform.integration.
              oracle/blocks/adapter/fw/metadata">
  
  <connection-factory location="eis/FileAdapter" 
               UIincludeWildcard="*.txt" 
adapterRef=""/>
  <endpoint-activation operation="Read">
    <activation-spec 
className="oracle.tip.adapter.file.
                     inbound.FileActivationSpec">
      <property name="UseHeaders" value="false"/>
      <property name=
              "LogicalDirectory" value="InputFileDir"/>
      <property name="Recursive" value="true"/>
      <property name="DeleteFile" value="true"/>
      <property name="IncludeFiles" value=".*\.txt"/>
      <property name="PollingFrequency" value="10"/>
      <property name="MinimumAge" value="0"/>
      <property name="OpaqueSchema" value="false"/>
    </activation-spec>
  </endpoint-activation>
 
</adapter-config>

    Note:

    There is no space after the comma (,) in the PipelineValves property value.

    Note:

    If you configure a pipeline using the PipelineValve property, then you cannot configure additional metadata such as Re-entrant Valve and Batch Notification Handler. Additional metadata can be configured only with PipelineFile that is used for the XML-based approach.

5.2.14.3 Using a Re-Entrant Valve For Processing Zip Files

The re-entrant valve enables you to process individual entries within a zip file. In a scenario that involves processing all entries within a zip file, wherein each entry is encrypted using the Data Encryption Standard (DES), you can configure the valve by adding the reentrant="true" attribute to the unzip valve as follows:

Example - Configuring the reentrant=true Attribute

<?xml version="1.0"?>
<pipeline xmlns="http://www.oracle.com/adapter/pipeline">
<valves>
        <valve reentrant="true">valves.ReentrantUnzipValve</valve>
        <valve> valves.SimpleDecryptValve </valve>
</valves>
</pipeline>

In this example, the pipeline invokes the ReentrantUnzipValve and then the SimpleDecryptValve repeatedly in the same order until the entire zip file has been processed. In other words, the ReentrantUnzipValve is invoked first to return the data from the first zipped entry, which is then fed to the SimpleDecryptValve for decryption, and the final content is returned to the Adapter. The process repeats until all the entries within the zip file are processed.

Additionally, the valve must set the message key using the setMessageKey() API. For more information refer to An Unzip Valve for processing Multiple Files.

Note:

Ensure that <FMWHome>/soa/soa/modules/oracle.rules.thirdparty_12.1.2/poi-ooxml-schemas-3.7.jar exists.

Error Handling For Zip Files

If there are translation errors for individual entries within the zip file, entries with the translation errors are rejected and the other entries are processed.

If there are errors during the publish operation, the publish operation is retried and the retry semantic holds. If the retry semantic does not hold, then the original file is rejected and the pipeline ends.

5.2.14.4 Configuring the Batch Notification Handler

The BatchNotificationHandler API is used with the Oracle File and FTP Adapter inbound de-batchability. In a de-batching scenario, each file contains multiple messages, and some sort of bookkeeping is required for crash-recovery. This is facilitated by the BatchNotificationHandler API, which lets you receive notification from the pipeline whenever a batch begins, occurs, or ends. The below example is the BatchNotificationHandler interface:

Example - BatchNotification Handler

package oracle.tip.pc.services.pipeline;
 
/*
 * Whenever the caller processes de-batchable files,
 * each file can
 * have multiple messages and this handler
 * allows the user to plug in
 * a notification mechanism into the pipeline.
 * 
 * This is particularly useful in crash recovery 
 * situations
 */
 public interface BatchNotificationHandler {
 
      /*
       * The Pipeline instance is set by the 
       * PipelineFactory when the
       * BatchNotificationHandler instance is created
       */
      public void setPipeline(Pipeline pipeline);
 
      public Pipeline getPipeline();
      /*
       * Called when the BatchNotificationHandler 
       * is instantiated
       */
        
      public void initialize();
      /*
       * Called by the adapter when a batch begins,
       * the implementation must 
       * return
         * a BatchContext instance with the 
         * following information:
         * i) batchId: a unique 
         * id that will be returned 
         * every time onBatch is 
         * invoked by called
         * ii)line/col/record/offset:
         * for error recovery cases
       */
      public BatchContext onBatchBegin();
 
      /*
       * Called by the adapter
       * when a batch is submitted. 
       * The parameter holds the 
       * line/column/record/offset for the successful batch
       * that is published.
       * Here the implementation 
       * must save these in 
       * order to recover from 
       * crashes
       */
 
      public void onBatch(BatchContext ctx);
 
      /*
       * Called by the adapter when a batch 
       * completes.
      * This must be used to clean up
       */
      public void onBatchCompletion
           (boolean success);
}

To use a pipeline with de-batching, you must configure the pipeline with a BatchNotificationHandler instance. See the below example.

Example - Configuring the Pipeline with a BatchNotificationHandler Instance

<?xml version="1.0"?>
<pipeline xmlns="http://www.oracle.com
           /adapter/pipeline" batchNotificationHandler="oracle.tip.pc.services.                  pipeline.ConsoleBatchNotificationHandler">
<valves>
      <valve reentrant="true">valves.
                  SimpleUnzipValve</valve>
      <valve>valves.SimpleDecryptValve</valve>
</valves>
</pipeline>

5.2.15 Error Handling

The Oracle File Adapter and Oracle FTP Adapter provide inbound error handling capabilities, such as the 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 property 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 record with errors are also rejected.

The below example provides an example of using the uniqueMessageSeparator property:

Example - Schema File Showing Use of uniqueMessageSeparator Property

<?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:-->

For information about handling rejected messages, connection errors, and message errors, see Handling Rejected Messages .

5.2.15.1 Sending a Malformed XML File to a Local File System Folder

During an Inbound Read operation, if a malformed XML file is read, the malformed file results in an error. The errored file is by default sent to the remote file system for archival.

The errored file can be archived at a local file system by specifying the useRemoteErrorArchive property in the jca file and setting that property to false.

The default value for this property is true.

5.2.16 Threading Model

This section describes the threading models that Oracle File and FTP Adapters support. An understanding of the threading models is required to throttle or de-throttle the Oracle File and FTP Adapters. The Oracle File and FTP Adapters use the following threading models:

5.2.16.1 Default Threading Model

In the default threading model, a poller is created for each inbound Oracle File or FTP Adapter endpoint. The poller enqueues file metadata into an in-memory queue, which is processed by a global pool of processor threads. Figure 5-12 shows a default threading model.

Figure 5-12 Default Threading Model

Description of Figure 5-12 follows
Description of "Figure 5-12 Default Threading Model"

The following steps highlight the functioning of the default threading model:

  1. The poller periodically looks for files in the input directory. The interval at which the poller looks for files is specified using the PollingFrequency parameter in the inbound JCA file.

  2. For each new file that the poller detects in the configured inbound directory, the poller enqueues information such as file name, file directory, modified time, and file size into an internal in-memory queue.

    Note:

    New files are ones that are not being processed.

  3. A global pool of processor worker threads wait to process from the in-memory queue.

  4. Processor worker threads pick up files from the internal queue, and perform the following actions:

    1. Stream the file content to an appropriate translator (for example, a translator for reading text, binary, XML, or opaque data.)

    2. Publish the XML result from the translator to the SCA infrastructure.

    3. Perform the required postprocessing, such as deletion or archival after the file is processed.

5.2.16.2 Modified Threading Model

You can modify the default threading behavior of Oracle File and FTP Adapters. Modifying the threading model results in a modified throttling behavior of the Oracle File and FTP Adapters. The following sections describe the modified threading behavior of the Oracle File and FTP Adapters:

5.2.16.2.1 Single Threaded Model

The single threaded model is a modified threaded model that enables the poller to assume the role of a processor. The poller thread processes the files in the same thread. The global pool of processor threads is not used in this model. You can define the property for a single threaded model in the inbound JCA file as follows:

Example - Defining the Property for a Single-Threaded Model

<activation-spec className="oracle.tip.adapter.file.
   inbound.FileActivationSpec">
   <property../>
   <property name="SingleThreadModel" value="true"/>
   <property../>
</activation-spec>
5.2.16.2.2 Partitioned Threaded Model

The partitioned threaded model is a modified threaded model in which the in-memory queue is partitioned and each composite application receives its own in-memory queue. The Oracle File and FTP Adapters are enabled to create their own processor threads rather than depend on the global pool of processor worker threads for processing the enqueued files. You can define the property for a partitioned model in the inbound JCA file. See the example below.

Example - Defining the Property for a Partitioned Model in the Inbound JCA File

<activation-spec 
className="oracle.tip.adapter.file.inbound.
   FileActivationSpec">
  <property../>
  <property name="ThreadCount" value="4"/>
  <property../>
</activation-spec>

In the preceding example for defining the property for a partitioned model:

  • If the ThreadCount property is set to 0, the threading behavior is like that of the single threaded model.

  • If the ThreadCount property is set to -1, the global thread pool is used, as in the default threading model.

  • The maximum value for the ThreadCount property is 40.

5.2.17 Performance Tuning

The Oracle File and FTP Adapters support the performance tuning feature by providing knobs to throttle the inbound and outbound operations. The Oracle File and FTP Adapters also provide parameters that you can use to tune the performance of outbound operations.

For more information about performance tuning, see Oracle JCA Adapter Tuning Guide in this document.

5.2.18 High Availability

The Oracle File and FTP Adapters support the high availability feature for the active-active topology with Oracle BPEL Process Manager and Mediator service engines. They support this feature for both inbound and outbound operations.

5.2.19 Multiple Directories

The Oracle File and FTP Adapters support polling multiple directories within a single activation. You can specify multiple directories in JDeveloper as distinct from a single directory. This is applicable to both physical and logical directories.

Note:

If the inbound Oracle File Adapter is configured for polling multiple directories for incoming files, then all the top-level directories (inbound directories where the input files appear) must exist before the file reader starts polling these directories.

After selecting the inbound directory or directories, you can also specify whether the subdirectories must be processed recursively. If you check the Process Files Recursively option, then the directories would be processed recursively. By default, this option is selected, in the File Directories page, as shown in Figure 5-13.

When you choose multiple directories, the generated JCA files use semicolon(;) as the separator for these directories. However, you can change the separator to something else. If you do so, manually add DirectorySeparator="chosen separator" in the generated JCA file. For example, to use comma (,) as the separator, you must first change the separator to "," in the Physical directory and then add <property name="DirectorySeparator" value=","/>, in the JCA file.

Additionally, if you choose to process directories recursively and one or more subdirectories do not have the appropriate permissions, the inbound adapter throws an exception during processing. To ignore this exception, you must define a binding property with the name ignoreListingErrors in your composite.xml as shown in the example below.

Example - Defining a Binding Property with the name ignoreLIstingErrors

<service name="FlatStructureIn">
<interface.wsdl 
interface="http://xmlns.oracle.com/
       pcbpel/adapter/file/
       FlatStructureIn/#wsdl.inte
rface(Read_ptt)"/>
<binding.jca config="FlatStructureIn_file.jca">
<property name="ignoreListingErrors" 
                    type="xs:string" 
many="false">true</property>
</binding.jca>
</service>

Figure 5-13 The Adapter Configuration Wizard - File Directories Page

Description of Figure 5-13 follows
Description of "Figure 5-13 The Adapter Configuration Wizard - File Directories Page"

5.2.20 Append Mode

The Oracle File and FTP Adapters enable you to configure outbound interactions that append to an existing file. The Append to Existing File option enables the outbound invoke to write to the same file. There are two ways in which you can append to a file name:

  • Statically — in the JCA file for the outbound Oracle File Adapter.

  • Dynamically — using the header mechanism.

Note:

The append mode is not supported for SFTP scenarios, where instead of appending to the existing file, the file is overwritten.

When you select the Append to existing file option in the File Configuration page, the batching options such as Number of Messages Equals, Elapsed Time Exceeds, File Size Exceeds options are disabled. Figure 5-14 displays the Append to existing file option.

Figure 5-14 The Adapter Configuration Wizard - File Configuration Page

Description of Figure 5-14 follows
Description of "Figure 5-14 The Adapter Configuration Wizard - File Configuration Page"

Batching option is disabled if "Append" is chosen in the wizard. In addition, the following error message is displayed if the user specifies a dynamic file naming convention as opposed to a static file naming convention:

You cannot choose to Append Files and use a dynamic file naming convention at the same time

If you are using the "Append" functionality in Oracle FTP Adapter, ensure that your FTP server supports the "APPE" command.

5.2.21 Recursive Processing of Files Within Directories in Oracle FTP Adapter

In earlier versions of the Oracle SOA Suite, the inbound Oracle FTP Adapter used the NLST (Name List) FTP command to read a list of file names from the FTP server. However, the NLST command does not return directory names and therefore does not allow recursive processing within directories. Currently, the Oracle FTP Adapter uses the LIST command, instead.

However, the response from the LIST command is different for different FTP servers. To incorporate the subtle differences in results from the LIST command in a standard manner, the following parameters are added to the deployment descriptor for Oracle FTP Adapter:

  • defaultDateFormat: This parameter specifies the default date format value. On the FTP server, this is the value for files that are older. The default value for this parameter is MMM d yyyy as most UNIX-type FTP servers return the last modified time stamp for older files in the MMM d yyyy format. For example, Jan 31 2006.

    You can find the default date format for your FTP server by using the ls -l command by using a FTP command-line client. For example, ls -l on a vsftpd server running on Linux returns the following: 

    -rw-r--r--    1 500      500           377 Jan 22 2005 test.txt

    For Microsoft Windows NT FTP servers, the defaultDateFormat is MM-dd-yy hh:mma, for example, 03-24-09 08:06AM <DIR> oracle.

  • recentDateFormat: This parameter specifies the recent date format value. On the FTP server, this is the value for files that were recently created.

    The default value for this parameter is MMM d HH:mm as most UNIX-type FTP servers return the last modified date for recently created files in MMM d HH:mm format, for example, Jan 31 21:32.

    You can find the default date format for your FTP server by using the ls -l command from an FTP command-line client. For example, ls -l on a vsftpd server running on Linux returns the following: 

    150 Here comes the directory listing.
-rw-r--r--    1 500      500           377 Jan 30 21:32 address.txt
-rw-r--r--    1 500      500           580 Jan 3121:32 container.txt
.....................................................................................

    For Microsoft Windows NT FTP servers, the recentDateFormat parameter is in the MM-dd-yy hh:mma, format, for example, 03-24-09 08:06AM <DIR> oracle.

  • serverTimeZone: The server time zone, for example, America/Los_Angeles. If this parameter is set to blank, then the default time zone of the server running the Oracle FTP Adapter is used.

  • listParserKey: Directs the Oracle FTP Adapter on how it should parse the response from the LIST command. The default value is UNIX, in which case the Oracle FTP Adapter uses a generic parser for UNIX-like FTP servers. Apart from UNIX, the other supported values are WIN, VMS, OS2, OS400, and MVS. As the names imply, each supported value is for a specific operating system. For example for FTP Server running on Microsoft Windows, set listParserKey to WIN and for FTP Server running on IBM iSeries, set listParserKey to OS400.

    Note:

    The locale language for the FTP server can be different from the locale language for the operating system. Do not assume that the locale for the FTP server is the same locale for the operating system it is running on. You must set the serverLocaleLanguage, serverLocaleCountry, and serverLocaleVariant parameters in such cases.

  • serverLocaleLanguage: This parameter specifies the locale construct for language.

  • serverLocaleCountry: This parameter specifies the locale construct for country.

  • serverLocaleVariant: This parameter specifies the locale construct for variant.

5.2.21.1 Configure the Parameters in the Deployment Descriptor

The standard date formats of an FTP server are usually configured when the FTP server is installed. If your FTP server uses a format "MMM d yyyy" for defaultDateFormat and "MMM d HH:mm" for recentDateFormat, then your Oracle FTP Adapter must use the same formats in its corresponding deployment descriptor.

If you enter "ls -l" from a command-line FTP, then you can see the following:

200 PORT command successful. Consider using PASV.
150 Here comes the directory listing.
-rw-r--r--    1 500      500           377 Jan 22 21:32 1.txt
-rw-r--r--    1 500      500           580 Jan 22 21:32 2.txt
.................................................................................

This is the recentDateFormat parameter for your FTP server, for example MMM d HH:mm (Jan 22 21:32). Similarly, if your server has an old file, the server does not show the hour and minute part and it shows the following: 

-rw-r--r--    1 500      500           377 Jan 22 2005 test.txt

This is the default date format, for example MMM d yyyy (Jan 22 2005).

Additionally, the serverTimeZone parameter is used to by the Oracle FTP Adapter to parse time stamps for FTP server running in a specific time zone. The value for this is either an abbreviation such as "PST" or a full name such as "America/Los_Angeles".

Additionally, the FTP server might be running on a different locale. The serverLocaleLanguage, serverLocaleCountry, and serverLocaleVariant parameters are used to construct a locale from language, country, variant where

  • language is a lowercase two-letter ISO-639 code, for example, en,

  • country is an uppercase two-letter ISO-3166 code, for example, US.

  • variant is a vendor and browser-specific code.

If these locale parameters are absent, then the Oracle FTP Adapter uses the system locale to parse the time stamp.

Additionally, if the FTP server is running on a different system than the SOA suite, then you must handle the time zone differences between them. You must convert the time difference between the FTP server and the system running the Oracle FTP Adapter to milliseconds and add the value as a binding property: timestampOffset in the composite.xml.

For example, if the FTP server is six hours ahead of your local time, you must add the following endpoint property to your service or reference. See the example below.

Example - Endpoint Property to Add if FTP Server is Ahead of Local

<service name="FTPDebatchingIn">
    <interface.wsdl
interface="http://xmlns.oracle.com/pcbpel
             /adapter/ftp/FTPDebatchingIn/#wsdl.
interface(Get_ptt)"/>
    <binding.jca config="DebatchingIn_ftp.jca">
<property name=" timestampOffset" 
               type="xs:string" 
                        many="false" source="" 
override="may"> 21600000</property>
    </binding.jca>
  </service>

Some FTP servers do not work well with the LIST command. In such cases, use the NLST command for listing, but you cannot process directories recursively with NLST.

To use the NLST command, then you must add the following property to the JCA file. See the example below.

Example - Adding the NLST Property

<?xml version="1.0" encoding="UTF-8"?>
<adapter-config name="FTPDebatchingIn" 
                   adapter="Ftp Adapter"
 xmlns="http://platform.integration.oracle/
                  blocks/adapter/fw/metadata">
<connection-factory location="eis/Ftp/FtpAdapter"
                     UIincludeWildcard="*.txt"
 adapterRef=""/>
    <activation-spec 
className="oracle.tip.adapter.ftp.
                  inbound.FTPActivationSpec">
       …………………………………………..
       …………………………………………..
      <property name="UseNlst" value="true"/>
    </activation-spec>
  </endpoint-activation>
</adapter-config>

5.2.22 Securing Enterprise Information System Credentials

When a resource adapter makes an outbound connection with an Enterprise Information System (EIS), it must sign on with valid security credentials. In accordance with the J2CA 1.5 specification, Oracle WebLogic Server supports both container-managed and application-managed sign-on for outbound connections. At runtime, Oracle WebLogic Server determines the chosen sign-on mechanism, based on the information specified in either the invoking client component's deployment descriptor or the res-auth element of the resource adapter deployment descriptor. This section describes the procedure for securing the user name and password for Oracle JCA Adapters by using Oracle WebLogic Server container-managed sign-on.

Both Oracle WebLogic Server and EIS maintain independent security realms. A container-managed sign-on enables you to sign on to Oracle WebLogic Server and also be able to use applications that access EIS through a resource adapter without having to sign on separately to the EIS. Container-managed sign-on in Oracle WebLogic Server uses credential mappings. The credentials (user name/password pairs or security tokens) of Oracle WebLogic security principals (authenticated individual users or client applications) are mapped to the corresponding credentials required to access EIS. You can configure credential mappings for applicable security principals for any deployed resource adapter.

To use container-managed sign-on first you must ensure that the connection pool you use supports container-managed sign-on. You can follow these steps to turn on container-managed sign-on for an existing connection pool or create a new pool which supports container-managed sign-on.

  1. Go to the Oracle SOA installation directory where the SOA adapter .rar files are located (for example, </fmwhome/AS11gR1SOA>/soa/connectors or <C:\Oracle\Middleware\Oracle_SOA1>\soa\connectors) where you must replace the path in the brackets with an appropriate path.
  2. Make a backup copy of the adapter .rar file, for example, FtpAdapter.rar, for which the weblogic-ra.xml will be modified.
  3. Extract the weblogic-ra.xml from the .rar file and open the extracted weblogic-ra.xml with an editor.
  4. For an existing connection pool in weblogic-ra.xml, if <wls:res-auth>Container</wls:res-auth> does not exist under the <wls:connection-properties> for the connection pool, add the property to the connection pool.

    As an example, the pre-configured eis/Ftp/FtpAdapter connection pool in the FTP adapter is defined as in the example below.

    Example - Defining the Pre-Configured Connection Pool

    <wls:connection-instance> 
<wls:description>Ftp Adapter</wls:description>
<wls:jndi-name>eis/Ftp/FtpAdapter</wls:jndi-name>
<wls:connection-properties>
 <wls:res-auth>Container</wls:res-auth>
</wls:connection-properties>

    This example indicates that this pool supports container-managed sign-on.

  5. To create a new connection pool that supports container-managed sign-on, add a new connection pool instance by using an existing instance as an example. You must replace the JNDI name and/or the connection factory name with appropriate names. The following is a sample configuration of a JMS connection pool that supports container-managed sign-on.

    (The presence of java.naming.factory.initial and java.naming.provider.urlare required to turn on container-managed sign-on.

    Example - Sample Configuration of a JMS Connection Pool Supporting Container-Managed Sign-on

     <connection-instance> 
  <jndi-name>eis/jms/MyConnectionPool</jndi-name> 
    <connection-properties> 
      <properties> 
        <property> 
         <name>ConnectionFactoryLocation</name> 
           <value>jms/MyConnectionFactory</value> 
        </property> 
        <property> 
          <name>FactoryProperties</name> 
           <value>java.naming.factory.initial
               =weblogic.jndi.
                      WLInitialContextFactory;java. 
                 naming.provider.url=
                   t3://ncosmidi-us5.us.
                         mydomain.com:8001</value> 
         </property> 
         <property> 
           <name>AcknowledgeMode</name>
            <value>AUTO_ACKNOWLEDGE</value> 
         </property> 
         <property> 
           <name>IsTopic</name> 
           <value>true</value> 
         </property> 
         <property> 
          <name>IsTransacted</name> 
            <value>false</value>
         </property>
         <property> 
          <name>Username</name> 
          <value></value> 
         </property> 
         <property> 
           <name>Password</name> 
           <value></value> 
         </property> 
           </properties> 
         <res-auth>Container</res-auth>
    </connection-properties> 
 </connection-instance>
  6. Add the modified weblogic-ra.xml back to adapter .rar and make sure it replaces the existing weblogic-ra.xml in the .rar file.
  7. Proceed to the Weblogic Server Console > Deployments and select the adapter; for example, FTP Adapter or JMS Adapter. Click Update.
  8. For a new connection pool, for example, a JMS pool, open Deployments > JmsAdapter > Configuration > Outbound Connection Pools and expand oracle.tip.adapter.jms.IJmsConnectionFactory to verify the new connection pool is present.

    After these steps, you can configure credential mapping for the corresponding pool by performing the following procedure using the Oracle WebLogic Server console. To do so:

  9. Log in to the Oracle WebLogic Server Administration Console.

    Click Deployments in the Domain Structure pane. The deployed applications and adapters are displayed, as shown in Figure 5-15.

    Figure 5-15 The Oracle WebLogic Server Administration Console - Summary of Deployments Page

    Description of Figure 5-15 follows
    Description of "Figure 5-15 The Oracle WebLogic Server Administration Console - Summary of Deployments Page"
  10. Click the adapter for which you must create the security credentials. For example, click FtpAdapter. The Settings for FtpAdapter page is displayed, as shown in Figure 5-16.

    Figure 5-16 The Oracle WebLogic Server Administration Console - Settings for FTPAdapter Page

    Description of Figure 5-16 follows
    Description of "Figure 5-16 The Oracle WebLogic Server Administration Console - Settings for FTPAdapter Page"
  11. Click the Security tab. The Settings for FTP Adapter page with the Stand-Alone Resource Adapter Roles pane displayed, as shown in Figure 5-17

    Figure 5-17 The Oracle WebLogic Server Administration Console - Settings for FTPAdapter Page

    Description of Figure 5-17 follows
    Description of "Figure 5-17 The Oracle WebLogic Server Administration Console - Settings for FTPAdapter Page"
  12. Click the Credential Mappings tab.
  13. Click New in the Credential Mappings pane. The Create a New Security Credential Mapping page is displayed, as shown in Figure 5-18.

    Figure 5-18 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page

    Description of Figure 5-18 follows
    Description of "Figure 5-18 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page"
  14. Select eis/Ftp/FtpAdapter (JNDI for Oracle FTP Adapter) to create a security credential map entry for Oracle FTP Adapter, as shown in Figure 5-19.

    Figure 5-19 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page

    Description of Figure 5-19 follows
    Description of "Figure 5-19 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page"
  15. Click Next. The Create a New Security Credential Mapping – WebLogic Server User page is displayed, as shown in Figure 5-20.

    Figure 5-20 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page

    Description of Figure 5-20 follows
    Description of "Figure 5-20 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page"

    Note:

    Credential mapping is not supported for the User for creating initial connections and Unauthenticated WLS User options.

  16. Select Configured User Name and enter the Oracle WebLogic Server user name in the WebLogic Server User Name field, as shown in Figure 5-21. For example, enter weblogic, which is the default user name. Depending on your configuration, in some cases, you might select Default User if Configured User Name does not work.

    Figure 5-21 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page

    Description of Figure 5-21 follows
    Description of "Figure 5-21 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page"
  17. Click Next. The Create a New Security Credential Mapping – EIS User Name and Password page is displayed.
  18. Enter the EIS user name in the EIS User Name field, the EIS password in the EIS Password field, and then reenter the EIS password in the Confirm Password field to confirm the password, as shown in Figure 5-22.

    Figure 5-22 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page

    Description of Figure 5-22 follows
    Description of "Figure 5-22 The Oracle WebLogic Server Administration Console - Create a New Security Credential Mapping Page"
  19. Click Finish. The new security credential mapping is created, as shown in Figure 5-23.

    Figure 5-23 The Oracle WebLogic Server Administration Console - Settings for FTPAdapter Page

    Description of Figure 5-23 follows
    Description of "Figure 5-23 The Oracle WebLogic Server Administration Console - Settings for FTPAdapter Page"

5.3 Oracle File and FTP Adapter Concepts

Get an overview of the Oracle File and FTP Adapters concepts.

5.3.1 Oracle File Adapter Read File Concepts

In the inbound direction, the Oracle 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 Oracle File Adapter. You use the Adapter Configuration Wizard to configure the Oracle File Adapter for use with a BPEL process or a Mediator. Configuring the Oracle File Adapter creates an inbound WSDL and JCA file pair.

The following sections describe the Oracle File Adapter read file concepts:

5.3.1.1 Inbound Operation

For inbound operations with the Oracle File Adapter, select the Read File operation, as shown in Figure 5-24.

Figure 5-24 Selecting the Read File Operation

Description of Figure 5-24 follows
Description of "Figure 5-24 Selecting the Read File Operation"
5.3.1.2 Inbound File Directory Specifications

The File Directories page of the Adapter Configuration Wizard shown in Figure 5-25 enables you to specify information about the directory to use for reading inbound files and the directories in which to place successfully processed files. You can choose to process files recursively within directories. You can also specify multiple directories.

Figure 5-25 The Adapter Configuration Wizard - Specifying Incoming Files

Description of Figure 5-25 follows
Description of "Figure 5-25 The Adapter Configuration Wizard - Specifying Incoming Files"

The following sections describe the file directory information to specify:

5.3.1.2.1 Specifying Inbound Physical or Logical Directory Paths in SOA Composite

You can specify inbound directory names as physical or logical paths in the composite involving Oracle BPEL PM and Mediator. Physical paths are values such as c:\inputDir.

Note:

If the inbound Oracle File Adapter is configured for polling multiple directories for incoming files, then all the top-level directories (inbound directories where the input file appears) must exist before the file reader starts polling these directories.

In the composite, logical properties are specified in the inbound JCA file and their logical-physical mapping is resolved by using binding properties. You specify the logical parameters once at design time, and you can later modify the physical directory name as required.

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

Example - Generated Inbound .jca File

<?xml version="1.0" encoding="UTF-8"?>
<adapter-config name="FlatStructureIn" 
                 adapter="File Adapter" 
xmlns="http://platform.integration.oracle/
             blocks/adapter/fw/metadata">
  
  <connection-factory location="eis/FileAdapter"
           UIincludeWildcard="*.txt" 
adapterRef=""/>
  <endpoint-activation operation="Read">
    <activation-spec 
className="oracle.tip.adapter.file.
                     inbound.FileActivationSpec">
      <property name="UseHeaders" value="false"/>
      <property name="LogicalDirectory" 
                   value="InputFileDir"/>
      <property name="Recursive" value="true"/>
      <property name="DeleteFile" value="true"/>
      <property name="IncludeFiles" value=".*\.txt"/>
      <property name="PollingFrequency" value="10"/>
      <property name="MinimumAge" value="0"/>
      <property name="OpaqueSchema" value="false"/>
    </activation-spec>
  </endpoint-activation>

</adapter-config>

In the composite.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. See the example below.

Example - Providing the Directory Path of the Corresponding ActivationSpec or InteractionSpec

<service name="FlatStructureIn">
    <interface.wsdl 
     interface="http://xmlns.oracle.com/pcbpel/
               adapter/file/FlatStructureIn/#wsdl.
     interface(Read_ptt)"/>
    <binding.jca config="FlatStructureIn_file.jca">
<property name=" InputFileDir" type="xs:string"
                        many="false" source="" 
      override="may"> /home/user/inputDir</property>
 
 </binding.jca>
</service>
5.3.1.2.2 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 SOA Composite.

5.3.1.2.3 Deleting Files After Retrieval

This option enables you to specify whether 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 been processed but the modification date remains the same, then that file is not retrieved.

5.3.1.3 File Matching and Batch Processing

The File Filtering page of the Adapter Configuration Wizard shown in Figure 5-26 enables you to specify details about the files to retrieve or ignore.

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

Figure 5-26 The Adapter Configuration Wizard-File Filtering Page

Description of Figure 5-26 follows
Description of "Figure 5-26 The Adapter Configuration Wizard-File Filtering Page"

The following sections describe the file filtering information to specify:

5.3.1.3.1 Specifying a Naming Pattern

Specify the naming convention that the Oracle 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 Oracle 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.

Note:

  • 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 file name, 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 backslash(\), slash (/), colon (:), asterisk (*), left angle bracket (<), right angle bracket (>), or vertical bar(|).

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

For the inbound Oracle 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 no abcd*.txt files are received.

Note:

You must enter a name pattern in the Include Files with Name Pattern field and not leave it empty. Otherwise, the inbound adapter service reads all the files present in the inbound directory, resulting in incorrect results.

Table 5-4 lists details of Java regex constructs.

Note:

Do not begin JDK regex pattern names with the following characters: plus sign (+), question mark (?), or asterisk (*).

Table 5-4 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 new line (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 white space 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, see

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

5.3.1.3.3 File Include and Exclude

The FileList operation does not expose the java.file.IncludeFiles property. This property is configured while designing the adapter interaction and cannot be overridden through headers, as shown in the example tomorrow.

Example - Overriding the FileList Operation

<adapter-config name="ListFiles" adapter="File Adapter"    xmlns="http://platform.integration.oracle
                   /blocks/adapter/fw/metadata">
   <connection-factory location="eis/FileAdapter"
                    UIincludeWildcard="*.txt" 
                        adapterRef=""/>
    <endpoint-interaction portType="FileListing_ptt" 
                               operation="FileListing">
    <interaction-spec className=
                    "oracle.tip.adapter.file.outbound.
                     FileListInteractionSpec">
        <property name="PhysicalDirectory" 
                             value="%INP_DIR%"/>
        <property name="PhysicalDirectory" 
                           value="%INP_DIR%"/>
        <property name="Recursive" value="true"/>
             <property name="Recursive" 
                            value="true"/>
             <property name="IncludeFiles"
                        value=".*\.txt"/>
   </interaction-spec>
   </endpoint-interaction>
</adapter-config>

In this example, after you set the IncludeFiles, they cannot be changed.

5.3.1.3.4 Debatching Messages

You can select whether incoming files have multiple messages, and specify the number of messages in one batch file to publish. When the file contains message with repeating elements, you can choose to publish the message in a specific number of batches. Refer to Figure 5-26.

When a file contains multiple messages and this check box is selected, this is referred to as debatching. Nondebatching is applied when the file contains only a single message and the check box is not selected. Debatching is supported for native and XML files.

5.3.1.4 File Polling

The File Polling page of the Adapter Configuration Wizard shown in Figure 5-27 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 polling parameter 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 5-27 The Adapter Configuration Wizard-File Polling Page

Description of Figure 5-27 follows
Description of "Figure 5-27 The Adapter Configuration Wizard-File Polling Page"

Note:

You must not manually change the value of polling parameters in JCA files. You must use the Adapter Configuration Wizard to modify this parameter.

5.3.1.4.1 Using Trigger Files

By default, polling by inbound Oracle File and FTP Adapters start as soon as the endpoint is activated. However, to obtain more control over polling, you can use a file-based trigger. Once the Oracle File or FTP Adapter finds the specified trigger file in a local or remote directory, it starts polling for the files in the inbound directory.

For example, a BPEL process is writing files to a directory and a second BPEL process is polling the same directory for files. To have the second process start polling the directory only after the first process has written all the files, you can use a trigger file. You can configure the first process to create a trigger file at the end. The second process starts polling the inbound directory after it finds the trigger file.

Note:

The lifecycle of the trigger file is not managed by the adapter. The trigger file must be managed externally. For example, un-trigger the endpoint, delete the trigger file using the external application, and either specify TriggerFileStrategy as EndpointActivation or EveryTime.

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 page shown in Figure 5-26.

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

Table 5-5 lists the parameters that you must specify in the inbound service JCA file:

Table 5-5 Trigger File Parameters

Parameter Description Example

TriggerFilePhysicalDirectory

or

TriggerFileLogicalDirectory

The physical or logical name of the directory in which the Oracle File and FTP Adapters look for the trigger file.

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

TriggerFilePhysicalDirectory="C:\foo"

TriggerFileLogicalDirectory= "TriggerFileDir"

TriggerFile

The name of the trigger file.

TriggerFile="Purchaseorder.trg"

TriggerFileStrategy

Strategy that is used as the triggering mechanism. The value can be:

EndpointActivation: The adapter looks for the trigger file every time the composite is activated. Note: The composite gets activated every time you start the container or redeploy the application, or retire or activate the composite application from Fusion Middleware Control.

Every time you restart the container, the composite application is not triggered until it sees the trigger file in the specified directory.

OnceOnly: The adapter looks for the trigger file only once in its lifetime. After it finds the trigger file, it remember that across restarts and redeployments.

EveryTime: The adapter looks for the trigger file on each polling cycle.The default value for TriggerFileStrategy is EndpointActivation.

TriggerFileStrategy="EndpointActivation "

The following is a sample JCA file for the inbound service:

Example - Sample .jca File for the Inbound Service

<?xml version="1.0" encoding="UTF-8"?>
<adapter-config name="FlatStructureIn" adapter="File Adapter" 
  xmlns="http://platform.integration.oracle/
                  blocks/adapter/fw/metadata">
 
  <connection-factory 
                 location="eis/FileAdapter"
    UIincludeWildcard="*.txt" 
adapterRef=""/>
  <endpoint-activation operation="Read">
    <activation-spec className=
                 "oracle.tip.adapter.file.
       inbound.FileActivationSpec">
       <property.../>
       <property name=
                "TriggerFilePhysicalDirectory" 
             value="/tmp/flat/ArchiveDir"/>
    </activation-spec>
</endpoint-activation>
 
</adapter-config>
5.3.1.5 Postprocessing

The Oracle File Adapter supports several postprocessing options. After processing the file, files are deleted if specified in the File Polling page shown in Figure 5-27. Files can also be moved to a completion (archive) directory if specified in the File Directories page shown in Figure 5-25.

5.3.1.6 Native Data Translation

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

Figure 5-28 Specifying the Schema - Messages Page

Description of Figure 5-28 follows
Description of "Figure 5-28 Specifying the Schema - Messages Page"

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. 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-delimited value (CSV), fixed-length, DTD, and COBOL Copybook. After the native schema file is created, the Messages page is displayed, with the Schema File URL and Schema Element fields filled in. For more information, see Supported File Formats.

Note:

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

5.3.1.7 Inbound Service

When you finish configuring the Oracle File Adapter, a JCA file is generated for the inbound service. The file is named after the service name you specified on the Service Name page of the Adapter Configuration Wizard. You can rerun the wizard later to change your operation definitions.

The ActivationSpec parameter holds the inbound configuration information. The ActivationSpec and a set of inbound Oracle File Adapter properties are part of the inbound JCA file.

Table 5-6 lists the properties of a sample inbound JCA file.

Table 5-6 Sample JCA Properties for Inbound Service

Property Sample Value

UseHeaders

true

PhysicalDirectory

/tmp/opaque/in

Recursive

true

DeleteFile

false

IncludeFiles

.*\.xml

PollingFrequency

1

MinimumAge

0

The ActivationSpec property values are specified in the Adapter Configuration Wizard during design time and, as shown in Table 5-6. The inbound Oracle File Adapter uses the following configuration properties:

  • PollingFrequency

  • MinimumAge

  • PhysicalDirectory

  • LogicalDirectory

  • PublishSize

  • PhysicalArchiveDirectory

  • LogicalArchiveDirectory

  • IncludeFiles

  • ExcludeFiles

  • UseHeaders

  • ListSorter

  • ThreadCount

  • Recursive

  • MaxRaiseSize

For a description of these configuration properties, see Appendix A of this book.

5.3.1.8 Inbound Headers

Apart from the payload, Oracle File Adapter publishes the following header metadata, from the inbound service, as shown in Figure 5-29:

  • jca.file.FileName: file name

  • jca.file.Directory: directory name

  • jca.file.Batch: a unique name for a batch in case of debatching

  • jca.file.BatchIndex: the batch index for each message within the batch for debatching

  • jca.file.Size: the file size

  • jca.file.LastModifiedTime: the last modified time for the file

Figure 5-29 The Invoke Dialog

Description of Figure 5-29 follows
Description of "Figure 5-29 The Invoke Dialog"

5.3.2 Oracle File Adapter Write File Concepts

In the outbound direction, the Oracle File Adapter receives messages from the service engine and writes the messages to a file in a file system. This section provides an overview of the outbound file writing capabilities of the Oracle File Adapter. You use the Adapter Configuration Wizard to configure the Oracle File Adapter for use with a BPEL process or a Mediator Service. This creates an outbound WSDL and a JCA file pair.

This section includes the following topics:

5.3.2.1 Outbound Operation

For outbound operations with the Oracle File Adapter, select the Write File operation, as shown in Figure 5-30.

Figure 5-30 Selecting the Write File Operation

Description of Figure 5-30 follows
Description of "Figure 5-30 Selecting the Write File Operation"

The Add Output Header check box is visible when you select File Write. When you select this check box, the adapter WSDL has an output message pointing to a header schema, shown by the bold highlight.

Example - Adapter WSDL with Output Message Pointing to the Schema

 <wsdl:definitions name="fileout3"
  targetNamespace="http://xmlns.oracle.com/pcbpel
           /adapter/file/SOAApp1/NewJCAFmwk/     
                   fileout3"
    xmlns:jca="http://xmlns.
                   oracle.com/pcbpel/wsdl/jca/"
xmlns:FILEAPP="http://xmlns.oracle.com
                    /pcbpel/adapter/file/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://xmlns.oracle.com/pcbpel
             /adapter/file/SOAApp1/NewJCAFmwk/
                 fileout3"
xmlns:plt="http://schemas.xmlsoap.org/ws
              /2003/05/partner-link/">"
xmlns:opaque=
    "http://xmlns.oracle.com/
    pcbpel/adapter/opaque/"
<plt:role name="Write_role" >
  <plt:portType name="tns:Write_ptt" />
  </plt:role>
</plt:partnerLinkType>"
<wsdl:types>
<schema TargetNamespace=
         "http://xlmns.oracle.com/pcbpel/
              adapter/opaque/"
   xmlns:opaque="http://xmlns.oracle.com
                       /pcbpel/adapter/opaque/"
      xmlns="http://www.w3.org/2001/XMLSchema" >
   <element name="opaqueElement"
                    type="base64Binary" />
</schema>
<schema targetNamespace=
        "http://xmlns.oracle.com/pcbpel/
          adapter/file/"
xmlns="http://www.w3.org/2001/XMLSchema"
  attributeFormDefault="qualified"
  <element name="OutboundFileHeaderType" >
   <complexType>
    <sequence>
     <element name="filename" type="string" />
     <element name="directory" type="string" />
   </sequence>
   </complexType>
   </element>
</schema>
</wsdl:types>
   <wsdl:message name="Write_msg">
   <wsdl:part name="opaque" element=
         "opaque:opaqueElement"/>
</wsdl:message>
   <wsdl:message name="Output_msg">
   <wsdl:part name="body" 
             element=
       "FILEAPP:OutboundFileHeaderType"/>
</wsdl:message>
   <wsdl:portType name="Write_ptt">
   <wsdl:operation name="Write">
     <wsdl:input message="tns:Write_msg"/>
     <wsdl:output message="tns:Output_msg"/>
       </wsdl:operation>
     </wsdl:portType>
</wsdl:definitions>

You can select the Update Output Header checkbox in edit mode, and the output message/header schema is removed from the adapter WSDL.

5.3.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 page of the Adapter Configuration Wizard shown in Figure 5-31 enables you to specify the directory for outgoing files and the outbound file naming convention.

Figure 5-31 The Adapter Configuration Wizard-Parameters for Outgoing Files

Description of Figure 5-31 follows
Description of "Figure 5-31 The Adapter Configuration Wizard-Parameters for Outgoing Files"

The following sections describe the file configuration information to specify:

5.3.2.2.1 Specifying Outbound Physical or Logical Directory Paths in Oracle BPEL PM

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 JCA file looks as follows for the logical outbound directory name OutputFileDir. See the example below.

Example - Generated JCA File for Sample Logical Outbound Directory

<?xml version="1.0" encoding="UTF-8"?>
<adapter-config name="FlatStructureOut" 
          adapter="File Adapter" 
  xmlns="http://platform.integration.
                oracle/blocks/
    adapter/fw/metadata">
  <connection-factory location="eis/FileAdapter" 
                       adapterRef=""/>
  <endpoint-interaction operation="Write">
    <interaction-spec 
className="oracle.tip.adapter.file.outbound.
                       FileInteractionSpec">
      <property name="LogicalDirectory" 
                     value="OutputFileDir"/>
      <property name="FileNamingConvention" 
              value="%yyMMddHHmmssSS%_%SEQ%_
                       %yyyyMMdd%_%SEQ%.out.%SEQ%"/>
      <property name="Append" value="false"/>
      <property name="NumberMessages" value="1"/>
      <property name="OpaqueSchema" value="false"/>
    </interaction-spec>
  </endpoint-interaction>

</adapter-config>

Select the outbound adapter in the External References swim lane in JDeveloper wizard (it is present in the composite.xml tab). Create a Binding Property in the Property Inspector for the outbound adapter (you must scroll down to find it). Once the Create Property box appears, enter OutputFileDir in the Name field and the actual output directory name, example, C:\outputDir in the Value field. The composite.xml file appears. See the example below.

Example - Creating a Property with An Outbound Directory Specified

<reference name="FlatStructureOut">
    <interface.wsdl 
interface="http://xmlns.oracle.com/pcbpel/adapter
           /file/FlatStructureOut/
                 #wsdl.interface(Write_ptt)"/>
    <binding.jca config="FlatStructureOut_file.jca">
      <property name="OutputFileDir" 
             type="xs:string" many="false"
                override="may">C:\outputDir
                        </property>
    </binding.jca>
  </reference>

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.

5.3.2.2.2 Specifying Outbound Physical or Logical Directory Paths in Mediator

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

You can specify the logical names at design time in the File Directories page shown in Figure 5-25 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 during design time.

5.3.2.2.3 Specifying a Dynamic Outbound Directory Name

For outbound operation, you can specify a dynamic outbound directory name. You can set variables to specify dynamic outbound directory names.

Example - Setting Variables to Specify Dynamic Outbound Directory Names

<?xml version="1.0" encoding="UTF-8"?>
<adapter-config name="ReadAddressChunk" 
                  adapter="File Adapter" 
xmlns="http://platform.integration.oracle
                     /blocks/adapter/fw/metadata">
  <connection-factory location="eis/FileAdapter" 
                     adapterRef=""/>
  <endpoint-interaction operation="ChunkedRead">
    <interaction-spec 
              className=
                 "oracle.tip.adapter.file.outbound.
                   ChunkedInteractionSpec">
      <property name=
              "PhysicalDirectory" value="C:\foo"/>
      <property name="FileName" value="dummy.txt"/>
      <property name="ChunkSize" value="1"/>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>

In the preceding example, in the JCA file, the physical directory is set to "C:\foo" but during runtime it is dynamically changed to the assigned value. In this example, the physical directory is dynamically changed to "C:\out".

You must perform the following steps to specify the dynamic outbound directory name:

  1. Double-click the Invoke activity.
  2. Select the Browse Variables icon.
  3. In the Variable Chooser dialog, select the Create an Object icon.
  4. Create a variable MyDir of type xsd:string, as shown in Figure 5-32.

    Figure 5-32 Create Variable Dialog

    Description of Figure 5-32 follows
    Description of "Figure 5-32 Create Variable Dialog"
  5. Drag and drop an Assign activity from the Components window in between the Receive and Invoke activities in the design area.
  6. Double-click the Assign activity and click the Copy Operation tab.
  7. Click Create and then Copy Operation. The Create Copy Operation dialog is displayed.
  8. In the Create Copy Operation dialog, select Expression from Type and specify the directory name and path, as shown in Figure 5-33. The operation writes the output file to this directory.

    Figure 5-33 Create Copy Operation Dialog

    Description of Figure 5-33 follows
    Description of "Figure 5-33 Create Copy Operation Dialog"
  9. Click OK in the Create Copy Operation dialog and then click OK in the Assign dialog. The .bpel page is displayed.
  10. Double-click the Invoke activity. The Invoke dialog is displayed.
  11. Click the Properties tab.
  12. Select the jca.file.Directory property from the Properties column and set the Value as MyDir (the directory that you created in Step 4.) Ensure that the Type column is set to input, as shown in Figure 5-34.

    Figure 5-34 The Invoke Dialog

    Description of Figure 5-34 follows
    Description of "Figure 5-34 The Invoke Dialog"

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.

5.3.2.2.4 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 in names of outgoing files, 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 5-31 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).

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.

Only one dynamic parameter is allowed in the outbound file name. That is,you cannot combine sequence number (%SEQ%) and time stamp parameters in a file name.

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 quotation marks (') to avoid interpretation. The characters "''" represent single quotation marks. All other characters are not interpreted.

The Java pattern letters are defined in Table 5-7.

Table 5-7 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 number. For parsing, the number of pattern letters is ignored unless it is required 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.

5.3.2.2.5 Specifying a Dynamic Outbound File Name

For outbound operation, you can specify a dynamic outbound file name. You can set variables to specify dynamic outbound file names.

Example - Setting Variables to Specify Dynamic Outbound File Names

<?xml version="1.0" encoding="UTF-8"?>
<adapter-config name="ReadAddressChunk" 
              adapter="File Adapter" 
xmlns="http://platform.integration.oracle/blocks
          /adapter/fw/metadata">
  <connection-factory location=
                     "eis/FileAdapter" 
          adapterRef=""/>
  <endpoint-interaction operation
                   ="ChunkedRead">
    <interaction-spec 
className="oracle.tip.adapter.file.outbound.
          ChunkedInteractionSpec">
      <property name="PhysicalDirectory"
                          value="C:\foo"/>
      <property name="FileName" 
                      value="dummy.txt"/>
      <property name="ChunkSize" value="1"/>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>

In the preceding example, in the JCA file, the physical directory is set to "C:\foo" but during runtime it is dynamically changed to the assigned value. In this example, the physical directory is dynamically changed to "C:\out". You must perform the following steps to specify the dynamic outbound directory name:

  1. Double-click the Invoke activity.
  2. Select the Browse Variables icon.
  3. In the Variable Chooser dialog, click the Create an Object icon.
  4. Create a variable file of type xsd:string, as shown in Figure 5-32.
  5. Drag and drop an Assign activity from the Components window in between the Receive and Invoke activities in the design area.
  6. Double-click the Assign activity and click the Copy Operation tab.
  7. Click Create and then Copy Operation. The Create Copy Operation dialog is displayed.
  8. In the Create Copy Operation dialog, select Expression from Type and specify the file name, as shown in Figure 5-33. The file operation writes the output file to this file.
  9. Click OK till you exit the Assign activity dialog.
  10. Double-click the Invoke activity. The Invoke dialog is displayed.
  11. Click the Properties tab.
  12. Select the jca.file.FileName property from the Properties column and set the Value as file (the file that you created in Step 4.) Ensure that the Type column is set to input, as shown in Figure 5-35.

    Figure 5-35 The Invoke Dialog

    Description of Figure 5-35 follows
    Description of "Figure 5-35 The Invoke Dialog"

Note:

When using dynamic files, 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 files.

5.3.2.2.6 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 method enables you to specify the number of messages to publish in one batch file. The following batch file settings are provided in the File Configuration page shown in Figure 5-31:

  • Number of Messages Equals

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

  • Elapsed Time Exceeds

    Specify a time which, when exceeded, causes a new outgoing file to be created.

    Note:

    The Elapsed Time Exceeds batching criteria is evaluated and a new outgoing file is created, only when an invocation happens.

    For example, if you specify that elapsed time exceeds 15 seconds, then the first message that is received is not written out, even after 15 seconds, as batching conditions are not valid. If a second message is received, then batching conditions become valid for the first one, and an output file is created when the elapsed time exceeds 15 seconds.

  • File Size Exceeds

    Specify a file size which, when equaled, causes an outgoing file to be created. For example, assume that you specify a value of 3 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.

Note:

You must not manually change the file configurations specified in the preceding list in the JCA files. You must use the Adapter Configuration Wizard to modify these configurations.

If the Oracle File Adapter encounters a problem during batching, it starts batching at the point at which it left off on recovery.

5.3.2.3 Native Data Translation

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

Figure 5-36 Specifying the Schema

Description of Figure 5-36 follows
Description of "Figure 5-36 Specifying the Schema"

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

  • Specify whether 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.

For more information about Messages page, see Native Data Translation.

5.3.2.4 Outbound Service Files

When you complete configuration of the Oracle File Adapter with the Adapter Configuration Wizard, a WSDL and a JCA file pair is generated for the outbound operation. The files are named after the service name you specified on the Service Name page of the Adapter Configuration Wizard shown in Figure 2-8. You can rerun the wizard later to change your operation definitions.

A sample outbound JCA file includes the information listed in Table 5-8:

Table 5-8 Sample JCA Properties for Outbound Service

Property Sample Value

PhysicalDirectory

/tmp/flat/OutputDir

FileNamingConvention

address-csv%SEQ%.txt

Append

true

NumberMessages

1

ConcurrentThreshold

0

OpaqueSchema

false

The outbound Oracle File Adapter uses the following configuration parameters:

  • PhysicalDirectory

  • LogicalDirectory

  • NumberMessages

  • ElapsedTime

  • FileSize

  • FileNamingConvention

  • Append

For a description of these configuration properties, see Oracle JCA Adapter Properties.

5.3.2.5 Outbound Headers

Apart from the payload, the Oracle File Adapter receives the following headers from the component: 

  • jca.file.FileName: file name

  • jca.file.Directory: directory name

5.3.3 Oracle File Adapter Synchronous Read Concepts

In the outbound direction, the Oracle File or FTP Adapter can read the content of a single file. This section provides an overview of the outbound synchronous file reading capabilities of the Oracle File Adapter. For reading a file synchronously, you select Synchronous Read File operation, as shown in Figure 5-37.

Figure 5-37 Synchronous Read Operation Page

Description of Figure 5-37 follows
Description of "Figure 5-37 Synchronous Read Operation Page"

In the outbound direction, the Oracle File/FTP Adapter enables you to read the content of a single file using the Synchronous File Read Operation. This operation now enables you to read the file as an attachment. Select the checkbox to read the file as an attachment,. The rest of the options are optional for attachments and are useful in cases where the information is required by the service engine.

Many of the pages of the Adapter Configuration Wizard are similar to the Read File operation except the File Name page. You can specify the name of the file to be read in the File Name field, as shown in Figure 5-38.

Figure 5-38 File Directories Page

Description of Figure 5-38 follows
Description of "Figure 5-38 File Directories Page"

5.3.4 Oracle File Adapter File Listing Concepts

This feature of the Oracle File Adapter lets you use a BPEL activity to retrieve a list of files from a target directory. This list of files is returned as an XML document and contains information such as file name, directory name, file size, and last modified time. This section provides an overview of the file listing capabilities of the Oracle File Adapter. You use the Adapter Configuration Wizard to configure the Oracle File Adapter for use with a BPEL process or a Mediator service. This creates an outbound WSDL and JCA file pair.

Note:

The file creation time property, creationTime, is not supported because the standard Java APIs do not provide a mechanism to retrieve the creation time. The value of the creationTime property is always displayed as 0.

For example,

<creationTime xmlns="http://xmlns.oracle.com
/pcbpel/adapter/file/FAListFiles/FAListFilesTest/ReadS/">
0</creationTime>

This section includes the following topics:

5.3.4.1 Listing Operation

For listing files, you must select the List Files operation, as shown in Figure 5-39.

Figure 5-39 List Files Operation Page

Description of Figure 5-39 follows
Description of "Figure 5-39 List Files Operation Page"
5.3.4.2 File Directory Specifications

The File Directories page of the Adapter Configuration Wizard shown in Figure 5-40 enables you to specify information about the directory to use for reading files names for the list operation. You can choose to list files recursively within directories.

Figure 5-40 The Adapter Configuration Wizard-Specifying Incoming Files

Description of Figure 5-40 follows
Description of "Figure 5-40 The Adapter Configuration Wizard-Specifying Incoming Files"

The following section describes the file directory information to specify:

5.3.4.2.1 Specifying Inbound Physical or Logical Directory Paths in SOA Composite

You can specify directory names as physical or logical paths for composites involving Oracle BPEL PM and Mediator. Physical paths are values such as C:\inputDir.

In the composite, logical properties are specified in the JCA file, and their logical-physical mapping is resolved by using binding properties. You specify the required directory once at design time, and you can later modify the directory name as required.

For example, the generated JCA file looks as follows for the logical input directory name C:\inputDir:

Example - Generated .jca file for Logical Input Directory

<adapter-config name="ListFiles"
       adapter="File Adapter" 
   xmlns="http://platform.integration.oracle
   /blocks/adapter/fw/metadata">
  
  <connection-factory location="eis/FileAdapter"
          UIincludeWildcard="*.txt" 
adapterRef=""/>
  <endpoint-interaction portType="FileListing_ptt" 
          operation="FileListing">
    <interaction-spec 
className="oracle.tip.adapter.file.
          outbound.FileListInteractionSpec">
      <property name="PhysicalDirectory" 
           value="C:\inputDir"/>
      <property name="Recursive" value="true"/>
      <property name="IncludeFiles" value=".*\.txt"/>
    </interaction-spec>
  </endpoint-interaction>
 
</adapter-config>
5.3.4.3 File Matching

The File Filtering page of the Adapter Configuration Wizard shown in Figure 5-41 enables you to specify details about the files to retrieve or ignore.

The Oracle File Adapter acts as a file listener and polls the specified directory on a local or remote file system and looks for files that match specified naming criteria.

Figure 5-41 The Adapter Configuration Wizard - File Filtering

Description of Figure 5-41 follows
Description of "Figure 5-41 The Adapter Configuration Wizard - File Filtering"

The following sections describe the file filtering information to specify:

5.3.4.3.1 Specifying a Naming Pattern

Specify the naming convention that the Oracle 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 Oracle File Adapter matches the files that appear in the inbound directory.

  • File wildcards (po*.txt)

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

  • Regular expressions (po.*\.txt)

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

Note:

  • 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 file name, 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 backslash(\), slash (/), colon (:), asterisk (*), left angle bracket (<), right angle bracket (>), or vertical bar(|).

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

To have the inbound Oracle 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*.

Note:

Do not begin JDK regex pattern names with the following characters: plus sign (+), question mark (?), or asterisk (*).

For details about Java regex constructs, go to

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

Note:

Files are not read and therefore there is no native data translation.

5.3.5 Oracle FTP Adapter Get File Concepts

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

Figure 5-42 Specifying FTP Server Connection Information

Description of Figure 5-42 follows
Description of "Figure 5-42 Specifying FTP Server Connection Information"

The default adapter instance JNDI name is eis/Ftp/FtpAdapter, or use a custom name. This name connects to the FTP server during runtime.

Note:

The Oracle 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 5-43 shows this selection.

Figure 5-43 Selecting the Get File Operation

Description of Figure 5-43 follows
Description of "Figure 5-43 Selecting the Get File Operation"

The serverType property in the deployment descriptor is 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.

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. You must note that this property is used by the NXSD translator component to write the line separator during an outbound operation.

From this point onwards, pages of the Adapter Configuration Wizard for the Get File operation are the same as those for the Read File operation of the file. Table 5-9 lists the pages that are displayed and provides references to sections that describe their functionality.

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

Page See Section...

File Directories (Figure 5-25)

Inbound File Directory Specifications

File Filtering (Figure 5-26)

File Matching and Batch Processing

File Polling (Figure 5-27)

File Polling

Messages (Figure 5-28)

Native Data Translation

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

  • 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 5-44 File Modification Time

Description of Figure 5-44 follows
Description of "Figure 5-44 File Modification Time"

This page enables you to specify a method for obtaining the modification time of files on the remote FTP server:

Note:

The Oracle FTP Adapter uses the LIST command as opposed to NLST for listing and retrieves the time stamps because of which you must not specify the time formats. However, you must specify the time formats as shown if you do any of the following:

  • If you specify NLST as the listing command (either through the mapping file or the UseNlst="true" parameter in the inboundJCA file)

  • To use the File Name Substring option

This note is not applicable if your case does not fall under neither of these categories.

  • 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 JCA file includes the following parameters and values:

    <property name=" FileModificationTime " value=" FileSystem "/>
<property name=" ModificationTimeFormat" value=" 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 Oracle FTP Adapter is running to milliseconds and add the value as a binding property in the composite.xml file: 

    <binding.jca config="FlatStructureIn_file.jca">
   <property name="timestampOffset" source="" type="xs:string" many="false" 
override="may">238488888</property-->
</binding.jca>

  • 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 JCA file includes the following parameters and values:

    <property name=" FileModificationTime " value=" DirListing"/>
<property name=" ModificationTimeFormat" value="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 Oracle FTP Adapter is running to milliseconds and add the value as a binding property in the composite.xml file: 

    <binding.jca config="FlatStructureIn_file.jca">
   <property name="timestampOffset" source="" type="xs:string" many="false" 
override="may">238488888</property-->
</binding.jca>

  • 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 JCA file includes the following parameters and values:

    <property name=" FileModificationTime " value=" Filename"/>
<property name=" FileNameSubstringBegin " value="12 "/>
<property name=" FileNameSubstringEnd " value="20"/>
<property name=" ModificationTimeFormat " value=" yyyyMMdd "/>

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

See Figure 2-28 for more information about error handling.

You must also add the DefaultDateFormat and the RecentDateFormat parameters to the deployment descriptor for Oracle FTP Adapter, as shown in the following sample: 

<non-managed-connection 
managedConnectionFactoryClassName=
          "oracle.tip.adapter.ftp.
             FTPManagedConnectionFactory">
   <property name="host" value="localhost"/>
   <property name="port" value="21"/>
   <property name="username" value="****"/>
   <property name="password" value="****"/>
    <property name="listParserKey" value="UNIX"/>
    <property name="defaultDateFormat"
                   value="MMM d yyyy"/>
    <property name="recentDateFormat"
                   value="MMM d HH:mm"/>
</non-managed-connection>

For more information on the DefaultDateFormat and the RecentDateFormat parameters, refer to Recursive Processing of Files Within Directories in Oracle File and FTP Adapters.

5.3.6 Oracle FTP Adapter Put File Concepts

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

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

Figure 5-45 Selecting the Put File Operation

Description of Figure 5-45 follows
Description of "Figure 5-45 Selecting the Put File Operation"

From this point onwards, pages of the Adapter Configuration Wizard for the Put File operation are the same as those for the Write File operation of the Oracle File Adapter. Table 5-10 lists the pages that display and provide references to sections that describe their functionality.

Table 5-10 The Adapter Configuration Wizard Pages for Put File Operation

Page See Section...

File Configuration (Figure 5-31)

Outbound File Directory Creation

Messages (Figure 5-36)

Native Data Translation

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

5.3.7 Oracle FTP Adapter Synchronous Get File Concepts

In the outbound direction, the Oracle FTP Adapter works the same way as the Synchronous Read File operations of the Oracle File Adapter in that it polls and gets files from a file system and reads the current contents of the file. The major difference is that the Oracle FTP Adapter is used for remote file exchanges. Because of this polling, the Adapter Configuration Wizard asks for connection information to an FTP server to be used later. For reading a file synchronously, you select Synchronous Get File operation, as shown in Figure 5-46.

Figure 5-46 Selecting the Synchronous Get File Operation

Description of Figure 5-46 follows
Description of "Figure 5-46 Selecting the Synchronous Get File Operation"

5.3.8 Oracle FTP Adapter File Listing Concepts

The Oracle FTP Adapter file listing concepts are similar to the Oracle File Adapter file listing concepts discussed in File Listing Concepts. The Oracle FTP Adapter polls for files in a target directory and lists files from the target directory to specified FTP locations. The contents of the files are not read. This feature of the Oracle FTP Adapter lets you use an invoke activity to retrieve a list of files from a target directory. This list of files is returned as an XML document and contains information such as file name, directory name, file size, and last modified time.

Note:

The file creation time property, creationTime, is not supported for FTP because the standard Java APIs do not provide a mechanism to retrieve the creation time. The value of the creationTime property is always displayed as 0.

The creationTime property is supported for SFTP only.

You use the Adapter Configuration Wizard to configure the Oracle FTP Adapter for use with a BPEL process or a Mediator service. This creates an outbound WSDL and JCA file pair.

For listing files, you must select the List Files operation from the Operation Type page of the Adapter Configuration Wizard. In the File Directories page of the Adapter Configuration Wizard, you must specify information about the directory to use for reading file names for the list operation. You can choose to list files recursively within directories. The File Filtering page of the Adapter Configuration Wizard enables you to specify details of the files to retrieve or ignore.

The Oracle FTP Adapter acts as a listener and polls the specified directory on a local or remote file system and looks for files that match specified naming criteria.

5.3.9 File and FTP Adapter Extensions

There are four File/FTP Adapter Extensions:

  • FTP Adapter extension to the login() operation in the default FTPClient implementation.

    FTP Adapter extension to support MLSD command.

  • FTP Adapter extension to extend the Listing operation to send the MLSD command instead of the LIST command.

  • FTP Adapter extension to the FTP Store operation to send additional proprietary FTP commands to an FTP server running on an MVS platform.

Each of these extensions is discussed in detail in the File and FTP Adapter use cases.

5.4 Configuring Oracle File and FTP Adapters

Various configuration tasks for Oracle File and FTP Adapters are discussed in the following sections.

Note:

  • See File/FTP adapter Tuning and Oracle File and FTP Adapters Properties information before configuring Oracle File and FTP Adapters.

  • You can use the ftpAbsolutePathBegin parameter to indicate to the adapter whether a directory name used in any FTP command issued by the FTP adapter is an absolute directory or relative directory. If the directory name starts with the ftpAbsolutePathBegin, it is an absolute directory, otherwise it is treated as a relative directory.

Note:

Use the IP address of the host for listen instead of localhost in nodemanager.properties. If you use localhost, the SOA and MFT process cannot write and read due to permissions. For more information, see Using Node Manager

5.4.1 Configuring the Credentials for Accessing a Remote FTP Server

To access a remote FTP server, you must configure the following credentials:

  • User name: the user name to use on the remote FTP server.

  • Password: the password to use on the remote FTP server.

  • Port: 21

  • Host: the IP address of the remote FTP server.

You must configure these credentials by modifying the weblogic-ra.xml file using the Oracle WebLogic Server console.

To do so, in the Oracle WebLogic Server Admin Console:

  1. Select Deployments from the Navigation pane on the left.
  2. Select FtpAdapter from the table of Deployments shown on the right.
  3. Select the Configuration subtab for the FtpAdapter and then Outbound Connection Pools.
  4. Expand javax.resource.cci.ConnectionFactory and then select the instance that you are modifying. (For example, choose the eis/Ftp/FtpAdapter instance for the non-High Availability use case.)

5.4.2 Configuring Oracle File and FTP Adapters for High Availability

The requirements and procedure to configure the Oracle File and FTP Adapters for high availability for an active-active topology are discussed in the following sections:

5.4.2.1 Prerequisites for High Availability

Before you configure the Oracle File or FTP Adapter for high availability, you must ensure that the following prerequisites are met:

  • Clustered processes must use the same physical directory.

  • Connection-factories must specify the same shared directory as the control directory, and their names must match. For example, if the deployment descriptor for one connection factory has /shared/control_dir as the value for controlDir, then the other deployment descriptor must also have the same value.

  • Oracle File and FTP Adapters do not lock High Availability files if they are placed directly in root folder. Place the files in a sub folder under root to use the High Availability feature.

  • Fault-policies and fault-bindings must be created for remote faults to ensure that the adapter acts correctly. For more information on fault-policies and fault-bindings, see Error Handling.

  • The MaxRaiseSize property must be set in the inbound JCA file.

Note:

For large payloads, you must increase the transaction time out for the SOADataSource by adding the following: 

<xa-set-transaction-timeout>true</xa-set-transaction-timeout>
<xa-transaction-timeout>1000</xa-transaction-timeout>

Note:

For Windows platforms, you must ensure that the input and output directories are made canonical. For example, you must use C:\bpel\input instead of c:\bpel\input. Note the use of capitalized drive letter C: instead of c:.

Note:

On all platforms, you must not end input or output directory names with the Java system property file.separator value. For example, /tmp/file/in/ is invalid but /tmp/file/in is valid as in the former the file separator slash is at the end.

5.4.2.2 High Availability in Inbound Operations

The Oracle File and FTP Adapters must ensure that only one node processes a particular file in a distributed topology. You can use the database table as a coordinator to ensure that Oracle File and FTP Adapters are highly available for inbound operations.

5.4.2.2.1 Using Database Table as a Coordinator

You must use the following procedure to make an inbound Oracle File or FTP Adapter service highly available by using database table as a coordinator:

Note:

You must increase global transaction timeouts if you use database as a coordinator.

  1. Create Database Tables

    You are not required to perform this step because the database schemas are pre-created as a part of soainfra.

  2. Modify Deployment Descriptor for Oracle File Adapter

    Modify Oracle File Adapter deployment descriptor for the connection-instance corresponding to eis/HAFileAdapter from the Oracle WebLogic Server Administration Console:

    1. Log in to your Oracle WebLogic Server Administration Console. To access the console, navigate to http://servername:portnumber/console.

    2. Click Deployments in the left pane for Domain Structure.

    3. Click FileAdapter under Summary of Deployments in the right pane.

    4. Click the Configuration tab.

    5. Click the Outbound Connection Pools tab, and expand javax.resource.cci.ConnectionFactory to see the configured connection factories, as shown in Figure 5-47:

      Figure 5-47 Oracle WebLogic Server Administration Console - Settings for FileAdapter Page

      Description of Figure 5-47 follows
      Description of "Figure 5-47 Oracle WebLogic Server Administration Console - Settings for FileAdapter Page"

    6. Click eis/HAFileAdapter. The Outbound Connection Properties for the connection factory corresponding to high availability is displayed.

    7. Update the connection factory properties, as shown in Figure 5-48.

      Figure 5-48 Oracle WebLogic Server Administration Console - Settings for javax.resource.cci.ConnectionFactory Page

      Description of Figure 5-48 follows
      Description of "Figure 5-48 Oracle WebLogic Server Administration Console - Settings for javax.resource.cci.ConnectionFactory Page"

      The new parameters in connection factory for Oracle File and FTP Adapters are as follows:

      controlDir - Set it to the directory structure where you want the control files to be stored. You must set it to a shared location if multiple WebLogic Server instances run in a cluster.

      inboundDataSource - Set the value to jdbc/SOADataSource. This is the data source, where the schemas corresponding to high availability are pre-created. The pre-created schema file can be found under $BEA_HOME/AS11gR1SOA/rcu/integration/soainfra/sql/adapter/createschema_adapter_oracle.sql. To create the schemas elsewhere, use this script. You must set the inboundDataSource property accordingly if you choose a different schema.

    8. Configure BPEL Process or Mediator Scenario to use the connection factory, as shown in the following example: 

      <adapter-config name="FlatStructureIn" 
                     adapter="File Adapter" 
xmlns="http://platform.integration.                oracle/blocks/adapter/fw/metadata">
  <connection-factory location=
                      "eis/HAFileAdapter" 
UIincludeWildcard="*.txt" adapterRef=""/>
  <endpoint-activation portType="Read_ptt"
                           operation="Read">
    <activation-spec 
className="oracle.tip.adapter.                   file.inbound.FileActivationSpec"../>
      <property../>
      <property../>
    </activation-spec>
  </endpoint-activation>
</adapter-config>

      Note:

      The location attribute is set to eis/HAFileAdapter for the connection factory.

5.4.2.3 High Availability in Outbound Operations

The Oracle File and FTP Adapters must ensure that if multiple references write to the same directory, then these do not overwrite each other. The following locking capabilities you can use to make Oracle File and FTP Adapters highly available for outbound operations:

  • Database mutex

  • User-defined mutex

5.4.2.3.1 Using a Database Mutex

You must use the following procedure to make an outbound Oracle File or FTP Adapter service highly available by using database table as a coordinator:

Note:

You must increase global transaction timeouts if you use the database as a coordinator.

  1. Create Database Tables

    You are not required to perform this step as the database schemas are precreated as a part of soainfra.

  2. Modify Deployment Descriptor for Oracle File Adapter

    Modify Oracle File Adapter deployment descriptor for the connection-instance corresponding to eis/HAFileAdapter from the Oracle WebLogic Server Administration Console:

    1. Log in to your Oracle WebLogic Server Administration Console. To access the console, navigate to http://servername:portnumber/console.

    2. Click Deployments in the left pane for Domain Structure.

    3. Click FileAdapter under Summary of Deployments in the right pane.

    4. Click the Configuration tab.

    5. Click the Outbound Connection Pools tab, and expand javax.resource.cci.ConnectionFactory to see the configured connection factories, as shown in Figure 5-47.

    6. Click eis/HAFileAdapter. The Outbound Connection Properties page is displayed with the connection factory corresponding to high availability.

    7. Update the connection factory properties, as shown in Figure 5-49.

      Figure 5-49 Oracle WebLogic Server Administration Console - Settings for javax.resource.cci.Connectionfactory Page

      Description of Figure 5-49 follows
      Description of "Figure 5-49 Oracle WebLogic Server Administration Console - Settings for javax.resource.cci.Connectionfactory Page"

      The new parameters in connection factory for Oracle File and FTP Adapters are as follows:

      controlDir - Set it to the directory structure where you want the control files to be stored. You must set it to a shared location if multiple WebLogic Server instances run in a cluster.

      inboundDataSource - Set the value to jdbc/SOADataSource. This is the data source, where the schemas corresponding to high availability are precreated. The precreated schemas can be found under $BEA_HOME/AS11gR1SOA/rcu/integration/soainfra/sql/adapter/createschema_adapter_oracle.sql. To create the schemas elsewhere, use this script. You must set the inboundDataSource property accordingly if you choose a different schema.

      outboundDataSource - Set the value to jdbc/SOADataSource. This is the data source where the schemas corresponding to high availability are precreated. The precreated schemas can be found under $BEA_HOME/AS11gR1SOA/rcu/integration/soainfra/sql/adapter/createschema_adapter_oracle.sql. To create the schemas elsewhere, use this script. You must set the outboundDataSource property if you choose to do so.

      outboundLockTypeForWrite - Set the value to oracle if you are using Oracle Database. By default the Oracle File and FTP Adapters use an in-memory mutex to lock outbound write operations. You must choose from the following values for synchronizing write operations:

      memory - The Oracle File and FTP Adapters use an in-memory mutex to synchronize access to the file system.

      oracle - The adapter uses the Oracle Database sequence.

      db - The adapter uses a precreated database table (FILEADAPTER_MUTEX) as the locking mechanism. You must use this option only if you are using a schema other than the Oracle Database schema.

      user-defined - The adapter uses a user-defined mutex. To configure the user-defined mutex, you must implement the mutex interface oracle.tip.adapter.file.Mutex and then configure a new binding-property with the name oracle.tip.adapter.file.mutex and value as the fully qualified class name for the mutex for the outbound reference.

    8. Configure BPEL Process or Mediator Scenario to use the connection factory, as shown in the following example: 

      <adapter-config name="FlatStructureOut" adapter="File Adapter" xmlns="http://platform.integration.                        oracle/blocks/adapter/fw/metadata">
  <connection-factory                    location="eis/HAFileAdapter" adapterRef=""/>
  <endpoint-interaction portType="Write_ptt" operation="Write">
<interaction-spec 
className="oracle.tip.adapter.file.outbound                             .FileInteractionSpec">
      <property../>
      <property../>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>

      Note:

      The location attribute is set to eis/HAFileAdapter for the connection factory.

      You can change the connection-factory location dynamically using JCA header properties in both BPEL as well as Mediator service engines. To dynamically set FTP JCA connection factory parameters, either remove the location (jndi) or give an invalid value (non existing jndi). This happens because, in non-managed connection factory when location=<jndi> is specified, the parameters defined in the outbound connections jndi get higher precedence. That means, the values that are specified in .jca will not take effect.

Note:

When database network connection fails, HAFileAdapter encounters Unable to acquire mutex for interaction and Unable to acquire lock on resource exceptions. These exceptions, however, do not have any functional impact.

5.4.3 Using Secure FTP with the Oracle FTP Adapter

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

This section includes the following topics:

5.4.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 for 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, you use openSSL to create a certificate for the server. Every client trusts a few parties, to begin with. If the server is one of these trusted parties, or if the server's certificate was issued by one of these parties, then 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 5-50, the server's certificate is directly imported into the client's certificate store as a trusted certificate.

Figure 5-50 Establishing Trust

Description of Figure 5-50 follows
Description of "Figure 5-50 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 client typically does this by 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 by using its private key and subsequently uses it to encrypt file data before sending it to the client.

5.4.3.2 Installing and Configuring FTP Over SSL on Solaris and Linux

The following subsections describe how to install and configure secure FTP for Solaris and Linux:

5.4.3.2.1 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 or Linux host to be used 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 you are not using it):
    sh
  9. Configure and export the PATH variable:
    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
5.4.3.2.2 Installing and Configuring vsftpd

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

  1. Go to the following location:
    ftp://vsftpd.beasts.org/users/cevans/
  2. Download vsftpd-2.0.5 (You must have the tar and signature file (.asc file)). For example:
    [BINARY]     vsftpd-2.0.5.tar.gz. . . . . . . . . . .    [Mar 19 21:26]    149K
[FILE]       vsftpd-2.0.5.tar.gz.asc. . . . . . . . .    [Mar 19 21:26]    189B
  3. Unzip the following file using gunzip. 
    gunzip vsftpd-2.0.5.tar.gz
  4. Unzip the tar file:
    tar xvf vsftpd-2.0.5.tar
  5. Change directories to the following location:
    cd vsftpd-2.0.5
  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.5 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.5 directory:
    ./vsftpd
5.4.3.2.3 Setting Up the Oracle FTP Adapter

Perform the following tasks to set up the Oracle FTP Adapter:

  1. On your Solaris or Linux 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 Oracle FTP Adapter deployment descriptor from the Oracle WebLogic Server Administration Console.
    Where... Is...

    useFtps

    Set to True. This setting is required to use FTP over SSL. The default is False.

    channelMask

    Which channel will be using SSL encryption. Possible values are:

    • both (default): both the control channel and data channel will be encrypted
    • control: the control channel will be encrypted.
    • data: the data channel will be encrypted

    If the FTP server allows, you can set channelMask to control if the files being transferred are already encrypted.

    securePort

    The port for FTP over SSL. The default is 990.

    keystoreProviderName

    The keystore provider class. The default is oracle.security.pki.OraclePKIProvider.

    keystoreType

    The keystore type. The default is PKCS12.

    keystoreAlgorithm

    The keystore algorithm. The default is OracleX509.

    enableCipherSuits

    List of comma separated cipher suites. The default is blank, in which case the default list of cipher suites are used. For most cases, you are not required to change this.

    pkiProvider

    The PKI provider name. The default is OraclePKI.

    jsseProvider

    The JSSE provider name. The default is OracleJSSE.

    Notes:

    • The default values for keystoreAlgorithm, keystoreProviderName, jsseProvider, and pkiProvider in the preceding table may not always work. In this case, set values as shown in Table 5-11 JCA Properties for Oracle File and FTP Adapters.
    • You must specify the keystore location to use SSL. Typically in a production environment, SSL certificates must be authenticated by a Trusted Certificate Authority. See Converting the Server Key From PEM to PKCS12 Format and Configuring Oracle FTP Adapter Deployment Descriptor to Use the New Key to set up the keystore.

      Another way to set up the keystore is to use the Oracle OPSS Keystore Service. See Configuring Oracle OPSS Keystore Service in Administering Security for Oracle WebLogic Server. In this case, you must set keystoreType to KSS, and kssStoreName, kssStorePassword, and kssStripeName to match the values you have configured in Oracle OPSS Keystore Service.

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

5.4.3.3 Installing and Configuring FTP Over SSL on Windows

The FTPS feature is certified on FileZilla FTP server with OpenSSL. You must follow the procedure in the following subsections for installing and configuring OpenSSL for FileZilla on Windows:

5.4.3.3.1 Installing OpenSSL

OpenSSL is an open source implementation of the SSL protocol. OpenSSL implements basic cryptographic functions and provides utility functions. Perform the following steps to install and configure OpenSSL on the Windows host to be used as the FTP server.

  1. Go to the following URL:
  2. Download and install Visual C++ 2008 Redistributables.
  3. Download and install Win32 OpenSSL v0.9.8k Light.
5.4.3.3.2 Generating OpenSSL Server Key and Certificate

(Note that you can use FileZilla utility to generate a private key and a certificate by clicking Generate new certificate in FileZilla and skip the steps in this section. Make sure the Common Name you enter is the fully qualified host name or IP of the machine on which the FileZilla FTP server is running. You still need to perform the steps in Converting the Server Key From PEM to PKCS12 Format. However, you will use the FileZilla-generated private key and certificate files.)

To create the server key and certificate files, perform the following steps:

  1. Open the command prompt and browse to the OpenSSL\bin directory.
  2. Run the following command:
    openssl req -new -x509 -keyout mykey.pem -out mycert.pem -days 365

    A sample command output is as follows:

    C:\OpenSSL\bin>openssl req -new -x509 -keyout mykey.pem       -out mycert.pem -days 365
Loading 'screen' into random state - done
Generating a 1024 bit RSA private key
..........++++++
.......++++++
writing new private key to 'mykey.pem'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
You are about to be asked to enter information that
       will be incorporated into your certificate request.
What you are about to enter is what is called a
                      Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:CA
Locality Name (eg, city) []:Belmont
Organization Name (eg, company) 
                [Internet Widgits Pty Ltd]:Test
Organizational Unit Name (eg, section) []:Test
Common Name (eg, YOUR name) []:Test test
Email Address []:test@test.com
  3. Enter a PEM pass phrase when prompted.
  4. Re-enter PEM pass phrase entered in step 3 for verification.
  5. Enter the requested details.

    The server key (mykey.pem) and certificate (mycert.pem) are generated in the OpenSSL\bin directory.

5.4.3.3.3 Importing the Server Key and Certificate Into FileZilla Server

To import the server key and certificate into FileZilla, you must perform the following steps:

  1. Open a FileZilla Server interface from your Windows Start menu.
  2. Click Edit, and then click Settings.

    The FileZilla Server Options dialog is displayed.

  3. Click SSL/TLS settings.
  4. Enter the server key and certificate details as shown in Figure 5-51.

    Figure 5-51 The FileZilla Server Options Dialog

    Description of Figure 5-51 follows
    Description of "Figure 5-51 The FileZilla Server Options Dialog"

    Note:

    In the Key password field, you must use the PEM pass phrase generated in Step 3 of Generating OpenSSL Server Key and Certificate.

5.4.3.3.4 Converting the Server Key From PEM to PKCS12 Format

You must convert the server key and the server certificate from the PEM format to the PKCS#12 format as the Oracle FTP Adapter does not recognize the PEM format.

To convert the server key and certificate to the PKCS#12 format

  1. Open the command prompt and browse to the OpenSSL\bin directory.
  2. Run the following command:
    openssl pkcs12 -export -out mykeyz.p12 -in mycert.pem -inkey mykey.pem

    The command output is as follows:

    openssl pkcs12 -export -out mykeyz.p12 -in mycert.pem -inkey mykey.pem
Loading 'screen' into random state - done
Enter pass phrase for mykey.pem:
Enter Export Password:
Verifying - Enter Export Password:
  3. Enter a PEM pass phrase when prompted. This is the pass phrase that you created while generating OpenSSL server key and certificate in Generating OpenSSL Server Key and Certificate.
  4. Enter an export password for the PKCS#12 file.
  5. Re-enter the export password for verification.
  6. Enter the requested details.

    The mykeyz.p12 file is generated in the OpenSSL\bin directory.

  7. Copy the mykeyz.p12 file to the managed Oracle WebLogic Server instance running the Oracle FTP Adapter.

    For example:

    /scratch/$user/private/mykeyz.p12
5.4.3.3.5 Configuring Oracle FTP Adapter Deployment Descriptor to Use the New Key

You must perform the following steps to configure the Oracle FTP Adapter deployment descriptor:

  1. Navigate to http://servername:portnumber/console.
  2. Use the required credentials to open the home page of the Oracle WebLogic Server Administration Console.
  3. Select Deployments in the Domain Structure pane.

    The Oracle WebLogic Server Administration Console - Summary of Deployments page is displayed.

  4. Click FtpAdapter.

    The Oracle WebLogic Server Administration Console - Settings for FtpAdapter page is displayed.

  5. Click the Configuration tab, and then click the Outbound Connection Pools tab.

    The Outbound Connection Pool Configuration table is displayed.

  6. Select the JNDI name for the Ftp Adapter instance you configure. For example, "eis/Ftp/FtpAdapter".
  7. Configure the deployment descriptors listed in Table 5-11:

    Table 5-11 JCA Properties for Oracle File and FTP Adapters

    Property Name Property Value

    useFtps

    Set the value to true.

    walletLocation

    Set it to the location of the PKCS#12 file in the managed Oracle WebLogic Server instance: /scratch/$user/private/mykeyz.p12.

    walletPassword

    Set the value to the export password generated in step 4 of Converting the Server Key From PEM to PKCS12 Format.

    keyStoreProviderName

    Set the value to sun.security.provider.Sun

    keystoreType

    Set the value to PKCS12

    keystoreAlgorithm

    Set the value to SunX509

    pkiProvider

    Must be left blank.

    jsseProvider

    Must be left blank.

5.4.4 Using SFTP with the Oracle FTP Adapter

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

This section includes the following tasks:

5.4.4.1 SFTP Overview

FTP 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 5-52 displays the communication process between an SSH client and an SSH server. SFTP is supported in Windows and Linux.

Figure 5-52 SFTP Communication

Description of Figure 5-52 follows
Description of "Figure 5-52 SFTP Communication"

SFTP has the following features:

5.4.4.1.1 Encryption

The SSH protocol uses public key cryptography for encryption. This section explains how data is encrypted:

  1. The SSH subsystem uses 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 by using the recipient's public key. Because the recipient has the private key, it can decrypt the message by using its preferred PKI algorithm such as Rivest-Shamir-Adleman (RSA) or Digital Signature Algorithm (DSA).
5.4.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, the SSH protocol uses a mechanism known as 'known hosts' to prevent threats such as IP spoofing. When this mechanism is used, both the client and the server have to prove their identity to each other before any kind of communication exchange.

5.4.4.1.3 Integrity

The SSH protocol uses 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 Encryption prevents deliberate tampering of data during transmission.

5.4.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 to reduce network bandwidth.

5.4.4.2 Install and Configure OpenSSH for Windows

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

  1. Log in as a user with Administrator privileges.

  2. Download 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 the default value.

  14. Select the Binaries box for openssh.

  15. Click Next to start the installation.

  16. On Windows XP desktop, right -click 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 are prompted with the 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.

5.4.4.3 Set Up Oracle FTP Adapter for SFTP

To use the SFTP functionality, you must modify the deployment descriptor for Oracle FTP Adapter.

Table 5-12 lists the properties for which you must specify a value in the deployment descriptor. The values of these properties depend on the type of authentication and the location of OpenSSH.

Table 5-12 SFTP Properties

Property Description

useSftp

Specify true.

Mandatory: Yes

Default 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 weblogic-ra.xml file are used. Ensure that there is a Windows user with the same name and password as specified in the weblogic-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

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

preferred CompressionAlgorithm

Specify none or zlib.

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

Mandatory: No

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

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

privateKeyFile

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

Mandatory: No

preferredCipherSuite

Specify a cipher from the following list:

  • twofish192-cbc

  • cast128-cbc

  • twofish256-cbc

  • aes128-cbc

  • twofish128-cbc

  • 3des-cbc

  • blowfish-cbc

  • aes256-cbc

  • aes192-cbc

Mandatory: No

Default value: blowfish-cbc

transportProvider

Specify socket or HTTP.

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

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

  • proxyHost

  • proxyPort

  • useProxy

Mandatory: Yes

5.4.4.3.1 Configuring Oracle FTP Adapter for Password Authentication

To set up the Oracle FTP Adapter for password authentication, the deployment descriptor for Oracle FTP Adapter must specify the values of the properties listed in Table 5-12. Ensure that the authenticationType property is set to password.

Specify the following properties and values listed in Table 5-13:

Table 5-13 Sample SFTP Properties and Values

Property Value

useSftp

true

authenticationType

PASSWORD

preferredKey ExchangeAlgorithm

diffie-hellman-group1-sha1

preferred CompressionAlgorithm

none

preferred DataIntegrityAlgorithm

hmac-md5

preferredPKIAlgorithm

ssh-rsa

privateKeyFile

-

preferredCipherSuite

blowfish-cbc

transportProvider

socket
5.4.4.3.2 Configuring Oracle FTP Adapter for Public Key Authentication

For public key authentication, you must first configure OpenSSH and then set up the Oracle FTP Adapter.

The Oracle FTP Adapter setup depends if the OpenSSH is running inside a firewall or outside a firewall.

If OpenSSH is running inside the firewall, then see the following sections:

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

5.4.4.3.3 Configuring OpenSSH for Public-Key Authentication

Perform the following steps:

  1. Go to the C:\cygwin\etc directory. If required, configure the sshd_config file to force public key authentication. For more information, see openssh help or manual.
  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 in a secured location such as C:\my-secured-folder\. The Oracle FTP Adapter configuration refers to this private key file.
  10. Restart the OpenSSH server by running the following commands:
    net stop sshd
net start sshd
5.4.4.3.4 Configuring Oracle FTP Adapter for Public Key Authentication with OpenSSH Running Inside a Firewall

To set up the Oracle FTP Adapter for public key authentication, you must specify the values of the parameters listed in Table 5-12 in the deployment descriptor. Ensure that the authenticationType parameter is set to publickey and the transportProvider parameter is set to socket. The privateKeyFile parameters should contain the location of the private key file.

A sample list of public key authentication properties and their values is shown in Table 5-14.

Table 5-14 Sample SFTP Properties and Values

Property Value

useSftp

true

authenticationType

publickey

preferredKey ExchangeAlgorithm

diffie-hellman-group1-sha1

preferred CompressionAlgorithm

none

preferred DataIntegrityAlgorithm

hmac-md5

preferredPKIAlgorithm

ssh-rsa

privateKeyFile

C:\my-secured-folder\id_rsa

preferredCipherSuite

blowfish-cbc

transportProvider

socket

Note:

If the private key file which is configured with privateKeyFile property is protected by a passphrase, enter the passphrase using the Password property. The PassPhrase property is used for configuring password for the MultilevelAuthentication property.
5.4.4.3.5 Configuring Oracle FTP Adapter for Public Key Authentication with OpenSSH Running Outside a Firewall

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

  1. In the deployment descriptor for Oracle FTP Adapter, you must specify the values of the properties listed in Table 5-12 in the deployment descriptor for Oracle FTP Adapter. Ensure that the authenticationType property is set to publickey and the transportProvider property is set to HTTP. The privateKeyFile property contains the location of the private key file.
  2. In the deployment descriptor for Oracle FTP Adapter, also specify the following proxy-related properties:

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

A sample list with public key authentication properties and proxy properties is shown in Table 5-15.

Table 5-15 Sample SFTP Properties and Values

Property Value

proxyHost

proxy.host.com

proxyPort

80

proxyUsername

anonymous

proxyPassword

tiger@scott.com

useProxy

true

useSftp

true

authenticationType

publickey

preferredKey ExchangeAlgorithm

diffie-hellman-group1-sha1

preferred CompressionAlgorithm

none

preferred DataIntegrityAlgorithm

hmac-md5

preferredPKIAlgorithm

ssh-rsa

privateKeyFile

C:\my-secured-folder\id_rsa

preferredCipherSuite

blowfish-cbc

transportProvider

HTTP

Note:

If the private key file which is configured with privateKeyFile property is protected by a passphrase, enter the passphrase using the Password property. The PassPhrase property is used for configuring password for the MultilevelAuthentication property.
5.4.4.3.6 Configuring for WINSSHD Servers

For SFTP adapter to work with WINSSHD server, configure IgnorePermissionsOnFile property as true on the connection factory.

To configure the IgnorePermissionsOnFile property:

  1. Log in to the WebLogic Servicer console.
  2. Navigate to Deployments, Ftp Adapter, Configuration, Outbound Connection Pools.
  3. Expand javax.resource.cci.ConnectionFactory.
  4. Click on the corresponding JNDI.
  5. Search for ignorePermissionsOnFile.
  6. Change the value to true.
Redeploy the FTP Adapter to load the new configuration.

5.4.5 Enabling FIPS Compliance in Oracle File and FTP Adapters

You can enable FIPS compliance while configuring the connection factory for SFTP.

FTP Adapter supports the use of FIPS-140 validated cryptography wherever cryptography is used to implement a security function or enforce a security policy. For example encryption, decryption, signing, hashing, verification, and so on.

If you opt for FIPS compliance, the system enables FIPS mode in the Maverick client and uses the preferred key exchange algorithm and public key algorithm configured to connect to SFTP server. SFTPClient is updated to accommodate these changes.

When you enable the EnableFIPSMode connection factory property, the adapter uses enableFIPS() on Maverick. To enable EnableFIPSMode, change the value to true as shown in the following example: 

<wls:property>
	<wls:name>EnableFIPSModewls:name>EnableFIPSMode>
	<wls:value>truewls:value>true>
</wls:property>

In the SftpAdapter_FIPS connection factory, located at eis/Ftp/SftpAdapter_FIPS, the property is already set to true.

If you are using the J2SSH Maverick library from 1.4.44 version, upgrade it to 1.4.47 as FIPS Compliance is supported only on this version.

  • J2SSH Maverick library is updated under $MW_HOME/soa/soa/modules/maverick-all.jar

  • Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files are placed under jre/lib/security

The FTP Adapter relies on JDK and the current Sun JDK does not support 2048 bit ciphers. For certification, use RsaJsse as the KeyStore provider. Also add com.rsa.jsse.JsseProvider as provider to security policy file.
Set the following parameters in the connection factory:

  • KeyStoreProviderName = com.rsa.jsse.JsseProvider

  • KeyStoreType = PKCS12

  • KeystoreAlgorithm = X509

  • PkiProvider = leave blank

  • JsseProvider = RsaJsse

  • TrustManager = oracle.tip.adapter.ftp.ServerTrustManager

  • EnableFIPSMode = true

When you enable FIPS mode, select the Preferred Cipher from the list of FIPS compliant ciphers.

Table 5-16 Preferred key exchange algorithm and Public Key Algorithm with FIPS Mode Enabled and Disabled

Feature FIPS Mode Disabled FIPS Mode Enabled

Key Exchange

diffie-hellman-group14-sha1

diffie-hellman-group14-sha1 (default)

Key Exchange

diffie-hellman-group1-sha1(default)

diffie-hellman-group14-sha1 (default)

Key Exchange

diffie-hellman-group-exchange-sha1

diffie-hellman-group14-sha1 (default)

Key Exchange

diffie-hellman-group-exchange-sha256

diffie-hellman-group14-sha1 (default)

Public Key Algorithm

ssh-rsa (default)

ssh-rsa (default)

Public Key Algorithm

ssh-dss

ssh-rsa (default)

Public Key Algorithm

x509v3-sign-rsa

ssh-rsa (default)

Public Key Algorithm

x509v3-sign-dss

ssh-rsa (default)

Public Key Algorithm

x509v3-sign-rsa-sha1

ssh-rsa (default)

For more information, see FIPS 140 Support in Oracle Fusion Middleware in Administering Oracle Fusion Middleware.

5.4.6 Configuring Oracle FTP Adapter for HTTP Proxy

The Oracle 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 Oracle FTP Adapter for running in plain FTP mode and SFTP mode. It contains following sections:

5.4.6.1 Configuring for Plain FTP Mode

For running the Oracle FTP Adapter in plain FTP mode, you must specify the value of certain parameters in the Oracle FTP Adapter deployment descriptor. Table 5-17 lists the properties that you must modify.

Table 5-17 Plain FTP Mode Properties

Property Description

host

The remote FTP server name.

port

The FTP control port number.

username

The FTP user name.

password

The FTP password.

proxyHost

The proxy host name.

proxyPort

The proxy port number.

proxyUsername

The proxy user name.

proxyPassword

The proxy password.

proxyType

The proxy type. Only HTTP proxy type is supported.

proxyDefinitionFile

The absolute path of the proxy definition file.

This parameter is not mandatary.

See Proxy Definition File for more information.

useProxy

Specify true to use proxy.

A sample list of Oracle FTP Adapter descriptor properties and their values is shown in Table 5-18.

Table 5-18 Sample Plain FTP Mode Properties and Values

Property Value

host

my.host.com

port

21

username

user

password

password

proxyHost

proxy.host.com

proxyPort

80

proxyUsername

anonymous

proxyPassword

tiger@scott.com

proxyType

http

proxyDefinitionFile

c:\proxydefinitions.xml

useProxy

true
5.4.6.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 property of the Oracle FTP Adapter deployment descriptor 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 below. Your proxy definition file must be based on this XML schema.

Example - 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 - Proxy Definition File XML Schema, would look as shown in the example below.

Example - 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 - Proxy Definition File, the Oracle FTP Adapter sends the following sequence of commands to log in:

  1. USER remote_username

  2. PASS remote_password

You can also direct the proxy definition file to pick values from the deployment descriptor for Oracle FTP Adapter. You can use the following expressions for this:

  • $proxy.user: This corresponds to the value of the proxyUsername parameter in the Oracle FTP Adapter deployment descriptor.

  • $proxy.pass: This corresponds to the value of the proxyPassword parameter in the Oracle FTP Adapter deployment descriptor.

  • $remote.user: This corresponds to the value of the username parameter in the Oracle FTP Adapter deployment descriptor.

  • $remote.pass: This corresponds to the value of the password parameter in the Oracle FTP Adapter deployment descriptor.

  • $remote.host: This corresponds to the value of the host parameter in the Oracle FTP Adapter deployment descriptor.

  • $remote.port: This corresponds to the value of the port parameter in the Oracle FTP Adapter deployment descriptor.

A sample proxy definition file based on the XML schema in Example - Proxy Definition File and taking values from the weblogic-ra.xml file is shown in the example below.

Example - Proxy Definition File Taking Values from the Deployment Descriptor

<?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>
5.4.6.2 Configuring for SFTP Mode

For running the Oracle FTP Adapter in SFTP mode, you must specify the value of certain properties in the Oracle FTP Adapter deployment descriptor. Table 5-19 lists the properties that you must modify.

Table 5-19 SFTP Mode Properties

Property Description

host

The remote FTP server name.

port

The FTP control port number.

username

The SFTP user name.

password

The SFTP password.

proxyHost

The proxy server host name.

proxyPort

The proxy port number.

proxyUsername

The proxy user name.

proxyPassword

The proxy password.

useSftp

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

authenticationType

Specify either PASSWORD or PUBLICKEY

See Set Up for SFTP

transportProvider

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

A sample list of deployment descriptor properties is shown in Table 5-20.

Table 5-20 Sample SFTP Mode Properties and Values

Property Value

host

my.host.com

port

22

username

user

password

password

proxyHost

proxy.host.com

proxyPort

80

proxyUsername

anonymous

proxyPassword

password

useSFTP

true

authenticationType

password

transportProvider

http or socket

5.4.7 Configuring File and FTP Adapters for High Availability

You can configure the File and FTP Adapters for high availability within the active-active topology for both SOA and OSB. You can configure high availability for both inbound and outbound operations.

5.4.7.1 Inbound Operations

Oracle File and FTP Adapters ensure that only one node processes a specific file in a distributed topology. To enable HA, the File or FTP adapter can either use database table or coherence cache as a coordinator to ensure that Oracle File and FTP Adapters are highly available for inbound operation.

To enable High Availability using a database table, you must indicate eis/HAFIleAdapter in your .jca file. This indicates use of an Oracle table for high availability or one of the other variants such as eis/HAFileAdapterMQSSQL or eis/HAFileAdapterDB2 for SQL Server and DB2 tables respectively.

In addition to the database-based coordinator, the File and FTP adapters support Coherence for HA capabilities. To do so, you can indicate eis/CoherenceHAFileAdapter or eis/Ftp/CoherenceHAFtpAdapter for File and FTP adapters respectively.

In the following .jca file for a File Adapter, the connection factory has been specified as CoherenceHAFileAdapter:

Example - .jca File for File Adapter with CoherenceHAFileAdapter Specified as Connection Factory

<adapter-config name="FileHACoherenceIn" 
                   adapter="File Adapter"
    wsdlLocation="FileHACoherenceIn.wsdl" 
    xmlns="http://platform.integration.
           oracle/blocks/adapter/fw/metadata">
  <connection-factory location=
                  "eis/CoherenceHAFileAdapter"
   UIincludeWildcard="*.zip" adapterRef=""/>
  <endpoint-activation portType="Read_ptt"
                   operation="Read">
    <activation-spec className=
                     "oracle.tip.adapter.file.
                                      inbound.
                     FileActivationSpec">
      <[..]>
      <[..]>
    </activation-spec>
  </endpoint-activation>
 
</adapter-config>
5.4.7.2 Outbound Operations

The Oracle File and FTP Adapters ensure that if multiple references write to the same directory, they do not overwrite each other.

The adapter uses a database table for serializing access to concurrent writes to the same file in the folder. The procedure is similar to inbound; you must select eis/HAFileAdapter which uses an Oracle table or one of the other variants such as eis/HAFileAdapterMQSSQL, or eis/HAFileAdapterDB2 for SQL Server and DB2 respectively.

As with inbound File and FTP Adapter high availability operations, the File and FTP adapters performing outbound support Coherence for High Availability capabilities. From a design experience, you must indicate eis/CoherenceHAFileAdapter or eis/Ftp/CoherenceHAFtpAdapter in your .jca file for File and FTP adapters respectively.

5.4.7.3 Additional Considerations

The File/FTP Adapter supports High Availability for both inbound as well as outbound using Coherence as a locking mechanism.

5.4.7.3.1 Inbound Operations

For inbound processing, the File/FTP Adapter must lock the file before an attempt to process the file (for example, to perform file translation and publish to the fabric). If the lock is already held for the same file by another node, the adapter ignores that file and continues with the next file.

To ensure that one particular node does not monopolize the distribution of files by acquiring locks on all the files, you must configure MaxRaiseSize to some finite value for inbound processing. See the example below.

Example - .jca File with MaxRaiseSize Configured to a Finite Value

<adapter-config name="FileHACoherenceIn" adapter="File Adapter" wsdlLocation="FileHACoherenceIn.wsdl" xmlns="http://platform.integration.oracle/blocks/
            adapter/fw/metadata">
 
  <connection-factory location="eis/CoherenceHAFileAdapter" UIincludeWildcard="*.zip" adapterRef=""/>
  <endpoint-activation portType="Read_ptt" operation="Read">
    <activation-spec className="oracle.tip.adapter.file.inbound.FileActivationSpec">
      <property name="MaxRaiseSize" value="100"/>
      <[..]>
      <[..]>
    </activation-spec>
  </endpoint-activation>
 
</adapter-config>

Additionally, if you have configured DeleteFile = "false"(for example, for Readonly polling) or when using de-batching, you must configure a valid shared location so that all the nodes in the cluster see exactly the same path. This is required since in both these cases, the File/FTP Adapter stores some control information in the shared control directory and if one node goes down during processing, the second node sees exactly the same control information.

To indicate your own Coherence Cache, use one of the following parameters:

  • CoherenceCacheConfig - the Relative path of the Coherence Cache Configuration

  • InboundCoherenceCacheName - the Coherence NamedCache used for the inbound File/FTP Adapter

  • OutboundCoherenceCacheName - Coherence NamedCache used for the outbound File/FTP Adapter.

If you want to create your own cache configuration, you must bundle the cache configuration in a jar file and add it to the server classpath (one quick way is to copy the jar file containing the cache configuration into the $DOMAIN_HOME/lib directory and then refer to the configuration in the connection factory). The default values are provided.

Example - Indicating Your Own Coherence Cache

<wls:properties>
             <wls:property>
                  <wls:name>CoherenceCacheConfig</wls:name>
                  <wls:value>config/
                      fileadapter-cache-config.xml</wls:value>
             </wls:property>
             <wls:property>
                  <wls:name>InboundCoherenceCacheName</wls:name>
                  <wls:value>FileAdapter-inbound</wls:value>
             </wls:property>
             <wls:property>
                  <wls:name>OutboundCoherenceCacheName</wls:name>
                  <wls:value>FileAdapter-outbound</wls:value>
             </wls:property>
             <wls:property../>
             <wls:property../>
         <wls:properties>
5.4.7.3.2 Outbound Operations

If you are appending to same file in the cluster, the adapter must obtain an explicit lock on the Named Cache for the filename begin appended to.

Additionally, if you are using batching, you would require the control directory to store batched content before the batching criteria evaluates to force a write to the outbound folder.

In order to fulfill HA on the outbound, the adapter would require a control directory on a shared file system (which is similar to inbound functioning).

5.4.7.3.3 Configuring XA in High-Availability Scenarios

Note:

If XA transaction is enabled in the File/FTP Adapter connection pool, the user or process that starts the WebLogic Server needs to have permission to create a directory and files on the local host machine. An XA transaction requires that the adapter saves the file to be transferred locally in a directory structure that mirrors the target directory structure. It uses the PhysicalDirectory property in the adapter JCA file to create the mirror directory structure. For example, if the adapter JCA file contains 
<endpoint-interaction portType="Put_ptt" operation="Put"> <interaction-spec className="oracle.tip.adapter.ftp.outbound.FTPInteractionSpec"> <property name="PhysicalDirectory" value="/home/oracle"/>
then the adapter will try to create a /home/oracle directory on the local machine. However, if the jca.file.Directory property is set in BPEL when the adapter is invoked, the directory set by the jca.file.Directory property will be used.

To provide XA transaction capabilities in a high-availability scenario:

  1. Log in to the WebLogic Server console, and select Deployments > File Adapter.

    Figure 5-53 WebLogic Server Console Showing Deployments-File Adapter

    Description of Figure 5-53 follows
    Description of "Figure 5-53 WebLogic Server Console Showing Deployments-File Adapter"
  2. Select Configurations > Outbound Connection Pool.

    Figure 5-54 WebLogic Server Console Showing Outbound Connection Pool

    Description of Figure 5-54 follows
    Description of "Figure 5-54 WebLogic Server Console Showing Outbound Connection Pool"
  3. Select New. Select oracle.tip.adapter.file.NonSharedConnectionFactory.

    Figure 5-55 WebLogic Server Console, File Adapter Deployments with oracle.tip.adapter.file.NonSharedConnectionFactory Selected

    Description of Figure 5-55 follows
    Description of "Figure 5-55 WebLogic Server Console, File Adapter Deployments with oracle.tip.adapter.file.NonSharedConnectionFactory Selected "
  4. Enter the JNDI name that you want to provide for the new connection instance.

    Figure 5-56 WebLogic Server Console Showing the JNDI Name for the New Instance Provided

    Description of Figure 5-56 follows
    Description of "Figure 5-56 WebLogic Server Console Showing the JNDI Name for the New Instance Provided"
  5. Click Finish and Save. Reopen the JNDI instance and enter the following Outbound Connection properties:

    Figure 5-57 WebLogic Server Console Showing Instance with Outbound Connection Properties Shown

    Description of Figure 5-57 follows
    Description of "Figure 5-57 WebLogic Server Console Showing Instance with Outbound Connection Properties Shown"

    Also, refer to Table 5-21.

    Table 5-21 Outbound Connection Properties for the JNDI Instance

    Property Property Type Property Value Supports Dynamic Indexing

    ConferenceCacheConfig

    java.lang.string

    config/fileadpter-cache-config.xml

    False

    ControlDir

    java.lang.string

    /scratch/ha

    False

    InboundCoherenceCacheName

    java.lang.string

    FileAdapter-inbound

    False

    InboundDataSource

    java.lang.string

    jdbc/SOADataSource

    False

    IsTransacted

    java.lang.string

    false

    False

    OutboundCoherenceCacheName

    java.lang.string

    FileAdapter-outbound

    False

    OutboundDataSource

    java.lang.string

    jdbc/SOADataSource

    False

    OutboundDataSourceLocal

    java.lang.string

    jdbc/SOALocalTxDataSource

    False

    OutboundLockTypeForWrite

    java.lang.string

    oracle

    False

    WorkingDirectory

    java.lang.string

    default

    False
  6. Select Transaction tab > XA Transaction. Click Save.

    Figure 5-58 Selecting the Transaction Tab in the WebLogic Console

    Description of Figure 5-58 follows
    Description of "Figure 5-58 Selecting the Transaction Tab in the WebLogic Console"
  7. If you are using OSB, make sure you do these additional tasks:

    • Supply jdbc/SOALocalTXDataSource datasource as it is not available by default.

    • QoS (Once-and-only once) for Routing options and Pipeline transaction is required for outbound XA.

    • Check Pipeline transaction is not required for inbound Local Transaction.

5.5 Oracle File and FTP Adapters Use Cases

This section includes the following Oracle File and FTP Adapters use cases.

5.5.1 Oracle File Adapter XML Debatching

This is an Oracle File Adapter feature that debatches large XML documents into smaller individual XML fragments.

In this use case, the Debatching XML process uses the Oracle File Adapter to debatch an XML file containing a batch of employees occurring in the XML file as repeating nodes. The Adapter then processes the nodes and writes separate output files to every individual node.

This section includes the following topics:

5.5.1.1 Prerequisites

To perform debatching, you must first create the following files:

  • emps.xml

  • employees.xsd

Contents of emps.xml

<?xml version="1.0" encoding="UTF-8"?>
<employees
    xmlns="http://www.srimant.com/employees" >
<employee>
	<name>Cynthia Holmes</name>	
        <address>
                <addr_line1>38660 Lexington Street</addr_line1>
                <addr_line2></addr_line2>
                <state>California</state>
                <zip>94548</zip>
        </address>
</employee>
<employee>
	<name>Robert Patrick</name>	
        <address>
                <addr_line1>41688 Spring Dale Road</addr_line1>
                <addr_line2></addr_line2>
                <state>Ohio</state>
                <zip>94548</zip>
        </address>
</employee>
</employees>

Contents of employees.xsd

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://www.srimant.com/employees" xmlns:emp="http://www.srimant.com/employees" xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" >
        <element name="employees" type="emp:employeesType"/>
        <complexType name="employeesType">
                <sequence>
                        <element ref="emp:employee"  minOccurs="0" maxOccurs="unbounded"/>
                </sequence>
        </complexType>
      <element name="employee" type="emp:employeeType"/>
        <complexType name="employeeType">
          <sequence>
              <element name="name" type="string"/>
              <element ref="emp:address" minOccurs="1" maxOccurs="1"/>
          </sequence>
        </complexType>
      <element name="address">
        <complexType>
          <sequence>
              <element name="addr_line1" type="string"/>
              <element name="addr_line2" type="string"/>
              <element name="state" type="string"/>
              <element name="zip" type="string"/>
          </sequence>
        </complexType>
      </element>
</schema>
5.5.1.2 Splitting an Input XML Document that Contains Repeating Element

This section describes the process for splitting an input XML document with repeating elements into smaller documents. This is helpful if you want to use XML debatching with the File or FTP Adapter.

nxsd:elementDepth is a schema level annotation that facilitates XML debatching in cases when the repeating element maxOccurs=’unbounded of the XML structure is not an immediate descendant of the root element. The value of the nxsd:elementDepth should comply to the XML structure defined in the XSD.

Example of XML Document with Repeating Elements

<root>
<ElementList>
	<element1>
		<element11>11</element11>
		<element12>12</element12>
	</element1>
	<element1>
		<element11>21</element11>
		<element12>22</element12>
	</element1>
	<element1>
		<element11>31</element11>
		<element12>32</element12>
	</element1>
</ElementList>
</root>

Procedure for splitting XML Document with Repeating Elements

Note:

Apply the correct value during design time; the correct value is the number of levels starting below the root element. Incorrect values cause unpredictable results and invalid XML documents. For example, in the following schema, to get the desired output, nxsd:elementDepth must be set to 2 as the repeating element <element1> is located two levels beneath the root element <root>.

To produce the required output, modify the XML Schema by adding xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd" nxsd:elementDepth="2"

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.examplefileIn.org"
xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd" nxsd:elementDepth="2"
targetNamespace="http://www.examplefileIn.org"
elementFormDefault="qualified">
<xsd:element name="root">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="ElementList">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="element1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="element11" type="xsd:string"/>
<xsd:element name="element12" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
5.5.1.3 Designing the SOA Composite

You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:

  1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.
  2. Enter SOA-XMLDebatching in the Application Name field, as shown in Figure 5-59, and click Next. The Create Generic Application - Name your project page is displayed.

    Figure 5-59 The Generic Create Application - Name your application Page

    eneric Create Application - Name your application Page
  3. Enter XMLDebatching in the Project Name field.
  4. In the Available list under the Project Technologies tab, double-click SOA to move it to the Selected list, as shown in Figure 5-60.

    Figure 5-60 The Create Generic Application - Name your project Page

    Create Generic Application - Name your project Page
  5. Click Next. The Configure SOA settings dialog appears.
  6. Select Composite With BPEL in the Composite Template box, as shown in Figure 5-61, and click Finish. The Create BPEL Process - BPEL Process page is displayed.

    Figure 5-61 The Create Generic Application - Configure SOA settings Page

    Create Generic Application - Configure SOA settings Page
  7. Enter BPELXMLDebatching in the Name field, select Define Service Later from the Template box, as shown in Figure 5-62.

    Figure 5-62 The Create BPEL Process - BPEL Process Page

    Create BPEL Process - BPEL Process Page
  8. Click OK. The SOA-XMLDebatching application and the XMLDebatching project appear in the design area, as shown in Figure 5-63.

    Figure 5-63 The JDeveloper - composite.xml Page

    Developer - composite.xml Page
  9. Copy the employees.xsd file that you created (see Prerequisites) to the xsd directory in your project.
5.5.1.4 Creating the Inbound Oracle File Adapter Service

Perform the following steps to create an inbound Oracle File Adapter service to read the file from a local directory:

  1. Drag and drop the Oracle File Adapter from the Components window to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter XMLDebatchingIn in the Service Name field and click Next.

    Figure 5-64 The Adapter Configuration Wizard - Service Name Page

    Description of Figure 5-64 follows
    Description of "Figure 5-64 The Adapter Configuration Wizard - Service Name Page"
  3. Select Define from operation and schema (specified later) in the Adapter Interface screen and click Next.
  4. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  5. Select Read File in the Operation screen and click Next.

    Figure 5-65 The Adapter Configuration Wizard Operation Page

    Description of Figure 5-65 follows
    Description of "Figure 5-65 The Adapter Configuration Wizard Operation Page"
  6. Enter the physical path for the input directory in the File Directories screen and click Next.

    Figure 5-66 The Adapter Configuration Wizard - File Directories Page

    Description of Figure 5-66 follows
    Description of "Figure 5-66 The Adapter Configuration Wizard - File Directories Page"
  7. Enter *.xml in the Include Files With Name Pattern field, select Files Contain Multiple Messages, specify 1 as the value for Publish Messages in Batches Of box in the File Filtering screen and click Next.

    Figure 5-67 The Adapter Configuration Wizard File Filtering Page

    Description of Figure 5-67 follows
    Description of "Figure 5-67 The Adapter Configuration Wizard File Filtering Page"
  8. Click Next in the File Polling screen.
  9. In the Messages screen, click Browse For Schema File that appears at the end of the URL field. The Type Chooser dialog is displayed.
  10. Click Project Schema Files, employees.xsd, and employees.

    Figure 5-68 The Type Chooser Dialog

    Description of Figure 5-68 follows
    Description of "Figure 5-68 The Type Chooser Dialog"
  11. Click OK. The URL field in the Messages page is populated with the employees.xsd file.

    Figure 5-69 The Adapter Configuration Wizard File Messages Page

    Description of Figure 5-69 follows
    Description of "Figure 5-69 The Adapter Configuration Wizard File Messages Page"
  12. Click Next.
  13. In the JCA Endpoint Properties screen, click Next.
    JCA Endpoint Properties screen appears if you have selected the Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  14. Click Finish. The inbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-70 The JDeveloper - Composite.xml

    Description of Figure 5-70 follows
    Description of "Figure 5-70 The JDeveloper - Composite.xml"
5.5.1.5 Creating the Outbound Oracle File Adapter Service

Perform the following steps to create an outbound Oracle File Adapter service to write the file from a local directory to the FTP server:

  1. Drag and drop the Oracle File Adapter from the Components window to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter XMLOut in the Service Name field and click Next.
  3. Select Define from operation and schema (specified later), and click Next in the Adapter Interface page.
  4. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  5. Select Write File, and click Next in the Operation screen.
  6. In the File Configuration screen:
    1. Enter the physical path for the output directory and enter emp_%SEQ%.xml in the File Naming Convention (po_%SEQ%.txt) field.
    2. Select Number of Messages Equals and click Next.
      The default value is 1.

      Figure 5-71 The Adapter Configuration Wizard - File Configuration Page

      Description of Figure 5-71 follows
      Description of "Figure 5-71 The Adapter Configuration Wizard - File Configuration Page"
  7. In the Messages screen:
    1. Click Browse For Schema File that appears at the end of the URL field. The Type Chooser dialog is displayed.
    2. Click Project Schema Files, employees.xsd, and employee.
    3. Click OK.
      The URL field in the Messages page is populated with the employees.xsd file
  8. In the JCA Endpoint Properties screen, click Next.
    The JCA Endpoint Properties screen appears if you have selected the Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  9. Click Finish. The outbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-72 The JDeveloper - Composite.xml

    Description of Figure 5-72 follows
    Description of "Figure 5-72 The JDeveloper - Composite.xml"
5.5.1.6 Wiring Services and Activities

You have to assemble or wire the three components that you have created: Inbound adapter service, BPEL process, Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the XMLDebatchingIn in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
  2. Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the XMLOut in the External References area.

    The JDeveloper composite.xml appears, as shown in Figure 5-73.

    Figure 5-73 The JDeveloper - Composite.xml

    Description of Figure 5-73 follows
    Description of "Figure 5-73 The JDeveloper - Composite.xml"
  3. Click File, Save All.
5.5.1.6.1 Add a Receive Activity
  1. Double-click BPELXMLDebatching. The BPELXMLDebatching.bpel page is displayed.
  2. Drag and drop a Receive activity from the Components window to the design area.
  3. Double-click the Receive activity. The Receive dialog is displayed.
  4. Enter ReceiveEmployee in the Name field, as shown in Figure 5-74.

    Figure 5-74 The JDeveloper - BPELXMLDebatching.bpel

    Description of Figure 5-74 follows
    Description of "Figure 5-74 The JDeveloper - BPELXMLDebatching.bpel"
  5. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  6. Select XMLDebatchingIn, as shown in Figure 5-75, and click OK.

    Figure 5-75 The Partner Link Chooser Dialog

    Description of Figure 5-75 follows
    Description of "Figure 5-75 The Partner Link Chooser Dialog"
  7. Click the Auto-Create Variable icon to the right of the Variable field in the Receive dialog, as shown in Figure 5-76. The Create Variable dialog is displayed.

    Figure 5-76 The Receive Dialog

    Description of Figure 5-76 follows
    Description of "Figure 5-76 The Receive Dialog"
  8. Select the default variable name and click OK. The Variable field is populated with the default variable name.
  9. Check Create Instance, and click OK. The JDeveloper BPELXMLDebatching.bpel page appears, as shown in Figure 5-77.

    Figure 5-77 The JDeveloper - BPELXMLDebatching.bpel

    Description of Figure 5-77 follows
    Description of "Figure 5-77 The JDeveloper - BPELXMLDebatching.bpel"
5.5.1.6.2 Add an Invoke Activity
  1. Drag and drop an Invoke activity from the Components window to the design area.
  2. Double-click the Invoke activity. The Invoke dialog is displayed.
  3. Enter WriteEmployee in the Name field, as shown in Figure 5-78.

    Figure 5-78 The Invoke Dialog

    Description of Figure 5-78 follows
    Description of "Figure 5-78 The Invoke Dialog"
  4. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  5. Select XMLOut, as shown in Figure 5-79, and click OK.

    Figure 5-79 The Partner Link Chooser Dialog

    Description of Figure 5-79 follows
    Description of "Figure 5-79 The Partner Link Chooser Dialog"
  6. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog. The Create Variable dialog is displayed.
  7. Select the default variable name and click OK. The Variable field is populated with the default variable name. The Invoke dialog is displayed, as shown in Figure 5-80.

    Figure 5-80 The Invoke Dialog

    Description of Figure 5-80 follows
    Description of "Figure 5-80 The Invoke Dialog"
  8. Click OK. The JDeveloper BPELXMLDebatching.bpel page appears, as shown in Figure 5-81.

    Figure 5-81 The JDeveloper - BPELXMLDebatching.bpel

    Description of Figure 5-81 follows
    Description of "Figure 5-81 The JDeveloper - BPELXMLDebatching.bpel"
5.5.1.6.3 Add a Transform Activity
  1. Drag and drop a Transform activity from the Components window in between the Receive and Invoke activities in the design area.
  2. Double-click the Transform activity. The Transform dialog is displayed.
  3. Enter TransformPayload in the Name field, as shown in Figure 5-82.

    Figure 5-82 The Transform Dialog

    Description of Figure 5-82 follows
    Description of "Figure 5-82 The Transform Dialog"
  4. Click the Transformation tab. The Transform dialog is displayed, as shown in Figure 5-83.

    Figure 5-83 The Transform Dialog - Transformation Tab

    Description of Figure 5-83 follows
    Description of "Figure 5-83 The Transform Dialog - Transformation Tab"
  5. Click the Create... icon. The Source Variable dialog is displayed.
  6. Select ReceiveEmployee_Read_InputVariable in the Source Variable box, and select employees in the Source Part box, and then click OK. The Transform dialog is displayed with the Source and Part selected.
  7. Select WriteEmployee_Write_InputVariable in the Target Variable list, select employee in the Target Part, as shown in Figure 5-84.

    Figure 5-84 The Transform Dialog

    Description of Figure 5-84 follows
    Description of "Figure 5-84 The Transform Dialog"
  8. Click the Create Mapping icon. The XSL Editor page is displayed.
  9. Drag employees from sources to employee in the target, as shown in Figure 5-85. The Auto Map Preferences dialog is displayed.

    Figure 5-85 The JDeveloper - Transformation_2.xsl

    Description of Figure 5-85 follows
    Description of "Figure 5-85 The JDeveloper - Transformation_2.xsl"
  10. Click OK.
  11. Click File, Save All.
  12. Close the XSL Editor page. The BPELXMLDebatching.bpel page is displayed, as shown in Figure 5-86.

    Figure 5-86 The JDeveloper - XML Debatching Complete

    Description of Figure 5-86 follows
    Description of "Figure 5-86 The JDeveloper - XML Debatching Complete"
5.5.1.7 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
5.5.1.8 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.
  2. Copy the emps.xml file that you created (see Prerequisites) to the input directory and ensure it gets processed. Check the output directory to ensure that an output file has been created.
  3. Click the SOA composite that you deployed. The Dashboard is displayed.

    Note your Instance ID in the Recent Instances area.

  4. Click the Instances tab. The Instance IDs of the SOA composite are listed.
  5. Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.
  6. Click your BPEL process instance. The Audit Trail of the BPEL process instance is displayed.
  7. Expand a payload node to view payload details.
  8. Click the Flow tab to view the process flow. Click an activity to view the details of the activity

5.5.2 Flat Structure for Oracle BPEL PM

This use case demonstrates how a flat structure business process uses the Oracle File Adapter to process address book entries from a Comma Separated Value (CSV) file. This is then transformed and written to another file in a Fixed Length format.

This section includes the following topics:

5.5.2.1 Prerequisites

To perform the flat structure business process, you must first create the following files:

  • address-csv.txt

  • address-csv.xsd

  • address-fixedLength.xsd

  • addr1Toaddr2.xsl

Contents of address-csv.txt

Name,Street1,Street2,City,State,Country
Oracle India Private Limited, Lexington Towers Prestige St. John's Woods, 2nd Cross Road Chikka Audugodi, Bangalore, Karnataka, India
Intel Technology India Private Limited, Survey #23-56 P Devarabeesanahalli Village, Outer Ring Road Varthur Hobli, Bangalore, Karnataka, India

Contents of address-csv.xsd

<?xml version="1.0" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
            targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
            xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
            elementFormDefault="qualified"
            attributeFormDefault="unqualified" nxsd:encoding="US-ASCII" nxsd:hasHeader="true" nxsd:headerLines="1" nxsd:linesTerminatedBy="${eol}" nxsd:stream="chars" nxsd:version="NXSD">
  <xsd:element name="Root-Element">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Address" minOccurs="1" maxOccurs="unbounded">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="Name" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Street1" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Street2" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="City" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="State" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Country" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="${eol}" nxsd:quotedBy="&quot;">
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>
<!--NXSDWIZ:D:\work\jDevProjects\BPEL\FlatStructure\address-csv.txt:-->

Contents of address-fixedLength.xsd

<?xml version="1.0" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
            targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/fixedLength"
            xmlns:fix="http://xmlns.oracle.com/pcbpel/demoSchema/fixedLength"
            elementFormDefault="qualified"
            attributeFormDefault="unqualified" nxsd:encoding="US-ASCII" nxsd:stream="chars" nxsd:version="NXSD">
  <xsd:element name="Root-Element">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Address" minOccurs="1" maxOccurs="unbounded" nxsd:style="array" nxsd:cellSeparatedBy="\r\n">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="Name" type="xsd:string" nxsd:style="fixedLength" nxsd:length="38">
              </xsd:element>
              <xsd:element name="Street" type="xsd:string" nxsd:style="fixedLength" nxsd:length="80">
              </xsd:element>
              <xsd:element name="City" type="xsd:string" nxsd:style="fixedLength" nxsd:length="11">
              </xsd:element>
              <xsd:element name="State" type="xsd:string" nxsd:style="fixedLength" nxsd:length="11">
              </xsd:element>
              <xsd:element name="Country" type="xsd:string" nxsd:style="fixedLength" nxsd:length="7">
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>
<!--NXSDWIZ:C:\orabpel\samples\tutorials\121.FileAdapter\FlatStructure\outputDir\csv_2004.11.10.txt:-->

Contents of addr1Toaddr2.xsl

<?xml version="1.0" encoding="windows-1252"?>
<?oracle-xsl-mapper
  <!-- SPECIFICATION OF MAP SOURCES AND TARGETS, DO NOT MODIFY. -->
  <mapSources>
    <source type="XSD">
      <schema location="xsd/address-csv.xsd"/>
      <rootElement name="Root-Element" namespace="http://xmlns.oracle.com/pcbpel/demoSchema/csv"/>
    </source>
  </mapSources>
  <mapTargets>
    <target type="XSD">
      <schema location="xsd/address-fixedLength.xsd"/>
      <rootElement name="Root-Element" namespace="http://xmlns.oracle.com/pcbpel/demoSchema/fixedLength"/>
    </target>
  </mapTargets>
  <!-- GENERATED BY ORACLE XSL MAPPER 1.0 AT [TUE NOV 16 16:14:01 IST 2004]. -->
?>
<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
                xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
                xmlns:fix="http://xmlns.oracle.com/pcbpel/demoSchema/fixedLength"
                exclude-result-prefixes="xsl xsd tns nxsd fix">
  <xsl:template match="/">
    <fix:Root-Element>
      <xsl:for-each select="/tns:Root-Element/tns:Address">
        <fix:Address>
          <fix:Name>
            <xsl:value-of select="tns:Name"/>
          </fix:Name>
          <fix:Street>
            <xsl:value-of select="concat(tns:Street1,tns:Street2)"/>
          </fix:Street>
          <fix:City>
            <xsl:value-of select="tns:City"/>
          </fix:City>
          <fix:State>
            <xsl:value-of select="tns:State"/>
          </fix:State>
          <fix:Country>
            <xsl:value-of select="tns:Country"/>
          </fix:Country>
        </fix:Address>
      </xsl:for-each>
    </fix:Root-Element>
  </xsl:template>
</xsl:stylesheet>
5.5.2.2 Designing the SOA Composite

You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following steps:

  1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.
  2. Enter SOA-FlatStructure in the Application Name field, and click OK. The Create Generic Application - Name your project page is displayed.
  3. Enter FlatStructure in the Project Name.
  4. In the Available list under the Project Technologies tab, double-click SOA to move it to the Selected list.
  5. Click Next. The Configure SOA Settings dialog appears.
  6. Select Composite With BPEL in the Composite Template box, and click Finish. The Create BPEL Process - BPEL Process page is displayed.
  7. Enter BPELFlatStructure in the Name field, select Define Service Later from the Template box.
  8. Click OK. The SOA-FlatStructure application and the FlatStructure project appear in the design area, as shown in Figure 5-87.

    Figure 5-87 The JDeveloper - Composite.xml

    Description of Figure 5-87 follows
    Description of "Figure 5-87 The JDeveloper - Composite.xml"
  9. Copy the address-csv.xsd and address-fixedLength.xsd files that you created (see Prerequisites) to the schema directory in your project.
  10. Copy addr1Toaddr2.xsl that you created (see Prerequisites) to the xsl directory of your project.
5.5.2.3 Creating the Inbound Oracle File Adapter Service

Perform the following steps to create an inbound Oracle File Adapter service to read the file from a local directory:

  1. Drag and drop File Adapter from the Components window to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter FlatStructureIn in the Service Name field and click Next.
  3. Select Define from operation and schema (specified later) in the Adapter Interface screen and click Next.
  4. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  5. Select Read File in the Operation screen, and click Next.
  6. Enter the physical path for the input directory in the File Directories screen. Check Archive Processed Files.
  7. Enter the physical path for the archive directory for processed files and click Next.
  8. Enter *.txt in the Include Files With Name Pattern field, click Next in the File Filtering screen.
  9. Click Next the File Polling page is displayed.
  10. In the Messages screen.
    1. Click Browse For Schema File that appears at the end of the URL field.
      The Type Chooser dialog is displayed.
    2. Click Project Schema Files, address-csv.xsd, and Root-Element.
    3. Click OK.
      The URL field in the Messages page is populated with the address-csv.xsd file.
    4. Click Next
  11. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  12. Click Finish. The inbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-88 The JDeveloper - Composite.xml

    Description of Figure 5-88 follows
    Description of "Figure 5-88 The JDeveloper - Composite.xml"
5.5.2.4 Creating the Outbound Oracle File Adapter Service

Perform the following steps to create an outbound Oracle File Adapter service to write the file from a local directory to the FTP server:

  1. Drag and drop File Adapter from the Components window to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter FlatStructureOut in the Service Name field and click Next.
  3. Select Define from operation and schema (specified later) in the Adapter Interface screen and click Next.
  4. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  5. Select Write File, and click Next in the Operation screen.
  6. In the File Configuration screen, enter the physical path for the output directory and enter address_%SEQ%.data in the File Naming Convention(po_%SEQ%.txt) field and click Next.
  7. In the Messages screen.
    1. Click Browse For Schema File that appears at the end of the URL field.
      The Type Chooser dialog is displayed.
    2. Click Project Schema Files, address-fixedLength.xsd, and Root-Element.
    3. Click OK.
      The URL field in the Messages page is populated with the address-fixedLength.xsd file.
    4. Click Next
  8. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  9. Click Finish. The outbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-89 The JDeveloper - Composite.xml

    Description of Figure 5-89 follows
    Description of "Figure 5-89 The JDeveloper - Composite.xml"
5.5.2.5 Wiring Services and Activities

You have to assemble or wire the three components that you have created: Inbound adapter service, BPEL process, Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the FlatStructureIn in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
  2. Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the FlatStructureOut in the External References area.

    The JDeveloper composite.xml appears, as shown in Figure 5-90.

    Figure 5-90 The JDeveloper - composite.xml

    Description of Figure 5-90 follows
    Description of "Figure 5-90 The JDeveloper - composite.xml"
  3. Click File, Save All.
5.5.2.5.1 Add a Receive Activity
  1. Double-click BPELFlatStructure. The BPELFlatStructure.bpel page is displayed.
  2. Drag and drop a Receive activity from the Components window to the design area.
  3. Double-click the Receive activity. The Receive dialog is displayed.
  4. Enter ReceiveCSV in the Name field.
  5. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  6. Select FlatStructureIn, and click OK.
  7. Click the Auto-Create Variable icon to the right of the Variable field in the Receive dialog. The Create Variable dialog is displayed.
  8. Select the default variable name and click OK. The Variable field is populated with the default variable name.
  9. Check Create Instance, and click OK. The JDeveloper BPELFlatStructure.bpel page appears, as shown in Figure 5-91.

    Figure 5-91 The JDeveloper - BPELFlatStructure.bpel

    Description of Figure 5-91 follows
    Description of "Figure 5-91 The JDeveloper - BPELFlatStructure.bpel"
5.5.2.5.2 Add an Invoke Activity
  1. Drag and drop an Invoke activity from the Components window to the design area.
  2. Double-click the Invoke activity. The Invoke dialog is displayed.
  3. Enter InvokeWrite in the Name field.
  4. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  5. Select FlatStructureOut, and click OK.
  6. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog. The Create Variable dialog is displayed.
  7. Select the default variable name and click OK. The Variable field is populated with the default variable name.
  8. Click OK. The JDeveloper BPELFlatStructure.bpel page appears, as shown in Figure 5-92.

    Figure 5-92 The JDeveloper - BPELFlatStructure.bpel

    Description of Figure 5-92 follows
    Description of "Figure 5-92 The JDeveloper - BPELFlatStructure.bpel"
5.5.2.5.3 Add a Transform Activity
  1. Drag and drop a Transform activity from the Components window in between the Receive and Invoke activities in the design area.
  2. Double-click the Transform activity. The Transform dialog is displayed.
  3. Enter TransformPayload in the Name field.
  4. Click the Transformation tab. The Transform dialog is displayed.
  5. Click the Create... icon. The Source Variable dialog is displayed.
  6. Select ReceiveCSV_Read_InputVariable in the Source Variable box, and select body in the Source Part box, and then click OK. The Transform dialog is displayed with the Source and Part selected.
  7. Select InvokeWrite_Write_InputVariable in the Target Variable list, select body in the Target Part.
  8. Click the Browse button at the end of the Mapper File field and select addr1Toaddr2.xsl file from the xsl directory in your project.
  9. Click OK.
  10. Click File, Save All. The BPELFlatStructure.bpel page is displayed, as shown in Figure 5-93.

    Figure 5-93 The JDeveloper - BPELFlatStructure.bpel

    Description of Figure 5-93 follows
    Description of "Figure 5-93 The JDeveloper - BPELFlatStructure.bpel"
5.5.2.6 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
5.5.2.7 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.
  2. Copy the address-csv.txt file that you created (see Prerequisites) to the input directory and ensure it gets processed. Check the output directory to ensure that an output file has been created.
  3. Click the SOA composite that you deployed. The Dashboard is displayed.

    Note your Instance ID in the Recent Instances area.

  4. Click the Instances tab. The Instance IDs of the SOA composite are listed.
  5. Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.
  6. Click your BPEL process instance. The Audit Trail of the BPEL process instance is displayed.
  7. Expand a payload node to view payload details.
  8. Click the Flow tab to view the process flow. Click an activity to view the details of the activity.
  9. Click ReceiveCSV to display the activity details.

5.5.3 Flat Structure for Mediator

In this use case, Mediator receives the customer data from a file system as a text file, through an inbound Oracle 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 section includes the following topics:

5.5.3.1 Prerequisites

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

To perform the flat structure for Mediator business process, you must first create the following file:

  • address-csv.xsd

Contents of address-csv.xsd

<?xml version="1.0" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
            targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
            xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
            elementFormDefault="qualified"
            attributeFormDefault="unqualified" nxsd:encoding="US-ASCII" nxsd:hasHeader="true" nxsd:headerLines="1" nxsd:linesTerminatedBy="${eol}" nxsd:stream="chars" nxsd:version="NXSD">
  <xsd:element name="Root-Element">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Address" minOccurs="1" maxOccurs="unbounded">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="Name" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Street1" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Street2" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="City" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="State" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Country" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="${eol}" nxsd:quotedBy="&quot;">
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>
<!--NXSDWIZ:D:\work\jDevProjects\BPEL\FlatStructure\address-csv.txt:-->
5.5.3.2 Creating a Mediator Application and Project

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

  1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.
  2. Enter FileFTP_RW in the Application Name field and click Next. The Create Generic Application - Name your project page is displayed.
  3. Enter FileRead_FTPWrite in the Project Name field.
  4. In the Available list in the Project Technologies tab, double-click SOA to move it to the Selected list.
  5. Click Next. The Create Generic Application - Configure SOA settings page is displayed.
  6. Select Composite With Mediator in the Composite Template box.
  7. Click Finish. The Create Mediator - Mediator Component page is displayed.
  8. Enter FileRead_RS in the Name field.
  9. Select Define Interface Later in the Template list, and then click OK. The FileFTP_RW application and the FileRead_FTPWrite project appear in the design area.
5.5.3.3 Importing the Schema Definition (.XSD) Files

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

  1. Create a Schema directory and copy the address-csv.xsd file that you created (see Prerequisites) to this directory.

  2. In the Application Navigator, select FileRead_FTPWrite.

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

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

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

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

  7. Click OK.

5.5.3.4 Creating the Inbound Oracle File Adapter Service

Perform the following steps to create an inbound Oracle File Adapter service to read the file from a local directory

  1. Drag a File Adapter service from the Components to the design area. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter ReadFile in the Service Name field and click Next.
  3. Select Define from operation and schema (specified later) in the Adapter Interface screen and click Next.
  4. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  5. Select Read File in the Operation screen, and click Next.
  6. In the File Directories screen, select Physical Path option, and click Browse, select a polling directory, and click Next.
  7. In the File Filtering screen, enter *.txt in the Include Files with Name Pattern field and click Next.
  8. Click Next in the File Polling page.
  9. In the Messages screen:
    1. Click the Browse For Schema File button at the end of the URL field.
      The Type Chooser dialog is displayed.
    2. Select Project Schema Files, address-csv.xsd, and then Root-Element.
    3. Click OK.
    4. Click Next.
  10. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  11. Click Finish. A ReadFile adapter service is created.
5.5.3.5 Creating the Outbound Oracle FTP Adapter Service

Perform the following steps to create an outbound Oracle FTP Adapter service to write the file to an FTP server:

  1. Drag an FTP Adapter service from Components to the design area. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter WriteFTP in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next. The FTP Server Connection page is displayed.
  5. Specify the JNDI Name of the FTP Server in the FTP Server JNDI Name field and click Next. The Operation page is displayed.
  6. Select Ascii option as File Type.
  7. Select Put File option as the Operation Type and click Next. The File Configuration page is displayed.
  8. Specify the directory to which file must be written in the Directory for Outgoing Files (physical path) field.
  9. Specify the naming convention for the output file name in the File Naming Convention field. For example, po_%SEQ%.txt.
  10. Click Next. The Messages page is displayed.
  11. Click the Browse For Schema File button at the end of the URL field. The Type Chooser dialog is displayed.
  12. Select Project Schema Files, address-csv.xsd, and then Root-Element.
  13. Click OK.
  14. Click Next in the Messages page. The Finish page is displayed.
  15. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  16. Click Finish. A WriteFTP adapter service is created.
5.5.3.6 Wiring Services

You have to assemble or wire the three components that you have created: Inbound Oracle File Adapter service, Mediator component, Outbound Oracle FTP Adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the ReadFile in the Exposed Services area to the drop zone that appears as a green triangle in the Mediator component in the Components area.
  2. Drag the small triangle in the Mediator component in the Components area to the drop zone that appears as a green triangle in the WriteFTP in the External References area. The JDeveloper composite.xml appears, as shown in Figure 5-94.

    Figure 5-94 The JDeveloper - Composite.xml

    Description of Figure 5-94 follows
    Description of "Figure 5-94 The JDeveloper - Composite.xml"
5.5.3.7 Creating the Routing Rule

Perform the following steps to create a routing service:

  1. Double-click the ReadFile_RS routing service. The Read operation is listed in the Operations pane, as shown in Figure 5-95.

    Figure 5-95 The JDeveloper - ReadFile_RS Routing Service Page

    Description of Figure 5-95 follows
    Description of "Figure 5-95 The JDeveloper - ReadFile_RS Routing Service Page"
  2. Click the + sign to the left of <<Filter Expression>>to expand the routing rule.
  3. Click the icon that appears at the end of the Transform Using field. The Request Transformation Map dialog is displayed, as shown in Figure 5-96.

    Figure 5-96 The Request Transformation Map Dialog

    Description of Figure 5-96 follows
    Description of "Figure 5-96 The Request Transformation Map Dialog"
  4. Select Create New Mapper File and click OK.

    A Root-Element_To_Root-Element.xsl tab is added to 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.

  5. Drag and drop the imp1:Address source element to the imp1:Address target element. The Auto Map Preferences dialog is displayed.
  6. From the During Auto Map options, deselect Match Elements Considering their Ancestor Names.
  7. Click OK.
  8. From the File menu, click Save.
5.5.3.8 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
5.5.3.9 Runtime Task

At runtime, copy a text file to the polling directory. Once the Oracle File Adapter picks the file, it writes the file to the directory that you specified at design time.

5.5.4 Oracle File Adapter Scalable DOM

This use case demonstrates how a scalable DOM process uses the streaming feature to copy/move huge files from one directory to another.

The streaming option is not supported with DB2 hydration store.

This section includes the following topics:

5.5.4.1 Prerequisites

To perform the streaming large payload process, you must first create the following files:

  • address-csv.xsd

  • address-csv-large.txt

Contents of address-csv.xsd

<?xml version="1.0" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
            targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
            xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
            elementFormDefault="qualified"
            attributeFormDefault="unqualified" nxsd:encoding="US-ASCII" nxsd:hasHeader="true" nxsd:headerLines="1" nxsd:linesTerminatedBy="${eol}" nxsd:stream="chars" nxsd:version="NXSD">
  <xsd:element name="Root-Element">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Address" minOccurs="1" maxOccurs="unbounded">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="Name" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Street1" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Street2" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="City" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="State" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Country" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="${eol}" nxsd:quotedBy="&quot;">
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>
<!--NXSDWIZ:D:\work\jDevProjects\BPEL\FlatStructure\address-csv.txt:-->

Contents of address-csv-large.txt

Name,Street1,Street2,City,State,Country
Oracle India Private Limited, Lexington Towers Prestige St. John's Woods, 2nd Cross Road Chikka Audugodi, Bangalore, Karnataka, India
Intel Technology India Private Limited, Survey #23-56 P Devarabeesanahalli Village, Outer Ring Road Varthur Hobli, Bangalore, Karnataka, India
<<copy the 2 lines above 100 times>>
5.5.4.2 Designing the SOA Composite

You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following steps:

  1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.
  2. Enter SOA-ScalableDOM in the Application Name field, and click Next. The Create Generic Application - Name your project page is displayed.
  3. Enter ScalableDOM in the Project Name field.
  4. In the Available list under the Project Technologies tab, double-click SOA to move it to the Selected list.
  5. Click Next. The Configure SOA settings dialog appears.
  6. Select Composite With BPEL in the Composite Template box, and click Finish. The SOA-ScalableDOM application and ScalableDOM project appears in the Application Navigator and the Create BPEL Process - BPEL Process page is displayed.
  7. Enter BPELScalableDOM in the Name field, select Define Service Later from the Template box.
  8. Click OK. The SOA-ScalableDOM application and the ScalableDOM project appears in the design area.
  9. Copy the address-csv.xsd file that you created (see Prerequisites) to the xsd directory in your project.
5.5.4.3 Creating the Inbound Oracle File Adapter Service

Perform the following steps to create an inbound Oracle File Adapter service to read the file from a local directory:

  1. Drag and drop File Adapter from the Components window to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter ScalableDOMIn in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next. The FTP Server Connection page is displayed.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select Read File, and check Use File Streaming, and click Next. The File Directories page is displayed.
  7. Enter the physical path for the input directory. The File Filtering page is displayed.
  8. Enter *.txt in the Include Files With Name Pattern field, click Next. The File Polling page is displayed.
  9. Click Next. The Messages page is displayed.
  10. Click Browse For Schema File that appears after the URL field. The Type Chooser dialog is displayed.
  11. Click Project Schema Files, address-csv.xsd, and Root-Element, as shown in Figure 5-97.

    Figure 5-97 The Type Chooser Dialog

    Description of Figure 5-97 follows
    Description of "Figure 5-97 The Type Chooser Dialog"
  12. Click OK. The URL field in the Messages page is populated with the address-csv.xsd file.
  13. Click Next.
  14. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  15. Click Finish. The inbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-98 The JDeveloper - Composite.xml

    Description of Figure 5-98 follows
    Description of "Figure 5-98 The JDeveloper - Composite.xml"
5.5.4.4 Creating the Outbound Oracle File Adapter Service

Perform the following steps to create an outbound Oracle File Adapter service to write the file from a local directory to the FTP server:

  1. Drag and drop File Adapter from the Components window to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter ScalableDOMOut in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next. The FTP Server Connection page is displayed.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select Write File, and click Next. The File Configuration page is displayed.
  7. Enter the physical path for the output directory and enter address-csv_%SEQ%.xml in the File Naming Convention (po_%SEQ%.txt) field.
  8. Click Next. The Messages page is displayed.
  9. Click Browse For Schema File that appears at the end of the URL field. The Type Chooser dialog is displayed.
  10. Click Project Schema Files, address-csv.xsd, and Root-Element.
  11. Click OK. The URL field in the Messages page is populated with the address-csv.xsd file.
  12. Click Next.
  13. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  14. Click Finish. The outbound Oracle File Adapter is now configured and composite.xml appears, as shown in Figure 5-99.

    Figure 5-99 The JDeveloper - Composite.xml

    Description of Figure 5-99 follows
    Description of "Figure 5-99 The JDeveloper - Composite.xml"
5.5.4.5 Wiring Services and Activities

You have to assemble or wire the three components that you have created: Inbound adapter service, BPEL process, Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the ScalableDOMIn in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
  2. Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the ScalableDOMOut in the External References area.

    The JDeveloper composite.xml appears, as shown in Figure 5-100.

    Figure 5-100 The JDeveloper - Composite.xml

    Description of Figure 5-100 follows
    Description of "Figure 5-100 The JDeveloper - Composite.xml"
  3. Click File, Save All.
5.5.4.5.1 Add a Receive Activity
  1. Double-click BPELScalableDOM. The BPELScalableDOM.bpel page is displayed.
  2. Drag and drop a Receive activity from the Components window to the design area.
  3. Double-click the Receive activity. The Receive dialog is displayed.
  4. Enter ReceiveFile in the Name field.
  5. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  6. Select ScalableDOMIn, as shown in Figure 5-101, and click OK.

    Figure 5-101 The Partner Link Chooser Dialog

    Description of Figure 5-101 follows
    Description of "Figure 5-101 The Partner Link Chooser Dialog"
  7. Click the Auto-Create Variable icon to the right of the Variable field in the Receive dialog. The Create Variable dialog is displayed.
  8. Select the default variable name and click OK. The Variable field is populated with the default variable name.
  9. Check Create Instance, and click OK. The JDeveloper composite.xml page appears, as shown in Figure 5-102.

    Figure 5-102 The JDeveloper - BPELScalableDOM.bpel

    Description of Figure 5-102 follows
    Description of "Figure 5-102 The JDeveloper - BPELScalableDOM.bpel"
5.5.4.5.2 Add an Invoke Activity
  1. Drag and drop an Invoke activity from the Components window to the design area.
  2. Double-click the Invoke activity. The Invoke dialog is displayed.
  3. Enter WriteFile in the Name field.
  4. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  5. Select ScalableDOMOut, and click OK.
  6. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog. The Create Variable dialog is displayed.
  7. Select the default variable name and click OK. The Input variable field is populated with the default variable name. The Invoke dialog is displayed.
  8. Click OK. The JDeveloper BPELScalableDOM.bpel page appears, as shown in Figure 5-103.

    Figure 5-103 The JDeveloper - BPELScalableDOM.bpel Page

    Description of Figure 5-103 follows
    Description of "Figure 5-103 The JDeveloper - BPELScalableDOM.bpel Page"
5.5.4.5.3 Add an Assign Activity
  1. Drag and drop an Assign activity from the Components window in between the Receive and Invoke activities in the design area.
  2. Double-click the Assign activity. The Assign dialog is displayed.
  3. Enter AssignPayload in the Name field.
  4. Click the Copy Operation tab. The Assign dialog is displayed, as shown in Figure 5-104.

    Figure 5-104 The Assign Dialog - Copy Operation Tab

    Description of Figure 5-104 follows
    Description of "Figure 5-104 The Assign Dialog - Copy Operation Tab"
  5. Select Copy Operation. The Create Copy Operation dialog is displayed.
  6. Expand the variables in the From and To panes, as shown in Figure 5-105.

    Figure 5-105 The Create Copy Operation Dialog

    Description of Figure 5-105 follows
    Description of "Figure 5-105 The Create Copy Operation Dialog"
  7. Click OK. The Assign dialog is displayed, as shown in Figure 5-106.

    Figure 5-106 The Assign Dialog

    Description of Figure 5-106 follows
    Description of "Figure 5-106 The Assign Dialog"
  8. Click OK, the JDeveloper BPELScalableDOM.bpel page is displayed, as shown in Figure 5-107.

    Figure 5-107 The JDeveloper - BPELScalableDOM.bpel

    Description of Figure 5-107 follows
    Description of "Figure 5-107 The JDeveloper - BPELScalableDOM.bpel"
  9. Click File, Save All.
5.5.4.6 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
5.5.4.7 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.
  2. Copy the address-csv-large.txt file that you created (see Prerequisites) to the input directory and ensure it gets processed. Check the output directory to ensure that an output file has been created.
  3. Click the SOA composite that you deployed. The Dashboard is displayed.

    Note your Instance ID in the Recent Instances area.

  4. Click the Instances tab. The Instance IDs of the SOA composite are listed.
  5. Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.
  6. Click your BPEL process instance. The Audit Trail of the BPEL process instance is displayed.
  7. Expand a payload node to view payload details.
  8. Click the Flow tab to view the process flow. Click an activity to view the details of the activity.

5.5.5 Oracle File Adapter Chunked Read

Chunked Read is an Oracle File Adapter feature that uses an invoke activity within a while loop to process the target file. This feature enables you to process arbitrarily large files.

This section includes the following topics:

5.5.5.1 Prerequisites

To perform the Oracle File Adapter ChunkRead operation, you must first create the following files:

  • address-csv.xsd

  • address-fixedLength.xsd

  • addr1Toaddr2.xsl

  • address-csv.txt

Contents of address-csv.xsd

<?xml version="1.0" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
            targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
            xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
            elementFormDefault="qualified"
            attributeFormDefault="unqualified" nxsd:encoding="US-ASCII" nxsd:hasHeader="true" nxsd:headerLines="1" nxsd:linesTerminatedBy="${eol}" nxsd:stream="chars" nxsd:version="NXSD">
  <xsd:element name="Root-Element">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Address" minOccurs="1" maxOccurs="unbounded">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="Name" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Street1" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Street2" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="City" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="State" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="&quot;">
              </xsd:element>
              <xsd:element name="Country" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="${eol}" nxsd:quotedBy="&quot;">
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>
<!--NXSDWIZ:D:\work\jDevProjects\BPEL\FlatStructure\address-csv.txt:-->

Contents of address-fixedLength.xsd

<?xml version="1.0" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
            targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/fixedLength"
            xmlns:fix="http://xmlns.oracle.com/pcbpel/demoSchema/fixedLength"
            elementFormDefault="qualified"
            attributeFormDefault="unqualified" nxsd:encoding="US-ASCII" nxsd:stream="chars" nxsd:version="NXSD">
  <xsd:element name="Root-Element">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Address" minOccurs="1" maxOccurs="unbounded" nxsd:style="array" nxsd:cellSeparatedBy="\r\n">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="Name" type="xsd:string" nxsd:style="fixedLength" nxsd:length="38">
              </xsd:element>
              <xsd:element name="Street" type="xsd:string" nxsd:style="fixedLength" nxsd:length="80">
              </xsd:element>
              <xsd:element name="City" type="xsd:string" nxsd:style="fixedLength" nxsd:length="11">
              </xsd:element>
              <xsd:element name="State" type="xsd:string" nxsd:style="fixedLength" nxsd:length="11">
              </xsd:element>
              <xsd:element name="Country" type="xsd:string" nxsd:style="fixedLength" nxsd:length="7">
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>
<!--NXSDWIZ:C:\orabpel\samples\tutorials\121.FileAdapter\FlatStructure\outputDir\csv_2004.11.10.txt:-->

Contents of addr1Toaddr2.xsl

<?xml version="1.0" encoding="windows-1252"?>
<?oracle-xsl-mapper
  <!-- SPECIFICATION OF MAP SOURCES AND TARGETS, DO NOT MODIFY. -->
  <mapSources>
    <source type="XSD">
      <schema location="xsd/address-csv.xsd"/>
      <rootElement name="Root-Element" namespace="http://xmlns.oracle.com/pcbpel/demoSchema/csv"/>
    </source>
  </mapSources>
  <mapTargets>
    <target type="XSD">
      <schema location="xsd/address-fixedLength.xsd"/>
      <rootElement name="Root-Element" namespace="http://xmlns.oracle.com/pcbpel/demoSchema/fixedLength"/>
    </target>
  </mapTargets>
  <!-- GENERATED BY ORACLE XSL MAPPER 1.0 AT [TUE NOV 16 16:14:01 IST 2004]. -->
?>
<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/csv"
                xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
                xmlns:fix="http://xmlns.oracle.com/pcbpel/demoSchema/fixedLength"
                exclude-result-prefixes="xsl xsd tns nxsd fix">
  <xsl:template match="/">
    <fix:Root-Element>
      <xsl:for-each select="/tns:Root-Element/tns:Address">
        <fix:Address>
          <fix:Name>
            <xsl:value-of select="tns:Name"/>
          </fix:Name>
          <fix:Street>
            <xsl:value-of select="concat(tns:Street1,tns:Street2)"/>
          </fix:Street>
          <fix:City>
            <xsl:value-of select="tns:City"/>
          </fix:City>
          <fix:State>
            <xsl:value-of select="tns:State"/>
          </fix:State>
          <fix:Country>
            <xsl:value-of select="tns:Country"/>
          </fix:Country>
        </fix:Address>
      </xsl:for-each>
    </fix:Root-Element>
  </xsl:template>
</xsl:stylesheet>

Contents of address-csv.txt

Name,Street1,Street2,City,State,Country
Oracle India Private Limited, Lexington Towers Prestige St. John's Woods, 2nd Cross Road Chikka Audugodi, Bangalore, Karnataka, India
Intel Technology India Private Limited, Survey #23-56 P Devarabeesanahalli Village, Outer Ring Road Varthur Hobli, Bangalore, Karnataka, India
5.5.5.2 Designing the SOA Composite

You must create a JDeveloper application to contain the SOA composite application. To create an application and a project for the use case, perform the following steps:

  1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.
  2. Enter SOA-ChunkedRead in the Application Name field, and click Next. The Create Generic Application - Name your project page is displayed.
  3. Enter ChunkedRead in the Project Name field.
  4. In the Available list under the Project Technologies tab, double-click SOA to move it to the Selected list.
  5. Click Next. The Configure SOA settings dialog appears.
  6. Select Composite With BPEL in the Composite Template box, and click Finish. The Create BPEL Process - BPEL Process page is displayed.
  7. Enter BPELChunkedRead in the Name field, select Define Service Later from the Template box.
  8. Click OK. The SOA-ChunkedRead application and the ChunkedRead project appears in the design area, as shown in Figure 5-108.

    Figure 5-108 The JDeveloper - Composite.xml

    Description of Figure 5-108 follows
    Description of "Figure 5-108 The JDeveloper - Composite.xml"
  9. Copy the address-csv.xsd and address-fixedLength.xsd files that you created (see Prerequisites) to the xsd directory in your project .
  10. Copy addr1Toaddr2.xsl that you created (see Prerequisites) to the xsl directory of your project.
5.5.5.3 Creating the Inbound Oracle File Adapter Service

Perform the following steps to create an inbound Oracle File Adapter service to read the file from a local directory:

  1. Drag and drop File Adapter from the Components window to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter FileInNoPayloadIn in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next. The FTP Server Connection page is displayed.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select Read File, check Do Not Read File Content box, and then click Next. The File Directories page is displayed.
  7. Enter the physical path for the input directory. Check Process Files Recursively.
  8. Click Next. The File Filtering page is displayed.
  9. Enter *.txt in the Include Files With Name Pattern field, click Next. The File Polling page is displayed.
  10. Click Next.
  11. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  12. Click Finish. The inbound Oracle File Adapter is now configured and composite.xml appears, as shown in Figure 5-109.

    Figure 5-109 The JDeveloper - Composite.xml

    Description of Figure 5-109 follows
    Description of "Figure 5-109 The JDeveloper - Composite.xml"
5.5.5.4 Creating the Outbound Oracle File Adapter Service

Perform the following steps to create an outbound Oracle File Adapter service to write the file from a local directory to the FTP server:

  1. Drag and drop File Adapter from the Components window to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter ReadAddressChunk in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next. The FTP Server Connection is displayed.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select Synchronous Read File, enter ChunkedRead in the Operation Name field, and then click Next. The File Directories page is displayed.
  7. Enter the physical path for the output directory and select Delete Files After Successful Retrieval.
  8. Click Next. The File Name page is displayed.
  9. Enter dummy.txt in the File Name field.
  10. Click Next. The Messages page is displayed.
  11. Click Browse For Schema File that appears at the end of the URL field. The Type Chooser dialog is displayed.
  12. Click Project Schema Files, address-csv.xsd, and Root-Element.
  13. Click OK. The URL field in the Messages page is populated with the address-csv.xsd file.
  14. Click Next.
  15. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  16. Click Finish. The outbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-110 The JDeveloper - Composite.xml

    Description of Figure 5-110 follows
    Description of "Figure 5-110 The JDeveloper - Composite.xml"
  17. Manually edit the metadata to incorporate the Chunked Read feature.

    Open ReadAddressChunk_file.jca file and modify the metadata as shown the example below.

    Example - Modifying Metadata to Incorporate the Chunked Read Feature

    <?xml version="1.0" encoding="UTF-8"?>
<adapter-config name="ReadAddressChunk" 
                adapter="File Adapter" 
xmlns="http://platform.integration.oracle/blocks
              /adapter/fw/metadata">
  <connection-factory location="eis/FileAdapter" 
                            adapterRef=""/>
  <endpoint-interaction portType="ChunkedRead_ptt" 
                    operation="ChunkedRead">
    <interaction-spec 
className="oracle.tip.adapter.file.
                       outbound.ChunkedInteractionSpec">
      <property name="PhysicalDirectory" 
                           value="/tmp/chunked/in"/>
      <property name="FileName" value="dummy.txt"/>
      <property name="ChunkSize" value="1"/>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>
  18. Click File, Save All.
5.5.5.4.1 Add Another Outbound Oracle File Adapter Service
  1. Drag and drop File Adapter from the Components window to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Click Next. The Service Name page is displayed.
  3. Enter AppendChunk in the Service Name field.
  4. Click Next. The Adapter Interface page is displayed.
  5. Select Define from operation and schema (specified later), and click Next. The Operation page is displayed.
  6. Select Write File, enter Write in the Operation Name field, and then click Next. The File Configuration page is displayed.
  7. Enter the physical path for the output directory, enter dummy.txt in the File Naming Convention (po_%SEQ%.txt) and select Append to Existing File.
  8. Click Next. The Messages page is displayed.
  9. Click Browse For Schema File that appears at the end of the URL field. The Type Chooser dialog is displayed.
  10. Click Project Schema Files, address-fixedLength.xsd, and Root-Element.
  11. Click OK. The URL field in the Messages page is populated with the address-fixedLength.xsd file.
  12. Click Next. The Finish page is displayed.
  13. Click Finish. The outbound Oracle File Adapter is now configured and composite.xml appears, as shown in Figure 5-111.

    Figure 5-111 The JDeveloper - Composite.xml

    Description of Figure 5-111 follows
    Description of "Figure 5-111 The JDeveloper - Composite.xml"
5.5.5.5 Wiring Services and Activities

You must assemble or wire the three components that you have created: Inbound adapter service, BPEL process, two Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the FileInNoPayloadIn in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
  2. Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the ReadAddressChunk in the External References area and also to the green triangle in the AppendChunk in the External References area.

    The JDeveloper composite.xml appears, as shown in Figure 5-112.

    Figure 5-112 The JDeveloper - Composite.xml

    Description of Figure 5-112 follows
    Description of "Figure 5-112 The JDeveloper - Composite.xml"
  3. Click File, Save All.
5.5.5.5.1 Add a Receive Activity
  1. Double-click BPELChunkedRead. The BPELChunkedRead.bpel page is displayed.
  2. Click the Variables... icon represented by (x). The Variables dialog is displayed.
  3. Click the Create... icon. The Create Variable dialog is displayed.
  4. Create the following variables, as shown in Figure 5-113, for later use:
     <variable name="dir" type="xsd:string"/>
    <variable name="file" type="xsd:string"/>
    <variable name="outIsEOF" type="xsd:string"/>
    <variable name="outLineNumber" type="xsd:string"/>
    <variable name="outColumnNumber" type="xsd:string"/>
    <variable name="returnIsEOF" type="xsd:string"/>
    <variable name="returnLineNumber" type="xsd:string"/>
    <variable name="returnColumnNumber" type="xsd:string"/>
    <variable name="returnIsMessageRejected"                                    type="xsd:string"/>
    <variable name="returnRejectionReason" type="xsd:string"/>
    <variable name="returnNoDataFound" type="xsd:string"/>

    Figure 5-113 The Variables Dialog

    Description of Figure 5-113 follows
    Description of "Figure 5-113 The Variables Dialog"

    Note:

    All variables are Simple Types of type xsd:string.

  5. Drag and drop a Receive activity from the Components window to the design area.
  6. Double-click the Receive activity. The Receive dialog is displayed.
  7. Enter ReceiveFileDetails in the Name field.
  8. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  9. Select FileInNoPayloadIn, and click OK.
  10. Click the Auto-Create Variable icon to the right of the Variable field in the Receive dialog. The Create Variable dialog is displayed.
  11. Select the default variable name and click OK. The Variable field is populated with the default variable name.
  12. Check Create Instance.
  13. Click the Properties tab. The properties and the corresponding value column is displayed.
  14. Select jca.file.Directory property. Double-click in the corresponding value column. The Adapter Property value dialog is displayed.
  15. Click the Browse Variables icon. The Variable XPath Builder dialog is displayed.
  16. Expand Variables, select dir, and then click OK. The value of the jca.file.Directory is set to dir.
  17. Repeat the same for jca.file.FileName property and set the value to file. The Receive dialog is displayed, as shown in Figure 5-114.

    Figure 5-114 The Receive Dialog - Adapters Tab

    Figure showing a Receive dialog box .
  18. Click OK. The JDeveloper BPELChunkedRead.bpel page appears, as shown in Figure 5-115.

    Figure 5-115 The JDeveloper - BPELChunkedRead.bpel

    Description of Figure 5-115 follows
    Description of "Figure 5-115 The JDeveloper - BPELChunkedRead.bpel"
5.5.5.5.2 Add an Assign Activity
  1. Drag and drop an Assign activity from the Components window after the Receive activity in the design area.
  2. Double-click the Assign activity. The Assign dialog is displayed.
  3. Enter AssignChunkedRead in the Name field.
  4. Click the Copy Operation tab. The Assign dialog is displayed, as shown in Figure 5-104.
  5. Select Copy Operation. The Create Copy Operation dialog is displayed.
  6. Set the default values for the headers, as shown in Figure 5-116.

    Figure 5-116 The Assign Dialog

    Description of Figure 5-116 follows
    Description of "Figure 5-116 The Assign Dialog"
  7. Click OK, the JDeveloper BPELChunkedRead.bpel page is displayed, as shown in Figure 5-117.

    Figure 5-117 The JDeveloper - BPELChunkedRead.bpel

    Description of Figure 5-117 follows
    Description of "Figure 5-117 The JDeveloper - BPELChunkedRead.bpel"
  8. Click File, Save All.
5.5.5.5.3 Add an Invoke Activity
  1. Drag and drop an Invoke activity below the Assign Activity from the Components window to the design area.
  2. Double-click the Invoke activity. The Invoke dialog is displayed.
  3. Enter InvokeReadAddress in the Name field.
  4. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  5. Select ReadAddressChunk, and click OK.
  6. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog. The Create Variable dialog is displayed.
  7. Select the default variable name and click OK. The Variable field is populated with the default variable name. The Invoke dialog is displayed with input variable populated.
  8. Repeat the same to select the output variable. The Invoke dialog is displayed, as shown in Figure 5-118.

    Figure 5-118 The Invoke Dialog

    Description of Figure 5-118 follows
    Description of "Figure 5-118 The Invoke Dialog"
  9. Click OK. The JDeveloper BPELChunkedRead.bpel page appears, as shown in Figure 5-119.

    Figure 5-119 The JDeveloper - BPELChunkedRead.bpel

    Description of Figure 5-119 follows
    Description of "Figure 5-119 The JDeveloper - BPELChunkedRead.bpel"
  10. Click the Source tab for the BPELChunkedRead.bpel page, and add the following properties for the Invoke activity that you just created:

    Example - Properties to Add to the Invoke Activity

    <bpelx:inputProperty name="jca.file.Directory" 
                 variable="dir"/>
<bpelx:inputProperty name="jca.file.FileName" 
                   variable="file"/>
<bpelx:inputProperty name="jca.file.LineNumber" 
                                 ="outLineNumber"/>
<bpelx:inputProperty name="jca.file.ColumnNumber" 
variable="outColumnNumber"/>
<bpelx:inputProperty name="jca.file.IsEOF" 
                           variable="outIsEOF"/>
<bpelx:outputProperty name="jca.file.LineNumber" 
variable="returnLineNumber"/>
<bpelx:outputProperty name="jca.file.ColumnNumber" 
variable="returnColumnNumber"/>
<bpelx:outputProperty name="jca.file.IsEOF" 
                   variable="returnIsEOF"/>
<bpelx:outputProperty 
               name="jca.file.IsMessageRejected" 
variable="returnIsMessageRejected"/>
<bpelx:outputProperty 
              name="jca.file.RejectionReason" 
variable="returnRejectionReason"/>
<bpelx:outputProperty name="jca.file.NoDataFound" 
variable="returnNoDataFound"/>

    Note that this is different for BPEL 2.0. For that version of BPEL, this would appear as shown in the example below.

    Example - Properties to Add for Invoke using BPEL 2.0

    <bpelx:toProperties> 
<bpelx:toProperty name="jca.file.Directory" variable="dir"/> 
<bpelx:toProperty name="jca.file.FileName" variable="file"/> 
<bpelx:toProperty name="jca.file.LineNumber" 
                    variable="outLineNumber"/> 
<bpelx:toProperty name="jca.file.ColumnNumber" 
                variable="outColumnNumber"/> 
<bpelx:toProperty name="jca.file.IsEOF"
               variable="outIsEOF"/> 
  </bpelx:toProperties> 
  <bpelx:fromProperties> 
<bpelx:fromProperty name="jca.file.LineNumber" 
                  variable="returnLineNumber"/> 
<bpelx:fromProperty name="jca.file.ColumnNumber" 
variable="returnColumnNumber"/> 
<bpelx:fromProperty name="jca.file.IsEOF" 
                  variable="returnIsEOF"/> 
<bpelx:fromProperty 
              name="jca.file.IsMessageRejected" 
variable="returnIsMessageRejected"/> 
<bpelx:fromProperty name="jca.file.RejectionReason" 
variable="returnRejectionReason"/> 
<bpelx:fromProperty 
              name="jca.file.NoDataFound" 
variable="returnNoDataFound"/> 
  </bpelx:fromProperties

    The Invoke activity appears as shown in the example below.

    Example - Invoke Activity

    <invoke name="InvokeReadAddress"
inputVariable="InvokeReadAddress_SynchRead_InputVariable"
outputVariable="InvokeReadAddress_SynchRead_OutputVariable"
partnerLink="ReadAddressChunk" portType="ns3:SynchRead_ptt"
operation="SynchRead">
<bpelx:inputProperty name="jca.file.Directory" variable="dir"/>
<bpelx:inputProperty name="jca.file.FileName" variable="file"/>
<bpelx:inputProperty name="jca.file.LineNumber" 
              variable="outLineNumber"/>
<bpelx:inputProperty name="jca.file.ColumnNumber" 
variable="outColumnNumber"/>
<bpelx:inputProperty name="jca.file.IsEOF" 
               variable="outIsEOF"/>
<bpelx:outputProperty name="jca.file.LineNumber" 
variable="returnLineNumber"/>
<bpelx:outputProperty name="jca.file.ColumnNumber" 
variable="returnColumnNumber"/>
<bpelx:outputProperty name="jca.file.IsEOF" 
                   variable="returnIsEOF"/>
<bpelx:outputProperty name="jca.file.IsMessageRejected" variable="returnIsMessageRejected"/>
<bpelx:outputProperty name="jca.file.RejectionReason" 
variable="returnRejectionReason"/>
<bpelx:outputProperty name="jca.file.NoDataFound" 
variable="returnNoDataFound"/>
</invoke>
  11. Add an assign activity called CopyHeaders, as given in Add an Assign Activity, to copy the return parameters from the invoke activity. The Assign dialog is displayed, as shown in Figure 5-120.

    Figure 5-120 The Assign Dialog

    Description of Figure 5-120 follows
    Description of "Figure 5-120 The Assign Dialog"
  12. Click OK. The JDeveloper BPELChunkedRead.bpel page is displayed, as shown in Figure 5-121.

    Figure 5-121 The JDeveloper - BPELChunkedRead.bpel

    Description of Figure 5-121 follows
    Description of "Figure 5-121 The JDeveloper - BPELChunkedRead.bpel"
5.5.5.5.4 Add a Switch Activity
  1. Drag and drop a Switch activity below the CopyHeaders Assign activity.
  2. Double-click <case> in the Switch activity. The Switch Case dialog is displayed.
  3. Enter DATA FOUND in the Name field and select the returnNoDataFound expression in the Expression box. The Switch Case dialog is displayed, as shown in Figure 5-122.

    Figure 5-122 The Switch Case Dialog

    Description of Figure 5-122 follows
    Description of "Figure 5-122 The Switch Case Dialog"
  4. Drag and drop an Invoke activity in the <Case DATA FOUND> for Switch Activity.
  5. Double-click the Invoke activity. The Invoke dialog is displayed.
  6. Enter InvokeAppend in the Name field.
  7. Select AppendChunk in the Partner Link field.
  8. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog. The Create Variable dialog is displayed.
  9. Select the default variable name and click OK. The Variable field is populated with the default variable name. The Invoke dialog is displayed with input variable populated.
  10. Click the Properties tab and select file variable, as shown in Figure 5-123.

    Figure 5-123 The Invoke Dialog

    Description of Figure 5-123 follows
    Description of "Figure 5-123 The Invoke Dialog"
  11. Click OK.
5.5.5.5.5 Add a Transform Activity
  1. Drag and drop a Transform activity in the <case DATA FOUND> section just before the InvokeAppend activity.
  2. Double-click the Transform activity.
  3. Enter TransformPayload in the Name field.
  4. Click the Transformation tab.
  5. Click the Create... icon. The Source Variable dialog is displayed.
  6. Select InvokeReadAddress_SyncRead_InputVariable, and click OK.
  7. Select InvokeAppend_Write_InputVariable from the Target Variable list.
  8. Click Browse at the end of the Mapper File field, and select the addr1Toaddr2.xsl file.
  9. Click OK.
  10. Drag and drop an Empty activity in the <otherwise> section in the Switch activity. The BPELChunkedRead.bpel page is displayed, as shown in Figure 5-124.

    Figure 5-124 The JDeveloper - BPELChunkedRead.bpel

    Description of Figure 5-124 follows
    Description of "Figure 5-124 The JDeveloper - BPELChunkedRead.bpel"
  11. Click File, Save All.
5.5.5.6 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
5.5.5.7 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.
  2. Copy the address-csv.txt file that you created (see Prerequisites) to the input directory and ensure it gets processed. Check the output directory to ensure that an output file has been created.
  3. Click the SOA composite that you deployed. The Dashboard is displayed.

    Note your Instance ID in the Recent Instances area.

  4. Click the Instances tab. The Instance IDs of the SOA composite are listed.
  5. Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.
  6. Click your BPEL process instance. The Audit Trail of the BPEL process instance is displayed.
  7. Expand a payload node to view payload details.
  8. Click the Flow tab to view the process flow. Click an activity to view the details of the activity.

5.5.6 Oracle File Adapter Read File As Attachments

This is an Oracle File Adapter feature to opaquely copy or move large amount of data, from a source directory on your file system to a destination directory, as attachments. For example, you can transfer large MS Word documents, images, and PDFs without processing their content within the composite application. The read file as attachment feature is available only when the Read File option is chosen.

This use case demonstrates the ability of the Oracle File Adapter to process a large *.doc file as an attachment. This feature of reading files as attachments is very similar to Opaque translation. However, attachments can be of the order of gigabytes depending on database limitations.

This section includes the following topics:

5.5.6.1 Prerequisites

To use the Oracle File Adapter read file as attachments feature, you require a large MS Word document (*.doc file).

5.5.6.2 Designing the SOA Composite

You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following steps:

  1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.
  2. Enter AttachmentApp in the Application Name field, and click Next. The Create Generic Application - Name your project page is displayed.
  3. Enter Attachment in the Project Name field.
  4. In the Available list under the Project Technologies tab, double-click SOA to move it to the Selected list.
  5. Click Next. The Configure SOA settings dialog appears.
  6. Select Composite With BPEL in the Composite Template box, and click Finish. The Create BPEL Process - BPEL Process page is displayed.
  7. Enter BPELAttachment in the Name field, select Define Service Later from the Template list.
  8. Click OK. The AttachmentApp application and the Attachment project appear in the design area, as shown in Figure 5-125.

    Figure 5-125 The JDeveloper - Composite.xml

    Description of Figure 5-125 follows
    Description of "Figure 5-125 The JDeveloper - Composite.xml"
5.5.6.3 Creating the Inbound Oracle File Adapter Service

Perform the following steps to create an inbound Oracle File Adapter service to read a large file from a local directory:

  1. Drag and drop File Adapter from the Components window to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter AttachmentIn in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next. The FTP Server Connection page is displayed.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select Read File as the Operation Type and select Read File As Attachment, and then click Next. The File Directories page is displayed.

    Note:

    Ignore Character Set, Encoding, and Content Type fields. These fields must be populated with values only if you are using third-party applications that must read this attachment. The attachment in this use case is finally consumed by an outbound Oracle File Adapter, hence these values are not required.

    Figure 5-126 The Adapter Configuration Wizard Operation Page

    Description of Figure 5-126 follows
    Description of "Figure 5-126 The Adapter Configuration Wizard Operation Page"
  7. Enter the physical path for the input directory, as shown in Figure 5-66 and click Next. The File Filtering page is displayed.
  8. Enter *.doc in the Include Files With Name Pattern field, as shown in Figure 5-67.
  9. Click Next. The File Polling page is displayed.
  10. Click Next.
  11. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  12. Click Finish. The inbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-127 The JDeveloper - Composite.xml

    Description of Figure 5-127 follows
    Description of "Figure 5-127 The JDeveloper - Composite.xml"
5.5.6.4 Creating the Outbound Oracle File Adapter Service

Perform the following steps to create an outbound Oracle File Adapter service to write the file from a local directory to the FTP server:

  1. Drag and drop File Adapter from the Components window to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter AttachmentOut in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select Write File, and click Next. The File Configuration page is displayed.
  7. Enter the physical path for the output directory and enter attachment_%SEQ%.doc in the File Naming Convention(po_%SEQ%.txt) field.
  8. Click Next. The Messages page is displayed.
  9. Click Browse For Schema File that appears at the end of the URL field. The Type Chooser dialog is displayed.
  10. Click Project WSDL Files, AttachmentIn.wsdl, Inline Schemas, and attachmentElement.

    Figure 5-128 The Type Chooser Dialog

    Description of Figure 5-128 follows
    Description of "Figure 5-128 The Type Chooser Dialog"
  11. Click OK. The URL field in the Messages page is populated with AttachmentIn.wsdl.
  12. Click Next.
  13. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  14. Click Finish. The outbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-129 The JDeveloper - Composite.xml

    Description of Figure 5-129 follows
    Description of "Figure 5-129 The JDeveloper - Composite.xml"
5.5.6.5 Wiring Services and Activities

You have to assemble or wire the three components that you have created: Inbound adapter service, BPEL process, Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the AttachmentIn in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
  2. Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the AttachmentOut in the External References area.

    The JDeveloper composite.xml appears, as shown in Figure 5-130.

    Figure 5-130 The JDeveloper - Composite.xml

    Description of Figure 5-130 follows
    Description of "Figure 5-130 The JDeveloper - Composite.xml"
  3. Click File, Save All.
5.5.6.5.1 Add a Receive Activity
  1. Double-click BPELAttachment. The BPELAttachment.bpel page is displayed.
  2. Drag and drop a Receive activity from the Components window to the design area.
  3. Double-click the Receive activity. The Receive dialog is displayed.
  4. Enter ReceiveInput in the Name field.
  5. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  6. Select AttachmentIn, as shown in Figure 5-131 and click OK.

    Figure 5-131 The Partner Link Chooser Dialog

    Description of Figure 5-131 follows
    Description of "Figure 5-131 The Partner Link Chooser Dialog"
  7. Click the Auto-Create Variable icon to the right of the Variable field in the Receive dialog, as shown in Figure 5-132. The Create Variable dialog is displayed.

    Figure 5-132 The Receive Dialog

    Description of Figure 5-132 follows
    Description of "Figure 5-132 The Receive Dialog"
  8. Select the default variable name and click OK. The Variable field is populated with the default variable name.
  9. Check Create Instance, and click OK. The JDeveloper BPELAttachment.bpel page appears, as shown in Figure 5-133.

    Figure 5-133 The JDeveloper - BPELXMLDebatching.bpel

    Description of Figure 5-133 follows
    Description of "Figure 5-133 The JDeveloper - BPELXMLDebatching.bpel"
5.5.6.5.2 Add an Invoke Activity
  1. Drag and drop an Invoke activity from the Components window to the design area.
  2. Double-click the Invoke activity. The Invoke dialog is displayed.
  3. Enter Write_Attachment in the Name field.
  4. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  5. Select AttachmentOut, as shown in Figure 5-134, and click OK.

    Figure 5-134 The Partner Link Chooser Dialog

    Description of Figure 5-134 follows
    Description of "Figure 5-134 The Partner Link Chooser Dialog"
  6. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog. The Create Variable dialog is displayed.
  7. Select the default variable name and click OK. The Variable field is populated with the default variable name. The Invoke dialog is displayed, as shown in Figure 5-135.

    Figure 5-135 The Invoke Dialog

    Description of Figure 5-135 follows
    Description of "Figure 5-135 The Invoke Dialog"
  8. Click OK. The JDeveloper BPELAttachment.bpel page appears, as shown in Figure 5-136.

    Figure 5-136 The JDeveloper - BPELXMLDebatching.bpel

    Description of Figure 5-136 follows
    Description of "Figure 5-136 The JDeveloper - BPELXMLDebatching.bpel"
5.5.6.5.3 Add an Assign Activity
  1. Drag and drop an Assign activity from the Components window in between the Receive and Invoke activities in the design area.
  2. Double-click the Assign activity. The Assign dialog is displayed.
  3. Enter AssignReference in the Name field.
  4. Click the Copy Operation tab. The Assign dialog is displayed, as shown in Figure 5-137.

    Figure 5-137 The Assign Dialog - Copy Operation Tab

    Description of Figure 5-137 follows
    Description of "Figure 5-137 The Assign Dialog - Copy Operation Tab"
  5. Select Copy Operation. The Create Copy Operation dialog is displayed.
  6. Expand the variables in the From and To panes, as shown in Figure 5-138.

    Figure 5-138 The Create Copy Operation Dialog

    Description of Figure 5-138 follows
    Description of "Figure 5-138 The Create Copy Operation Dialog"

    Note:

    When variables are defined by reference to an element, both the source and the target must be the same element.

  7. Click OK. The Assign dialog is displayed, as shown in Figure 5-139.

    Figure 5-139 The Assign Dialog

    Description of Figure 5-139 follows
    Description of "Figure 5-139 The Assign Dialog"
  8. Click OK, the JDeveloper BPELAttachment.bpel page is displayed, as shown in Figure 5-140.

    Figure 5-140 The JDeveloper - BPELScalableDOM.bpel

    Description of Figure 5-140 follows
    Description of "Figure 5-140 The JDeveloper - BPELScalableDOM.bpel"
  9. Click File, Save All.
5.5.6.6 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
5.5.6.7 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.
  2. Copy the attachment.doc file that you created (see Prerequisites) to the input directory and ensure it gets processed. Check the output directory to ensure that an output file has been created.
  3. Click the SOA composite that you deployed. The Dashboard is displayed.

    Note your Instance ID in the Recent Instances area.

  4. Click the Instances tab. The Instance IDs of the SOA composite are listed.
  5. Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.
  6. Click your BPEL process instance. The Audit Trail of the BPEL process instance is displayed.
  7. Expand a payload node to view payload details.
  8. Click the Flow tab to view the process flow. Click an activity to view the details of the activity.

5.5.7 Oracle File Adapter File Listing

This is an Oracle File Adapter feature that lets you use an invoke activity to retrieve a list of files from a target directory. This list of files is returned as an XML document and contains information such as file name, directory name, file size, and last modified time.

This section includes the following topics:

5.5.7.1 Prerequisites

To perform Oracle File Adapter Listing, you require *.txt files. You must create and save the *.txt files in the target directory.

5.5.7.2 Designing the SOA Composite

You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following steps:

  1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.
  2. Enter FileListingApp in the Application Name field, and click Next. The Create Generic Application - Name your project page is displayed.
  3. Enter FileListing in the Project Name field.
  4. In the Available list under the Project Technologies tab, double-click SOA to move it to the Selected list.
  5. Click Next. The Configure SOA settings dialog appears.
  6. Select Composite With BPEL in the Composite Template box, and click Finish. The Create BPEL Process - BPEL Process page is displayed.
  7. Enter BPELFileListing in the Name field, and select One Way BPEL Process from the Template box.
  8. Click OK. The FileListingApp application and the FileListing project appear in the design area, as shown in Figure 5-141.

    Figure 5-141 The JDeveloper - Composite.xml

    Description of Figure 5-141 follows
    Description of "Figure 5-141 The JDeveloper - Composite.xml"
5.5.7.3 Creating the Outbound Oracle File Adapter Service

Perform the following steps to create an outbound Oracle File Adapter service to list the file from a target directory:

  1. Drag and drop File Adapter from the Components window to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter ListFiles in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select List Files, enter FileListing in the Operation Name field, and then click Next. The File Directories page is displayed.
  7. Enter the physical path for the input directory.
  8. Click Next. The File Filtering page is displayed.
  9. Enter *.txt in the Include Files with Name Pattern field.
  10. Click Next.
  11. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  12. Click Finish. The outbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-142 The JDeveloper - Composite.xml

    Description of Figure 5-142 follows
    Description of "Figure 5-142 The JDeveloper - Composite.xml"
  13. Click File, Save All.
5.5.7.4 Wiring Services and Activities

You have to assemble or wire the two components that you have created: BPEL process, and the Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in ListFiles in the External References area.

    The JDeveloper composite.xml appears, as shown in Figure 5-143.

    Figure 5-143 The JDeveloper - Composite.xml

    Description of Figure 5-143 follows
    Description of "Figure 5-143 The JDeveloper - Composite.xml"
  2. Click File, Save All.
5.5.7.4.1 Create a String Variable
  1. Double-click BPELFileListing. The BPELFileListing.bpel page is displayed.
  2. Click the Variables... icon represented by (x). The Variables dialog is displayed.
  3. Click the Create... icon. The Create Variable dialog is displayed.
  4. Create a variable, MyDir of type xsd:string, as shown in Figure 5-144, for later use.

    Figure 5-144 The Variables Dialog

    Description of Figure 5-144 follows
    Description of "Figure 5-144 The Variables Dialog"
  5. Click OK. The JDeveloper BPELFileListing.bpel page appears, as shown in Figure 5-145

    Figure 5-145 The JDeveloper - BPELFileListing.bpel

    Description of Figure 5-145 follows
    Description of "Figure 5-145 The JDeveloper - BPELFileListing.bpel"
5.5.7.4.2 Add an Invoke Activity
  1. Drag and drop an Invoke activity below the receive Activity from the Components window to the design area.
  2. Double-click the Invoke activity. The Invoke dialog is displayed.
  3. Enter InvokeListFiles in the Name field.
  4. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  5. Select ListFiles, and click OK.
  6. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog. The Create Variable dialog is displayed.
  7. Select the default variable name and select OK. The Variable field is populated with the default variable name. The Invoke dialog is displayed with input variable populated.
  8. Repeat the same to select the output variable. The Invoke dialog is displayed, as shown in Figure 5-146.

    Figure 5-146 The Invoke Dialog

    Description of Figure 5-146 follows
    Description of "Figure 5-146 The Invoke Dialog"
  9. Click the Properties tab. The properties and the corresponding value column is displayed.
  10. Select jca.file.Directory property. Double-click in the corresponding value column. The Adapter Property Value dialog is displayed.
  11. Click the Browse Variables icon. The Variable XPath Builder dialog is displayed.
  12. Expand Variables, select MyDir, and then click OK. The value of the jca.file.Directory is set to Mydir.
  13. Click OK. The JDeveloper BPELFileListing.bpel page appears, as shown in Figure 5-147.

    Figure 5-147 The JDeveloper - BPELFileListing.bpel

    Description of Figure 5-147 follows
    Description of "Figure 5-147 The JDeveloper - BPELFileListing.bpel"
5.5.7.4.3 Add an Assign Activity
  1. Drag and drop an Assign activity from the Components window in between the Receive activities and the Invoke activity in the design area.
  2. Double-click the Assign activity. The Assign dialog is displayed.
  3. Enter AssignDirName in the Name field.
  4. Click the Copy Operation tab. The Assign dialog is displayed.
  5. Select Copy Operation. The Create Copy Operation dialog is displayed.
  6. Set the values for the headers, as shown in Figure 5-148.

    Figure 5-148 The Assign Dialog

    Description of Figure 5-148 follows
    Description of "Figure 5-148 The Assign Dialog"
  7. Click OK, the JDeveloper BPELFileListing.bpel page is displayed, as shown in Figure 5-149.

    Figure 5-149 The JDeveloper - BPELFileListing.bpel

    Description of Figure 5-149 follows
    Description of "Figure 5-149 The JDeveloper - BPELFileListing.bpel"
  8. Click File, Save All.
5.5.7.5 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
5.5.7.6 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.
  2. Copy the *.txt files that you created (see Prerequisites) to the input directory and ensure they gets processed. Check the output directory to ensure that output files have been created.
  3. Click the SOA composite that you deployed. The Dashboard is displayed.

    Note your Instance ID in the Recent Instances area.

  4. Click the Instances tab. The Instance IDs of the SOA composite are listed.
  5. Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.
  6. Click your BPEL process instance. The Audit Trail of the BPEL process instance is displayed.
  7. Expand a payload node to view payload details.
  8. Click the Flow tab to view the process flow. Click an activity to view the details of the activity.

5.5.8 Oracle File Adapter Complex Structure

This use case demonstrates the ability of the Oracle File Adapter to process native data defined in a custom format. In this sample, the custom format represents an invoice defined in invoice-nxsd.xsd. The Oracle File Adapter processes the invoice.txt file and publishes this to the ComplexStructure BPEL process. This is then transformed to a PurchaseOrder and written out as an xml file.

This section includes the following topics:

5.5.8.1 Prerequisites

To perform the complex structure business process, you must first create the following files:

  • invoice-nxsd.xsd

  • po.xsd

  • InvToPo.xsl

  • invoice.txt

Contents of invoice-nxsd.xsd

<schema targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/invoice-nxsd"
        xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
        xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/invoice-nxsd"
        elementFormDefault="qualified" attributeFormDefault="qualified"
        nxsd:version="NXSD" nxsd:stream="chars">
  <element name="invoice" type="tns:invoiceType"/>
  <complexType name="invoiceType">
    <sequence>
      <element name="purchaser" type="tns:partnerType"/>
      <element name="seller" type="tns:partnerType"/>
      <element name="line-item" type="tns:line-itemType" maxOccurs="unbounded"
               nxsd:style="array" nxsd:cellSeparatedBy="${eol}"
               nxsd:arrayTerminatedBy="#"/>
      <element name="total" type="double" nxsd:style="terminated"
               nxsd:terminatedBy="${eol}"/>
    </sequence>
  </complexType>
  <complexType name="partnerType">
    <sequence>
      <element name="uid" type="string" nxsd:style="fixedLength" nxsd:length="7"
               nxsd:padStyle="tail" nxsd:paddedBy=" "/>
      <element name="name" type="string" nxsd:style="surrounded"
               nxsd:surroundedBy="^"/>
      <element name="address" type="tns:addressType"/>
    </sequence>
  </complexType>
  <complexType name="addressType">
    <sequence>
      <element name="street1" type="string" nxsd:style="fixedLength"
               nxsd:length="15" nxsd:padStyle="tail" nxsd:paddedBy=" "/>
      <element name="street2" type="string" nxsd:style="fixedLength"
               nxsd:length="10" nxsd:padStyle="tail" nxsd:paddedBy=" "/>
      <element name="city" type="string" nxsd:style="fixedLength"
               nxsd:length="15" nxsd:padStyle="tail" nxsd:paddedBy=" "/>
      <element name="postal-code" type="string" nxsd:style="fixedLength"
               nxsd:length="5" nxsd:padStyle="none"/>
      <element name="country" type="string" nxsd:style="fixedLength"
               nxsd:length="2" nxsd:padStyle="none"/>
      <element name="state" type="string" nxsd:style="fixedLength"
               nxsd:length="2" nxsd:padStyle="none"/>
      <element name="phone" type="string" nxsd:style="terminated"
               nxsd:terminatedBy="${eol}"/>
    </sequence>
  </complexType>
  <complexType name="line-itemType">
    <sequence>
      <element name="uid" type="string" nxsd:style="fixedLength" nxsd:length="3"
               nxsd:padStyle="none"/>
      <element name="description" type="string" nxsd:style="surrounded"
               nxsd:surroundedBy="|"/>
      <element name="price" type="double" nxsd:style="terminated"
               nxsd:terminatedBy=","/>
      <element name="quantity" type="integer" nxsd:style="terminated"
               nxsd:terminatedBy=","/>
      <element name="line-total" type="double" nxsd:style="surrounded"
               nxsd:surroundedBy="+"/>
    </sequence>
  </complexType>
</schema>

Contents of po.xsd

<schema attributeFormDefault="qualified" elementFormDefault="qualified" 
                targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/po"         
                xmlns:pons="http://xmlns.oracle.com/pcbpel/demoSchema/po"
                xmlns="http://www.w3.org/2001/XMLSchema" >
	    <element name="po" type="pons:poType"/>
	    <complexType name="poType"> 
	    	<sequence>
	    	   <element name="header" type="pons:headerType"/>
	    	   <element name="body" type="pons:bodyType"/>
	    	   <element name="footer" type="pons:footerType"/>		  
	        </sequence>
	     </complexType>
	     <complexType name="headerType"> 
	    	<sequence>
	    	   <element name="date" type="dateTime"/>
	    	   <element name="supplier" type="pons:poPartnerType"/>
	    	   <element name="buyer" type="pons:poPartnerType"/>
	    	</sequence>
	     </complexType>
	     <complexType name="poPartnerType"> 
	    	<sequence>
	    	    <element name="name" type="string"/>
	            <element name="uid" type="string"/>
	            <element name="address" type="pons:poAddressType"/>
	    	</sequence>		 
	     </complexType>
	     <complexType name="poAddressType"> 
	    	<sequence>
	    	    <element name="street" type="string"/>
	    	    <element name="city" type="string"/>
	    	    <element name="zip" type="string"/>
	    	    <element name="state" type="string"/>
	    	</sequence>
	     </complexType>	   
	     <complexType name="bodyType"> 
	    	<sequence>
	    	    <element name="item" type="pons:itemType" maxOccurs="unbounded"/>
	    	</sequence>
	     </complexType>	   
	     <complexType name="itemType"> 
	    	<sequence>
	    	    <element name="uid" type="string"/>
	    	    <element name="name" type="string"/>
	    	    <element name="price" type="double"/>
	    	    <element name="quantity" type="integer"/>
	        </sequence>
	     </complexType>
	     <complexType name="footerType"> 
	    	<sequence>
	    	    <element name="comment" type="string"/>
	    	</sequence>
	     </complexType>
</schema>

Contents of InvToPo.xsl

<?xml version="1.0" encoding="windows-1252"?>
<?oracle-xsl-mapper
  <!-- SPECIFICATION OF MAP SOURCES AND TARGETS, DO NOT MODIFY. -->
  <mapSources>
    <source type="XSD">
      <schema location="invoice-nxsd.xsd"/>
      <rootElement name="invoice" namespace="http://xmlns.oracle.com/pcbpel/demoSchema/invoice-nxsd"/>
    </source>
  </mapSources>
  <mapTargets>
    <target type="XSD">
      <schema location="po.xsd"/>
      <rootElement name="po" namespace="http://xmlns.oracle.com/pcbpel/demoSchema/po"/>
    </target>
  </mapTargets>
  <!-- GENERATED BY ORACLE XSL MAPPER 1.0 AT [TUE NOV 16 15:32:26 IST 2004]. -->
?>
<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/invoice-nxsd"
                xmlns:na0="http://www.w3.org/2001/XMLSchema"
                xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
                xmlns:pons="http://xmlns.oracle.com/pcbpel/demoSchema/po"
                exclude-result-prefixes="xsl tns na0 nxsd pons">
  <xsl:template match="/">
    <pons:po>
      <pons:header>
        <pons:supplier>
          <pons:name>
            <xsl:value-of select="/tns:invoice/tns:seller/tns:name"/>
          </pons:name>
          <pons:uid>
            <xsl:value-of select="/tns:invoice/tns:seller/tns:uid"/>
          </pons:uid>
          <pons:address>
            <pons:street>
              <xsl:value-of select="concat(/tns:invoice/tns:seller/tns:address/tns:street1,/tns:invoice/tns:seller/tns:address/tns:street2)"/>
            </pons:street>
            <pons:city>
              <xsl:value-of select="/tns:invoice/tns:seller/tns:address/tns:city"/>
            </pons:city>
            <pons:zip>
              <xsl:value-of select="/tns:invoice/tns:seller/tns:address/tns:postal-code"/>
            </pons:zip>
            <pons:state>
              <xsl:value-of select="/tns:invoice/tns:seller/tns:address/tns:state"/>
            </pons:state>
          </pons:address>
        </pons:supplier>
        <pons:buyer>
          <pons:name>
            <xsl:value-of select="/tns:invoice/tns:purchaser/tns:name"/>
          </pons:name>
          <pons:uid>
            <xsl:value-of select="/tns:invoice/tns:purchaser/tns:uid"/>
          </pons:uid>
          <pons:address>
            <pons:street>
              <xsl:value-of select="concat(/tns:invoice/tns:seller/tns:address/tns:street1,/tns:invoice/tns:seller/tns:address/tns:street2)"/>
            </pons:street>
            <pons:city>
              <xsl:value-of select="/tns:invoice/tns:purchaser/tns:address/tns:city"/>
            </pons:city>
            <pons:zip>
              <xsl:value-of select="/tns:invoice/tns:purchaser/tns:address/tns:postal-code"/>
            </pons:zip>
            <pons:state>
              <xsl:value-of select="/tns:invoice/tns:purchaser/tns:address/tns:state"/>
            </pons:state>
          </pons:address>
        </pons:buyer>
      </pons:header>
      <pons:body>
        <xsl:for-each select="/tns:invoice/tns:line-item">
          <pons:item>
            <pons:uid>
              <xsl:value-of select="tns:uid"/>
            </pons:uid>
            <pons:name>
              <xsl:value-of select="tns:description"/>
            </pons:name>
            <pons:price>
              <xsl:value-of select="tns:price"/>
            </pons:price>
            <pons:quantity>
              <xsl:value-of select="tns:quantity"/>
            </pons:quantity>
          </pons:item>
        </xsl:for-each>
      </pons:body>
      <pons:footer>
        <pons:comment>
          The po total is
          <xsl:value-of select="/tns:invoice/tns:total"/>
        </pons:comment>
      </pons:footer>
    </pons:po>
  </xsl:template>
</xsl:stylesheet>

Contents of invoice.txt

6335722^Company One^First Street   999       San Jose       95129USCA650-801-6250
       ^Oracle^Bridge Parkway 1600      Redwood Shores 94065USCA650-506-7000
001|BPEL Process Manager Enterprise Edition|20000,2,+40000+
002|BPEL Process Manager Standard Edition|10000,5,+50000+
003|BPEL Process Manager Developer Edition|1000,20,+20000+#110000
5.5.8.2 Designing the SOA Composite

You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following steps:

  1. In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.
  2. Enter SOA-ComplexStructure in the Application Name field, and click Next. The Create Generic Application - Name your project page is displayed.
  3. Enter ComplexStructure in the Project Name field.
  4. In the Available list under the Project Technologies tab, double-click SOA to move it to the Selected list.
  5. Click Next. The Configure SOA settings dialog appears.
  6. Select Composite With BPEL in the Composite Template box, and click Finish. The Create BPEL Process - BPEL Process page is displayed.
  7. Enter BPEComplexStructure in the Name field, select Define Service Later from the Template box.
  8. Click OK. The SOA-ComplexStructure application and the ComplexStructure project appear in the design area, as shown in Figure 5-150.

    Figure 5-150 The JDeveloper - Composite.xml

    Description of Figure 5-150 follows
    Description of "Figure 5-150 The JDeveloper - Composite.xml"
  9. Copy the invoice-nxsd.xsd and po.xsd files that you created (see Prerequisites) to the schema directory in your project.
  10. Copy InvToPo.xsl that you created (see Prerequisites) to the xsl directory of your project.
5.5.8.3 Creating the Inbound Oracle File Adapter Service

Perform the following steps to create an inbound Oracle File Adapter service to read the file from a local directory:

  1. Drag and drop File Adapter from the Components window to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter Complex Structure In in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select Read File, and click Next. The File Directories page is displayed.
  7. Enter the physical path for the input directory and click Next. The File Filtering page is displayed.
  8. Enter *.txt in the Include Files With Name Pattern field, click Next. The File Polling page is displayed.
  9. Click Next. The Messages page is displayed.
  10. Click Browse For Schema File that appears at the end of the URL field. The Type Chooser dialog is displayed.
  11. Click Project Schema Files, invoice-nxsd.xsd, and invoice.
  12. Click OK. The URL field in the Messages page is populated with the invoice-nxsd.xsd file.
  13. Click Next.
  14. Click next in JCA Endpoint Properties screen.
    The JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  15. Click Finish. The inbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-151 The JDeveloper - Composite.xml

    Description of Figure 5-151 follows
    Description of "Figure 5-151 The JDeveloper - Composite.xml"
5.5.8.4 Creating the Outbound Oracle File Adapter Service

Perform the following steps to create an outbound Oracle File Adapter service to write the file from a local directory to the FTP server:

  1. Drag and drop the Oracle File Adapter from the Components window to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
  2. Enter ComplexStructureOut in the Service Name field.
  3. Click Next. The Adapter Interface page is displayed.
  4. Select Define from operation and schema (specified later), and click Next.
  5. Enter FTP Server JNDI Name in the FTP Server Connection screen, and click Next.
  6. Select Write File, and click Next. The File Configuration page is displayed.
  7. Enter the physical path for the output directory and enter invoice_%SEQ%.txt in the File Naming Convention(po_%SEQ%.txt) field.
  8. Click Next. The Messages page is displayed.
  9. Click Browse For Schema File that appears at the end of the URL field. The Type Chooser dialog is displayed.
  10. Click Project Schema Files, po.xsd, and po.
  11. Click OK. The URL field in the Messages page is populated with the po.xsd file.
  12. Click Next.
  13. Click next in JCA Endpoint Properties screen.
    JCA Endpoint Properties screen appears if you have selected Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  14. Click Finish. The outbound Oracle File Adapter is now configured and composite.xml appears.

    Figure 5-152 The JDeveloper - Composite.xml

    Description of Figure 5-152 follows
    Description of "Figure 5-152 The JDeveloper - Composite.xml"
5.5.8.5 Wiring Services and Activities

You have to assemble or wire the three components that you have created: Inbound adapter service, BPEL process, Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the ComplexStructureIn service in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
  2. Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the ComplexStructureOut reference in the External References area.

    The JDeveloper composite.xml appears, as shown in Figure 5-153.

    Figure 5-153 The JDeveloper - Composite.xml

    Description of Figure 5-153 follows
    Description of "Figure 5-153 The JDeveloper - Composite.xml"
  3. Click File, Save All.
5.5.8.5.1 Add a Receive Activity
  1. Double-click BPELComplexStructure. The BPELComplexStructure.bpel page is displayed.
  2. Drag and drop a Receive activity from the Components window to the design area.
  3. Double-click the Receive activity. The Receive dialog is displayed.
  4. Enter ReceiveInvoice in the Name field.
  5. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  6. Select ComplexStructureIn, and click OK.
  7. Click the Auto-Create Variable icon to the right of the Variable field in the Receive dialog. The Create Variable dialog is displayed.
  8. Select the default variable name and click OK. The Variable field is populated with the default variable name.
  9. Check Create Instance, and click OK. The JDeveloper BPELComplexStructure.bpel page appears.
5.5.8.5.2 Add an Invoke Activity
  1. Drag and drop an Invoke activity from the Components window to the design area.
  2. Double-click the Invoke activity. The Invoke dialog is displayed.
  3. Enter InvokeWrite in the Name field.
  4. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  5. Select ComplexStructureOut, and click OK.
  6. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog. The Create Variable dialog is displayed.
  7. Enter InvokeWrite_Write_OutputVariable in the variable name field and click OK. The Invoke dialog is displayed.
  8. Click OK. The JDeveloper BPELComplexStructure.bpel page appears.
5.5.8.5.3 Add a Transform Activity
  1. Drag and drop a Transform activity from the Components window in between the Receive and Invoke activities in the design area.
  2. Double-click the Transform activity. The Transform dialog is displayed.
  3. Enter TransformPayload in the Name field.
  4. Click the Transformation tab. The Transform dialog is displayed.
  5. Select the Create... icon. The Source Variable dialog is displayed.
  6. Select ReceiveInvoice_Read_InputVariable in the Source Variable box, and select body in the Source Part box, and then click OK. The Transform dialog is displayed with the Source and Part selected.
  7. Select InvokeWrite_Write_OutputVariable in the Target Variable list, select body in the Target Part.
  8. Click the Browse Mapping icon at the end of the Mapper File field and select InvToPo.xsl file from the xsl directory in your project.
  9. Click OK.
  10. Click File, Save All. The BPELComplexStructure.bpel page is displayed, as shown in Figure 5-154.

    Figure 5-154 The JDeveloper - BPELComplexStructure.bpel

    Description of Figure 5-154 follows
    Description of "Figure 5-154 The JDeveloper - BPELComplexStructure.bpel"
5.5.8.6 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
5.5.8.7 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.
  2. Copy the invoice.txt file that you created (see Prerequisites) to the input directory and ensure it gets processed. Check the output directory to ensure that an output file has been created.
  3. Click the SOA composite that you deployed. The Dashboard is displayed.

    Note your Instance ID in the Recent Instances area.

  4. Click the Instances tab. The Instance IDs of the SOA composite are listed.
  5. Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.
  6. Click your BPEL process instance. The Audit Trail of the BPEL process instance is displayed.
  7. Expand a payload node to view payload details.
  8. Click the Flow tab to view the process flow. Click an activity to view the details of the activity.
  9. Click ReceiveInvoice to display the activity details

5.5.9 Oracle FTP Adapter Debatching

This is an Oracle FTP Adapter feature that debatches a large XML document into smaller individual XML fragments. This use case demonstrates how the debatching business process sample uses the Oracle FTP Adapter to process a file containing a batch of business records such as one or more invoice and purchase orders. The PurchaseOrders (POs) are then debatched and written to separate output files.

This section includes the following topics:

5.5.9.1 Prerequisites

To perform the complex structure business process, you must first create the following files:

  • container.xsd

  • po.xsd

  • InvToPo.xsl

  • PoToPo.xsl

  • container.txt

Contents of container.xsd

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://xmlns.oracle.com/pcbpel/demoSchema/container"
        xmlns:tns="http://xmlns.oracle.com/pcbpel/demoSchema/container"
        attributeFormDefault="qualified" elementFormDefault="qualified"
        xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd" nxsd:version="NXSD"
        nxsd:stream="chars">
        
  <element name="container" >
    <complexType>
      <choice maxOccurs="unbounded" nxsd:choiceCondition="fixedLength" nxsd:length="2">
        <element ref="tns:po" nxsd:conditionValue="PO"/>
        <element ref="tns:invoice" nxsd:conditionValue="IN"/>
      </choice>
    </complexType>
  </element>
  
  <element name="po" type="tns:poType"/>
  <element name="invoice" type="tns:invoiceType"/>
  
  &l