4 Oracle JCA Adapter for Files/FTP

This chapter describes how to use the Oracle File and FTP Adapters, which work with Oracle BPEL Process Manager and Oracle Mediator. Information on concepts, features, configuration and use cases for the Oracle File and FTP Adapters is also provided.

The term Oracle JCA Adapter for Files/FTP is used for the Oracle File and FTP Adapters, which are separate adapters with very similar functionality.

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

4.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 File Adapter for FTP Adapter from the Component Palette of JDeveloper BPEL Designer, the Adapter Configuration Wizard starts with a Welcome page, as shown in Figure 4-1.

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 4-1 lists the available operations and provides references to sections that describe the configuration information you must provide.

4.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 4-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 Chapter 1, "Introduction to Oracle JCA Adapters."

4.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 Section 3.2.4, "Oracle SOA Composite Integration with Adapters."

4.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. This section explains the following features of the Oracle File and FTP Adapters:

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.

4.2.1File Formats

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

XML (both XSD- and DTD-based)

Delimited

Fixed positional

Binary data

COBOL Copybook data

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

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

4.2.3Inbound 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:

Poll the file system looking for matches.

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

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, and the component that provides this function is the file reader. This operation is known as a Java Connector Architecture (JCA) inbound activation.

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

Receive messages from BPEL or Mediator.

Format the XML contents as specified at design time.

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.

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

4.2.4File Debatching

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 must not manually change the value of the publish size parameter in JCA files. You must use the Adapter Configuration Wizard to modify this parameter.

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

4.2.5File ChunkedRead

This is a feature of Oracle File and FTP Adapters that uses an invoke activity within a while loop to process the target file. This feature enables you to process arbitrarily large files.

If an invalid payload is provided, then ChunkedRead scenarios do not throw an exception. When a translation exception (bad record violating the NXSD specification) is encountered, the return header is populated with the translation exception message that includes details such as line and column where the error occurred. All translation errors do not result in a fault. These errors are manifested as a value in the return header. You must check the jca.file.IsMessageRejected and jca.file.RejectionReason header values to ascertain whether an exception has occurred. Additionally, you can also check the jca.file.NoDataFound header value.

4.2.6 File Sorting

When files must be processed by Oracle File and FTP Adapters in a particular order, you must configure the sorting parameters. 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.

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

4.2.7Dynamic 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 Section 4.3.2.2, "Outbound File Directory Creation."

4.2.9Nontransactional

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, during this process if a failover occurs in the Oracle RAC back end or in an SOA managed server, 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.

4.2.10Proxy 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 4-3 shows how a proxy server creates connections to simulate a direct connection between the client and the remote FTP server.

4.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."

4.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 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 Section 4.5.6, "Oracle File Adapter Read File As Attachments."

Note:

You must not pass large payloads as opaque schemas.

4.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 Section 4.3.1.4, "File Polling."

4.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:

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

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>
*/
publicinterface 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;
}

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.

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

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

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

Step 3 Creating a Pipeline

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

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 4-6 shows a sample pipeline.xml file (unzippipeline.xml) added to the InboundUnzipAndOutboundZip project.

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"/>

For example, in the JCA file shown in Figure 4-6, 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 reentrancy, 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:

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

Note:

If you configure a pipeline using the "PipelineValves" 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.

4.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:

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.

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

If there are errors during the publish operation, then 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.

4.2.14.4Configuring 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 following is the BatchNotificationHandler interface:

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 as follows:

4.2.15 Error Handling

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 following schema file provides an example of using the uniqueMessageSeparator property:

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

4.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:

4.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 4-7 shows a default threading model.

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

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.

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.

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

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

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

Publishes the XML result from the translator to the SCA infrastructure.

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

4.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 Oracle File and FTP Adapters. The following sections describe the modified threading behavior of the Oracle File and FTP Adapters:

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:

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 as follows:

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

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

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

The maximum value for the ThreadCount property is 40.

4.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 knobs that you can use to tune the performance of outbound operations.

4.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. It supports this feature for both inbound and outbound operations.

4.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 opposed to 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 4-8.

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 following example:

4.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 4-9 displays the Append to Existing File option.

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 the FTP server supports the "APPE" command.

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. In the 11g release, 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:

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 and WINDOWS, which are specific to the Microsoft Windows NT FTP server.

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.

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:

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, then the server does not show the hour and minute part and it shows the following:

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:

4.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 run time, 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 configure credential mappings, you can specify the user names and passwords in the weblogic-ra.xml file for the corresponding adapter or perform the following procedure by accessing the Oracle WebLogic Server Administration Console:

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 4-10.

Click Next. The Create a New Security Credential Mapping – EIS User Name and Password page is displayed.

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 4-17.

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

4.3.1.2 Inbound File Directory Specifications

The File Directories page of the Adapter Configuration Wizard shown in Figure 4-20 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.

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

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

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.

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

4.3.1.3 File Matching and Batch Processing

The File Filtering page of the Adapter Configuration Wizard shown in Figure 4-21 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.

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

Notes:

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

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

Be aware of any file length restrictions imposed by your operating system. For example, Windows operating system file names cannot be more than 256 characters in length (the 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(|).

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

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

4.3.1.3.4 Debatching Multiple Inbound Messages

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

4.3.1.4 File Polling

The File Polling page of the Adapter Configuration Wizard shown in Figure 4-22 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.

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

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.

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 4-21.

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

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

Table 4-4 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 Oracle Enterprise Manager.

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.

4.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 4-22. Files can also be moved to a completion (archive) directory if specified in the File Directories page shown in Figure 4-20.

4.3.1.6 Native Data Translation

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

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 Section 6.1.1, "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.

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

The ActivationSpec property values are specified in the Adapter Configuration Wizard during design time and, as shown in Table 4-5. 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.

4.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 4-24:

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

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

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

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 dir name, example, C:\outputDir in the Value field. The composite.xml file appears as follows:

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.

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 4-20 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.

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

In the preceding example, in the JCA file, the physical directory is set to "C:\foo" but during run time 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:

Click OK in the Create Copy Operation dialog and then click OK in the Assign dialog. The .bpel page is displayed.

Double-click the invoke activity. The Invoke dialog is displayed.

Click the Properties tab.

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 4-29.

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.

4.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 4-26 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.

Additionally, you can combine file naming conventions. For example, you can specify the file naming convention as po_%SEQ%_%yyyy.MM.dd%_%SEQ%.txt.

Note:

When you use the time stamp pattern, the same time stamp may be generated on subsequent calls and you may lose messages. The workaround is to combine the time-stamp pattern with a sequence pattern. Alternatively, you can use a time-stamp pattern closest to a millisecond, in which case the adapter handles the uniqueness of the file names.

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.

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 needed to separate two adjacent fields.

Year

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

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

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

Month

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

General time zone

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

GMTOffsetTimeZone:

GMT Sign Hours : Minutes

Sign: one of

+ -

Hours:

Digit

Digit Digit

Minutes:

Digit Digit

Digit: one of

0 1 2 3 4 5 6 7 8 9

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

For parsing, RFC 822 time zones are also accepted.

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

RFC822TimeZone:

Sign TwoDigitHours Minutes

TwoDigitHours:

Digit Digit

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

For parsing, general time zones are also accepted.

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

In the preceding example, in the JCA file, the physical directory is set to "C:\foo" but during run time 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:

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.

4.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 4-26:

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 some problem during batching, then it starts batching at the point at which it left off on recovery.

4.3.2.3 Native Data Translation

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

4.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, "Application Profile Deployment". You can rerun the wizard later to change your operation definitions.

A sample outbound JCA file includes the information listed in Table 4-7:

Table 4-7 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 Appendix A of this book.

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

4.3.3 Oracle File Adapter Synchronous Read Concepts

In the outbound direction, the Oracle File Adapter polls and reads the current contents of files. 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 4-32.

All 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 4-33.

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

4.3.4.1 Listing Operation

4.3.4.2 File Directory Specifications

The File Directories page of the Adapter Configuration Wizard shown in Figure 4-35 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.

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 logical directory once at design time, and you can later modify the directory name as needed.

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

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

Notes:

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

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

Be aware of any file length restrictions imposed by your operating system. For example, Windows operating system file names cannot be more than 256 characters in length (the 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(|).

4.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 (*).

4.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 4-37.

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 4-8 lists the pages that are displayed and provides references to sections that describe their functionality.

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

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.

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 below 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 mdtmfilename 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 mdtmfilename command.

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:

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.

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:

4.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 4-37.

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

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 4-9 lists the pages that display and provide references to sections that describe their functionality.

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

4.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 4-41.

4.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 Section 4.3.4, "Oracle File Adapter 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.

4.4 Configuring Oracle File and FTP Adapters

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

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

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 Section 2.21, "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:

For Windows platforms, you must ensure that the input and output directories are canonicalized. 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.

4.4.2.2High 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.

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.

Create Database Tables

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

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.

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

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

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

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.

Create Database Tables

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

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.

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

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

4.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. For Windows, this feature is certified on FileZilla FTP server with OpenSSL. This section provides an overview of secure FTP functionality and describes how to install and configure this feature.

4.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 4-45, the server's certificate is directly imported into the client's certificate store (or Oracle Wallet) as a trusted certificate.

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.

4.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:

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

Go to the following URL:

http://www.openssl.org/source

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)

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

Unzip the following file using gunzip.

gunzip openssl-0.9.7g.tar.gz

Untar the following file:

tar xvf openssl-0.9.7g.tar

Change directories to the following location:

cd openssl-0.9.7g

Run the following command:

./config --prefix=/usr --openssldir=/usr/local/openssl

Change to the Bourne shell (if you are not using it):

sh

Configure and export the PATH variable:

PATH=${PATH}:/usr/ccs/bin; export PATH

Run the following command:

make

Exit the Bourne shell:

exit

Run the following command:

make test

Log in as the super user:

msu

Enter the password when prompted.

Run the following command:

make install

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

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.

4.4.3.2.3 Creating an Oracle Wallet

s

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

4.4.3.3.1Installing 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.

4.4.3.3.2 Generating OpenSSL Server Key and Certificate

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

Open the command prompt and browse to the OpenSSL\bin directory.

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

4.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, you must perform the following steps:

4.4.4 Using SFTP with 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.

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

4.4.4.1.1 Encryption

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

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.

The data is encrypted using the session key.

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

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

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

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

Open the cygwin window.

Type ssh-host-config.

You are prompted with the following questions:

Shall privilege separation be used? (yes/no)

Enter yes.

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

Enter yes.

Do you want to install sshd as service?

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

Enter yes.

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.

Type net start sshd to start the sshd service.

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

To test the setup, type ssh localhost in the cygwin window.

4.4.4.3Set Up Oracle FTP Adapter for SFTP

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

Table 4-11 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 4-11 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.

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

proxyUser

proxyPassword

useProxy

Mandatory: Yes

4.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 4-11. Ensure that the authenticationType property is set to password.

For public key authentication, you must first configure OpenSSH and then set up the Oracle FTP Adapter. The Oracle FTP Adapter setup depends on whether the OpenSSH is running inside a firewall or outside a firewall. If OpenSSH is running inside the firewall, then see the following sections:

To set up the Oracle FTP Adapter for public key authentication, you must specify the values of the parameters listed in Table 4-11 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 4-13.

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

In the deployment descriptor for Oracle FTP Adapter, you must specify the values of the properties listed in Table 4-11 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.

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 4-14.

Table 4-14 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

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

4.4.5.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 4-15 lists the properties that you must modify.

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

Table 4-16 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

4.4.5.1.1 Proxy Definition File

You can specify all proxy-specific information in a proxy definition file and configure the adapter to use this file with the proxyDefinitionFile 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 4-5. Your proxy definition file must be based on this XML schema.

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

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.

Select WriteEmployee_Write_InputVariable in the Target Variable list, select employee in the Target Part, as shown in Figure 4-74.

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

Click the Flow tab to view the process flow. Additionally, click an activity (such as invoke, receive) to view the details of an activity.

Click ReceiveCSV to display the activity details.

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

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

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

Click Next. The Messages page is displayed.

Click the Browse For Schema File button at the end of the URL field. The Type Chooser dialog is displayed.

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

Click OK.

Click Next in the Messages page. The Finish page is displayed.

Click Finish. A WriteFTP adapter service is created.

4.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:

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.

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 4-84.

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.

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

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

Click OK.

From the File menu, click Save.

4.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:

4.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:

In the Application Navigator of JDeveloper, click New Application. The Create Generic Application - Name your application page is displayed.

Enter SOA-ScalableDOM in the Application Name field, and click Next. The Create Generic Application - Name your project page is displayed.

Enter ScalableDOM in the Project Name field.

In the Available list under the Project Technologies tab, double-click SOA to move it to the Selected list.

Click Next. The Configure SOA settings dialog appears.

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.

Enter BPELScalableDOM in the Name field, select Define Service Later from the Template box.

Click OK. The SOA-ScalableDOM application and the ScalableDOM project appears in the design area.

4.5.5.5 Wiring Services and Activities

You have to 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:

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.

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.

4.5.5.7 Monitoring Using Fusion Middleware Control Console

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

Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.

Copy the address-csv.txt file to the input directory (see Section 4.5.5.1, "Prerequisites" for the location of this file) and ensure it gets processed. Check the output directory to ensure that an output file has been created.

Click the SOA composite that you deployed. The Dashboard is displayed.

Note your Instance ID in the Recent Instances area.

Click the Instances tab. The Instance IDs of the SOA composite are listed.

Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.

Click the Flow tab to view the process flow. Additionally, click an activity to view the details of an activity.

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

4.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:

Drag and drop File Adapter from the Component Palette to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

Click Next. The Service Name page is displayed.

Enter AttachmentIn in the Service Name field.

Click Next. The Adapter Interface page is displayed.

Select Define from operation and schema (specified later), and click Next. The Operation page is displayed.

Select Read File as the Operation Type and select Read File As Attachment, as shown in Figure 4-116, and then click Next. The File Directories page is displayed.

Note:

You must 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.

4.5.6.7 Monitoring Using Fusion Middleware Control Console

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

Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.

Copy the attachment.doc file to the input directory (see Section 4.5.6.1, "Prerequisites" for details) and ensure it gets processed. Check the output directory to ensure that an output file has been created.

Click the SOA composite that you deployed. The Dashboard is displayed.

Note your Instance ID in the Recent Instances area.

Click the Instances tab. The Instance IDs of the SOA composite are listed.

Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.

Click the Flow tab to view the process flow. Additionally, click an activity to view the details of an activity.

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

Click the Flow tab to view the process flow. Additionally, click an activity to view the details of an activity.

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

4.5.8.7 Monitoring Using Fusion Middleware Control Console

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

Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.

Copy the invoice.txt file to the input directory (see Section 4.5.8.1, "Prerequisites" for the location of this file) and ensure it gets processed. Check the output directory to ensure that an output file has been created.

Click the SOA composite that you deployed. The Dashboard is displayed.

Note your Instance ID in the Recent Instances area.

Click the Instances tab. The Instance IDs of the SOA composite are listed.

Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.

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

Click the Xpath Expression Builder icon in the pop-up window. The Expression Builder dialog is displayed.

Enter starts-with(local-name(ora:getNodes('receive_Get_InputVariable','body','/ns3:container/child::*[position()=1]')),'invoice') as the expression, as shown in Figure 4-152, and click OK. The screen returns to the Condition Expression pop-up window.

4.5.9.7 Monitoring Using Fusion Middleware Control Console

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

Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.

Copy the container.txt file to the input directory (see Section 4.5.9.1, "Prerequisites" for the location of this file) and ensure it gets processed. Check the output directory to ensure that an output file has been created.

Click the SOA composite that you deployed. The Dashboard is displayed.

Note your Instance ID in the Recent Instances area.

Click the Instances tab. The Instance IDs of the SOA composite are listed.

Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.

Click the Flow tab to view the process flow. Additionally, click an activity (such as invoke, receive) to view the details of an activity.

4.5.10 Oracle FTP Adapter Dynamic Synchronous Read

This use case demonstrates the ability of the Oracle FTP Adapter to perform a mid-process synchronous read operation using an Invoke activity. This use case illustrates the following adapter functionality:

Oracle File Adapter (Read Operation)

Oracle FTP Adapter (Synchronous Read operation)

Ability to specify the file name to be read during run-time

Oracle File Adapter (Write Operation)

The process is initiated by the presence of a trigger file appearing in a local directory monitored by the inbound Oracle File Adapter. The trigger file contains the name of the file to be read by the synchronous read operation. This file name is passed through headers to the adapter. This can be done using the Properties tab for the Invoke activity. This synchronous read file operation is performed against a remote directory on a FTP server. The result of the read is then transformed and written out to a local directory through the outbound Oracle File Adapter. This section includes the following topics:

4.5.10.5 Wiring Services and Activities

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

Drag the small triangle in the ReadTrigger in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.

Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the SyncRead in the External References area and to the drop zone that appears as a green triangle in WriteFile.

Drag and drop a Transform activity from the Component Palette in between the Invoke_SyncRead and InvokeWrite activities in the design area.

Double-click the Transform activity. The Transform dialog is displayed.

Enter TransformPayload in the Name field.

Click the Transformation tab. The Transform dialog is displayed.

Click the Create... icon. The Source Variable dialog is displayed.

Select InvokeSyncRead_SyncRead_OutputVariable 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.

Select InvokeWrite_Write_InputVariable in the Target Variable list, select body in the Target Part.

Click the Browse Mappings icon at the end of the Mapper File field and select addr1Toaddr2.xsl file from the xsl directory in your project.

4.5.10.7 Monitoring Using Fusion Middleware Control Console

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

Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.

Copy the address-csv.txt file to the input directory (see Section 4.5.10.1, "Prerequisites" for the location of this file) and ensure it gets processed. Check the output directory to ensure that an output file has been created.

Click the SOA composite that you deployed. The Dashboard is displayed.

Note your Instance ID in the Recent Instances area.

Click the Instances tab. The Instance IDs of the SOA composite are listed.

Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.

4.5.11 Copying, Moving, and Deleting Files

The Oracle File and FTP Adapters let you copy or move a file from one location to another, or delete a file from the target directory. Additionally, the Oracle FTP Adapter lets you move or copy files from a local file system to a remote file system and from a remote file system to a local file system. This feature is implemented as a interaction specification for outbound services. So, this feature can be accessed either by using a BPEL invoke activity or a Mediator routing rule.

At a high level, you must create an outbound service and configure this service with the source and target directories and file names.

The following use cases demonstrate the new functionality supported by Oracle File and FTP Adapters that allow you to copy, move, and delete files by using an outbound service:

4.5.11.1 Moving a File from a Local Directory on the File System to Another Local Directory

You can model only a part of this procedure by using the wizard because the corresponding Adapter Configuration Wizard is not available. You must complete the remaining procedure by manually configuring the generated JCA file.

You must perform the following steps to move a file from a local directory on the file system to another local directory:

Create an empty BPEL process.

Drag and drop File Adapter from the Component Palette to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

Click Next. The Service Name page is displayed.

Enter a service name in the Service Name field.

Click Next. The Adapter Interface page is displayed.

Select Define from operation and schema (specified later), and click Next. The Operation page is displayed.

Select Synchronous Read File, enter FileMove in the Operation Name field, and then click Next. The File Directories page is displayed.

Note:

You have selected Synchronous Read File as the operation because the WSDL file that is generated because this operation is similar to the one required for the file I/O operation.

Enter a dummy physical path for the directory for incoming files, and then click Next. The File name page is displayed.

Note:

The dummy directory is not used. You must manually change the directory in a later step.

Enter a dummy file name, and then click Next. The Messages page is displayed.

Note:

The dummy file name you enter is not used. You must manually change the file name in a later step.

Select Native format translation is not required (Schema is opaque), and then click Next. The Finish page is displayed.

Click Finish. The outbound Oracle File Adapter is now configured.

Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in FileMove in the External References area. The BPEL component is connected to the Oracle File Adapter outbound service.

Create an invoke activity for the FileMove service that you just created by selecting the default settings.

The next step is to modify the generated WSDL file for MoveFileService service and configure it with the new interaction specification for the move operation.

Open the FileMove_file.jca file and modify the endpoint interaction, as shown in the following example.

You must configure the JCA file with the source and target directory and file details. You can either hardcode the source and target directory and file details in the JCA file or use header variables to populate them. In this example, header variables are used.

You have modified the className attribute, and added SourcePhysicalDirectory, SourceFileName,TargetPhysicalDirectory, TargetFileName and Type. Currently, the values for the source and target details are dummy. You must populate them at run-time. You can also hardcode them to specific directories or file names.

The Type attributes decides the type of operation. Apart from MOVE, the other acceptable values for the Type attribute are COPY and DELETE.

Map the actual directory and file names to the source and target file parameters by performing the following procedure:

Create 4 string variables with appropriate names. You must populate these variables with the source and target directory details. The BPEL source view shows you this:

Create an assign activity to assign values to sourceDirectory, sourceFileName, targetDirectory, and targetFileName variables. The assign operation appears in the BPEL source view as in the following example:

4.5.11.4 Using a Large CSV Source File

Consider the following scenario, where you have a large CSV file of size 1 gigabyte coming on the source directory, and you must perform the following:

Translate the CSV into XML.

Transform the resulting XML using XSL.

Translate the result from the transform operation into a fixed length file.

This use case is similar to the FlatStructure sample in the BPEL samples directory. The difference is that the three steps occur in a single File I/O interaction.

Note:

All the three steps occur in a single File I/O interaction. This works only if all the records in the data file are of the same type.

To use a large CSV file and perform the operations listed in the preceding scenario, you must perform the following steps:

Copy the address-csv.xsd and address-fixedLength.xsd files from the FlatStructure sample into the xsd directory of your project.

Copy addr1Toaddr2.xsl from the FlatStructure sample into the xsl directory of your project.

Configure the File I/O interaction, as shown in the following example. At a high level, you must specify the source schema, the target schema, and the XSL in the interaction specification along with the source and target directory or file details, as shown in the following example:

4.5.11.5 Moving a File from One Remote Directory to Another Remote Directory on the Same FTP Server

The I/O use cases for the Oracle FTP Adapter are very similar to those for Oracle File Adapter. However, there are a few nuances that need attention.

In this use case you move a file within the same directory, which is similar to a rename operation on the same server. Most FTP servers support the RNFR/RNTO FTP commands that let you rename a file on the FTP server.

However, even if the RNFR/RNTO commands are not supported, moving a file within the same directory is still possible because of a binding property, UseNativeRenameOperation. By default, this property is set to TRUE, and in this case the Oracle FTP Adapter uses the native RNFR/RNTO commands. However, if this property is set to FALSE, then the Oracle FTP Adapter uses the Get and Put commands followed by a Delete command to emulate a move operation.

You can model only a part of this procedure by using the wizard because the corresponding Adapter Configuration Wizard is not available. You must complete the remaining procedure by manually configuring the generated JCA file.

You must perform the following steps to move a file from a remote directory to another remote directory on the same FTP server:

Create an empty BPEL process.

Drag and drop FTP Adapter from the Component Palette to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

Click Next. The Service Name page is displayed.

Enter a service name in the Service Name field.

Click Next. The Adapter Interface page is displayed.

Click Next. The FTP Server Connection page is displayed.

Enter the JNDI name for the FTP server, and click Next. The Operation page is displayed.

Select Synchronous Get File, enter FTPMove in the Operation Name field, and then click Next. The File Directories page is displayed.

Note:

You have selected Synchronous Get File as the operation because the WSDL file that is generated because this operation is similar to the one required for the file I/O operation.

Enter a dummy physical path for the directory for incoming files, and then click Next. The File name page is displayed.

Note:

The dummy directory is not used. You must manually change the directory in a later step.

Enter a dummy file name, and then click Next. The File Name page is displayed.

Note:

The dummy file name you enter is not used. You must manually change the file name in a later step.

Click Next. The Messages page is displayed.

Select Native format translation is not required (Schema is opaque), and then click Next. The Finish page is displayed.

Click Finish. The outbound Oracle File Adapter is now configured.

Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in FTPMove in the External References area. The BPEL component is connected to the Oracle FTP Adapter outbound service.

Click File, Save All.

Create an invoke activity for the FTPMove service that you just created.

The next step is to modify the generated WSDL file for FTPMove service and configure it with the new interaction specification for the move operation.

Open the FTPMove_ftp.jca file and modify the interaction-spec, as shown in the following example.

You must configure the JCA file with the source and target directory and file details. You can either hardcode the source and target directory and file details in the JCA file or use header variables to populate them. In this example, header variables are used.

You have modified the className attribute, and added SourcePhysicalDirectory, SourceFileName, TargetPhysicalDirectory, TargetFileName, and Type. Currently, the values for the source and target details are dummy. You must populate them at run-time. You can also hardcode them to specific directories or file names.

The Type attributes decides the type of operation. Apart from MOVE, the other acceptable values for the Type attribute are COPY and DELETE.

Map the actual directory and file names to the source and target file parameters by performing the following procedure:

Create 4 string variables with appropriate names. You must populate these variables with the source and target directory details. The BPEL source view shows you this:

Create an assign activity to assign values to sourceDirectory, sourceFileName, targetDirectory, and targetFileName variables. The assign operation appears in the BPEL source view as in the following example:

In this example, you have configured SourceIsRemote as false. In this case, the FTP input and output operation assumes that the source file comes from a local file system. Also, notice that you did not specify the parameter for target because TargetIsRemote is set to true by default.

4.5.11.7 Moving a File from a Remote Directory on the FTP Server to a Local Directory on the File System

In this example, you have configured TargetIsRemote as false. In this case, the FTP I/O assumes that the source file comes from a remote file system whereas the target is on a local file system. Also, notice that you did not specify the parameter for source because SourceIsRemote is set to true by default.

4.5.11.8 Moving a File from One FTP Server to another FTP Server

To move a file from one FTP server to another FTP server you must sequentially perform the use cases documented in the following sections:

4.5.12 Creating a Synchronous BPEL Composite using File Adapter

By default, the JDeveloper Adapter Wizard generates asynchronous WSDLs when you use technology adapters. Typically, you follow these steps when creating an adapter scenario in 11g:

Create a SOA Application with either Composite with BPEL or an Empty Composite selected. If you choose Empty Composite, you must drop the BPEL Process from the Service Components pane onto the SOA Composite Editor.

You arrive at the screen below where you fill in the process details. You are required to choose Define Service Later as the template.

This is how most BPEL processes that use Adapters are modeled. The generated WSDL implies one-way directionally one way and that makes the BPEL process asynchronous:

Figure 4-167 Generated One-Way WSDL

In other words, the inbound File Adapter polls for files in the directory and for each file that it finds there, it translates the content into XML and publishes to BPEL.

However, because the BPEL process is asynchronous, the File Adapter returns immediately after the publish and performs the required post processing-for example. deletion/archival of data.

The disadvantage with such asynchronous BPEL processes is that it becomes difficult to throttle the inbound adapter. In otherwords, the inbound adapter would keep sending messages to BPEL without waiting for the downstream business processes to complete. This can lead to issues such as higher memory usage and CPU usage.

To mitigate the occurrence of these problems, you can manually change the WSDL and BPEL artifacts into synchronous processes. Once you have changed the synchronous to synchronous BPEL processes, the inbound File Adapter automatically throttles itself because the File Adapter is forced to wait for the downstream process to complete with a <reply> before processing the next file or message.

Refer to the altered WSDL below. Here, you convert the one-way WSDL to a two-way WSDL-- thereby making the WSDL synchronous.

This type of exercise is not required for the Mediator because the Mediator routing rules are sequential by default. In other words, the Mediator uses the caller thread (inbound file adapter thread) for processing routing rules. This is the case even if the WSDL for mediator is one-way..

Where there is a requirement to send the same file to five different FTP servers, you could create, for example, five FtpAdapter references, one for each connection-factory location. However, this is not the most optimal approach; instead, you can use the concept of "Dynamic Partner Links".

If you're running the adapter in managed mode, it requires you to configure the connection factory JNDI in the WebLogic Server console for the FtpAdapter.

In the sample below, the connection-factory JNDI location "eis/Ftp/FtpAdapter" has been mapped with the Ftp server running on localhost.

After you've configured the connection factory on your application server, you must refer to the connection-factory JNDI in the jca artifact of your SCA process. In the example below, the FTPOut reference in the following .jca file uses the FTP server corresponding to eis/Ftp/FtpAdapter

You can change this connection-factory location dynamically using JCA header properties in both BPEL and Mediator service engines. To do so, the business scenario involving BPEL or Mediator is required to use a reserved JCA header property jca.jndi as shown in the following.

You must preconfigure the connection factories on the SOA server. In the BPEL example above, both eis/Ftp/FtpAdater1 and eis/Ftp/FtpAdater2 must be configured in the WebLogic Server deployment descriptor for the FtpAdapter before your deployment of the scenario.

Dynamic Partner Links are applicable to outbound invocations only

4.5.12.2 Retrieving the Details of the File from an Outbound Write Operation

You can capture the details of the file that was written out as a part of a BPEL process that is invoking a File/FTP Adapter

For example, using FileNamingConvention as PurchaseOrder_%SEQ%.txt, you might be required to perform post processing based on the file that was written out (the name of the file is not known until the adapter invocation completes for example, PurchaseOrder_1.txt,PurchaseOrder_2.txt ...)

To provide for the capture of metadata, you must edit the WSDL so the File/Ftp Adapter can return the metadata of the file being written. In general, the File/Ftp Write/Put WSDL operations are one way as shown below.

In general, the File/FTP Write/Put WSDL operations, as inserted in the .jca file, are one way of enabling the return of the metadata, as shown below.

The File/TP Adapters are designed to return the metadata back if the WSDL is tweaked into a two-way WSDL. In addition, the </wsdl.output> must import the fileread.xsd schema. You must copy the fileread.xsd schema from the following location:

4.5.13 Changing the Sequencing Strategy for FILE/Ftp Adapter

The File/Ftp Adapter enables you to configure outbound writes to use a sequence number. For example, if you choose address-data_%SEQ%.txt as the FileNamingConvention, all files would be generated as address-data_1.txt, address-data_2.txt,..

The sequence number comes from the control directory for the particular adapter project(or scenario). For each project that use the File or Ftp Adapter, a unique directory is created for book-keeping purposes. Because this control directory must be unique, the adapter uses a digest to ensure that no two control directories are the same.

For example, for the FlatStructure sample in the example above, the control information for my project would go under FMW_HOME/user_projects/domains/soainfra/fileftp/controlFiles/[DIGEST]/outbound where the value of DIGEST would differ from one project to another.

Within this directory, there is a file control_ob.properties file where the sequence number is maintained. The sequence number is maintained in binary form and you might need a hexadecimal editor to view its content. There is another zero byte file, SEQ_nnn. This extra file is maintained as a backup.

One of the challenges faced by the adapter run time is to guard all writes to the control files so no two threads inadverently attempt to update the control files at the same time. It does this guarding with the help of a "Mutex". The mutex is of different types:

In-memory

DB-based

Coherence-based

User-defined

There might be scenarios, particularly when the Adapter is under heavy tranactional load, where the mutex is a bottleneck. The Adapter, however, enables you to change the configuration so the adapter sequence value is derived from a database sequence or a stored procedure. In such a situation, the mutex is by-passed, and the process results in improved throughput.

The simplest way to achieve improved throughput is by switching your JNDI connection factory location for the outbound JCA file to use the eis/HAFileAdapter:

Figure 4-176 Switching the JNDI Connection Factory to Use the HAFileAdapter

With this change, the Adapter run time creates a sequence on the Oracle database. For example, if you do a select * from user_sequences in your soa-infra schema, you see a new sequence being created with name as SEQ_<GUID>__ (where the GUID differs by project).

However, to use your own sequence, you must add a new property to your JCA file called SequenceName. You must create this sequence on your soainfra schema beforehand.

Using DB2 or MSSQL Server as the dehydration support is a bit different. DB2 supports sequences natively but MSSQL Server does not. The Adapter run time uses a natively generated sequence for DB2, but, for MSSQL server, the Adapter relies on a stored procedure that ships with the product.To achieve the same result for a SOA Suite running DB2 as the dehydration store, change the connection factory JNDI name in the JCA file to eis/HAFileAdapterDB2. For MSSQL, use eis/HAFileAdapterMSSQL. To use a stored procedure other than the one that ships with the product, you must rely on binding properties to override the adapter behavior; specifically, you must instruct the adapter to use a stored procedure:

When the File/Ftp Adapter is used in Append mode, the adapter run time degrades the mutex to use pessimistic locks to prevent writers from different nodes appending to the same file at the same time.

4.5.14Creating a Synchronous BPEL Composite using the File Adapter

By default, the JDeveloper Adapter wizard generates asynchronous WSDLs when you use technology adapters. Typically, you follow the following steps when creating an adapter scenario in Release 11g:

Create a SOA Application with either Composite with BPEL or an EmptyComposite. If you choose Empty Composite, you must drop the BPEL Process from the Service Components panel onto the SOA Composite Editor. Either way, you arrive at the process details screen You must choose Define Service Later as the template. Description of the illustration bpel_create.gif

Next, you create the inbound service and outbound reference and wire them with the BPEL component:

The inbound File Adapter polls for files in the directory and for each file it finds there, the Adapter translates the content into XML and publishes to BPEL. But, because the BPEL process is asynchronous, the Adapter returns immediately after the publish operation and performs the required post processing, for example, deletion/archival.

The disadvantage with such asynchronous BPEL processes is that it becomes difficult to throttle the inbound adapter. In other words, the inbound adapter keeps sending messages to BPEL without waiting for the downstream business processes to complete. This can lead to several issues including higher memory usage, and CPU usage.

To alleviate these problems, manually tweak the WSDL and BPEL artifacts into synchronous processes. Oncet here are synchronous BPEL processes, the inbound adapter automatically throttles itself as the adapter is forced to wait for the downstream process to complete with a <reply> before processing the next file or message.

In the following WSDL, the one-way WSDL has been converted to a two-way WSDL, thereby making the WSDL synchronous:

4.5.15 Controlling the Order in which Files Are Processed

The File/FTP Adapter enables you to control the order in which files get processed. For example, you might want the files to be processed in sequience of their modified times/ file sizes , or other determiners.

The File/FTP adapter enables you to achieve controlling the order in which files gets processed through a FileSorter attribute that you can define in the JCA file for your inbound File/Ftp Adapter service.

The File/FTP Adapter provides two predefined sorters that use the last modified times--or example:

However, there are times when you would like to define the order yourself. You can implement a Java Comparator and register that with the File Adapter as described below:

Write a comparator. For example, the FileSizeSorter comparator below sorts the files in descending order of their sizes:

To compile this class, you must place fileAdapter.jar in the classpath. From [FMW_HOME]/AS11gR1SOA/soa/connectors, expand FileAdapter.rar, for example, jar xvf FileAdapter.rar to extract fileAdapter.jar. You must place fileAdapter.jar in your classpath to compile the FileSizeSorter.java class, for example:

setenv CLASSPATH fileAdapter.jar
jacac -d .FileSizeSorter.java

After compilation, bundle the class in its own jar file, for example,

jar cvf fileadapter-sorter.jar file

Bundle the fileadapter-sorter.jar in the FileAdapter.rar, for example,

jar uvf FileAdapter.rar fileadapter-sorter.jar

This step is required since the fileadapter-sorter.jar becomes visible to the ClassLoader that loads FileAdapter.rar. Though, there are other ways for example, copying the fileadapter-sorter.jar and fileadapter.jar under [DOMAIN_HOME]/lib, but the one above is the simplest and easiest to do.

Setting SingleThreadModel as true in the JCA file (see image at the beginning of this section.)

If you're using BPEL, ensure you model a synchronous process.

Scripting on this page enhances content navigation, but does not change the content in any way.