Skip Navigation Links | |
Exit Print View | |
Oracle Java CAPS Adapter for Batch User's Guide Java CAPS Documentation |
Oracle Java CAPS Adapter for Batch User's Guide
Additional Licensing Considerations
Batch Adapter System Requirements
Installing Adapter Enterprise Manager plug-ins
Creating and Configuring Batch Adapters
Selecting a Batch External Application
Modifying the Adapter Properties
BatchFTP Adapter Connectivity Map Properties
Pre Transfer (BatchFTP Connectivity Map)
SOCKS (BatchFTP Connectivity Map)
FTP (BatchFTP Connectivity Map)
FTP Raw Commands (BatchFTP Connectivity Map)
Sequence Numbering (BatchFTP Connectivity Map)
Post Transfer (BatchFTP Connectivity Map)
Target Location (BatchFTP Connectivity Map)
SSH Tunneling (BatchFTP Connectivity Map)
Additional SSH-supporting Software
General Settings (BatchFTP Connectivity Map)
BatchFTP Adapter Environment Properties
General Settings (BatchFTP Environment)
SSH Tunneling (BatchFTP Environment)
Connection Pool Settings (BatchFTP Environment)
Connection Retry Settings (BatchFTP Environment)
BatchFTPOverSSL Adapter Connectivity Map Properties
Pre Transfer (BatchFTPOverSSL Connectivity Map)
FTP and SSL Settings (BatchFTPOverSSL Connectivity Map)
Post Transfer (BatchFTPOverSSL Connectivity Map)
Firewall Settings (BatchFTPOverSSL Connectivity Map)
Synchronization (BatchFTPOverSSL Connectivity Map)
BatchFTPOverSSL Adapter Environment Properties
FTP and SSL Settings (BatchFTPOverSSL Environment)
Firewall Settings (BatchFTPOverSSL Environment)
General Settings (BatchFTPOverSSL Environment)
Connection Pool Settings (BatchFTPOverSSL Environment)
Connection Retry Settings (BatchFTPOverSSL Environment)
BatchSCP Adapter Connectivity Map Properties
SCP Settings (BatchSCP Connectivity Map)
Firewall Settings (BatchSCP Connectivity Map)
Synchronization (BatchSCP Connectivity Map)
BatchSCP Adapter Environment Properties
SSH Settings (BatchSCP Environment)
Firewall Settings (BatchSCP Environment)
General Settings (BatchSCP Environment)
Connection Pool Settings (BatchSCP Environment)
Connection Retry Settings (BatchSCP Environment)
BatchSFTP Adapter Connectivity Map Properties
Pre Transfer (BatchSFTP Connectivity Map)
SFTP Settings (BatchSFTP Connectivity Map)
Post Transfer (BatchSFTP Connectivity Map)
Firewall Settings (BatchSFTP Connectivity Map)
Synchronization (BatchSFTP Connectivity Map)
BatchSFTP Adapter Environment Properties
SFTP Settings (BatchSFTP Environment)
Firewall Settings (BatchSFTP Environment)
General Settings (BatchSFTP Environment)
Connection Pool Settings (BatchSFTP Environment)
Connection Retry Settings (BatchSFTP Environment)
BatchLocalFile Connectivity Map Properties
Pre Transfer (BatchLocalFile Connectivity Map)
Sequence Numbering (BatchLocalFile Connectivity Map)
Post Transfer (BatchLocalFile Connectivity Map)
General Settings (BatchLocalFile Connectivity Map)
Target Location (BatchLocalFile Connectivity Map)
BatchLocalFile Environment Properties
General Settings (BatchLocalFile Environment)
Connection Pool Settings (BatchLocalFile Environment)
BatchRecord Connectivity Map Properties
General Settings (BatchRecord Connectivity Map)
Record (BatchRecord Connectivity Map)
BatchRecord Environment Properties
Connection Pool Settings (BatchRecord Environment)
BatchInbound Connectivity Map Properties
Settings (BatchInbound Connectivity Map)
BatchInbound Environment Properties
MDB Settings (BatchInbound Environment)
IBM IP Stack Required for MVS Sequential, MVS GDG, and MVS PD
Creating User Defined Heuristic Directory Listing Styles
Heuristics Configuration File Format
FTP Heuristics Configuration Parameters
Commands Supported by FTP Server
Header Indication Regex Expression
Trailer Indication Regex Expression
Directory Indication Regex Expression
File Link Indication Regex Expression
File Link Symbol Regex Expression
Valid File Line Minimum Position
Special Envelope For Absolute Path Name
Listing Directory Yields Absolute Path Names
Absolute Path Name Delimiter Set
Change Directory Before Listing
Directory Name Requires Terminator
FTP Configuration Requirements for AS400 UNIX (UFS)
Dynamic Configurable Parameters for Secure FTP OTDs
Configuration Parameters that Accept Integer Values
Understanding Batch Adapter OTDs
BatchFTPOverSSL OTD Node Functions
BatchLocalFile OTD Node Functions
BatchLocalFile Specific Features
Pre/Post File Transfer Commands
Essential BatchLocalFile OTD Methods
Operation Without Resume Reading Enabled
To Avoid Storing a Resume Reading State
Generating Multiple Files with Sequence Numbering
Example 1: Parsing a Large File
Example 2: Slow, Complex Query
Record-processing OTD Node Functions
Using the Record-processing OTD
Choosing the Parse or Create Mode
Using Record Processing with Data Streaming
Regular Expressions and the Adapter
Rules for Directory Regular Expressions
Restrictions for Using Regular Expressions as Directory Names
Regular Expression Directory Name Examples
Additional Batch Adapter Features
Streaming Data Between Components
Introduction to Data Streaming
Overcoming Large-file Limitations
Data Streaming Versus Payload Data Transfer
SOCKS Configuration Properties
Additional Software Requirements
The Batch Adapter includes four OTDs that allow you to perform FTP data-transfer functions. The BatchFTP OTD enables the Java CAPS system to exchange data with other network hosts for the purpose of receiving and delivering objects stored in files. In addition, the BatchFTPOverSSL, BatchSCP, and BatchSFTP OTDs enable secure data transfer between the local host and a remote host using FTP over SSL and SSH.
The BatchFTP OTD contains three top-level nodes, Client, Configuration, Provider, State, and StateManager. Expand these nodes to reveal additional sub-nodes.
Figure 3 BatchFTP OTD Structure
Each field sub-node in the Configuration node of the OTD corresponds to one of the adapter’s FTP configuration parameters.
This OTD includes two additional top-level nodes, the Client and Provider. These nodes implement their respective functionality interfaces in the adapter.
The client interface represents how the functionality of the provider is actually used.
The provider interface represents all of the general FTP operations that can be performed by the OTD.
The following list provides an explanation of various nodes in the BatchFTP OTD, including primary functions:
BatchFTP: Represents the OTD’s root node.
Configuration: Each field sub-node within this node corresponds to an adapter configuration parameter and contains settings information.
InputStreamAdapter and OutputStreamAdapter: Allow you to use and control the OTD’s data-streaming features; see Streaming Data Between Components for details.
Note - This OTD has configuration parameters that can be regular expressions. See Using Regular Expressions for details.
Client: This node contains the following sub-nodes, which implement the adapter’s client interface in the OTD (FtpFileClient):
Payload: An in-memory buffer that contains the payload or message data you want to transfer by FTP, in the form of a byte array.
UserProperties: Only used if you have provided a user-defined implementation of the FtpFileClient interface; in such cases, the node represents the properties specified in the configuration.
Note - You can transfer data using the Payload node or by using data streaming (InputStreamAdapter and OutputStreamAdapter nodes), but you cannot use both methods in the same OTD.
ResolvedNamesForGet and ResolvedNamesForPut: Allow you to get the real file or directory name used during a transfer and perform an operation with it. For example, you could do a file transfer, with get() or put(), using the real name. You are able to retrieve the real file or directory name, even if these names have been expressed using regular expressions or special characters.
These nodes contain sub-nodes that allow you to resolve file and directory names for target destinations, as well as names for pre- and post-transfer commands. See Pre/Post File Transfer Commands, Resolving Names for more information on these nodes. Also see Using Regular Expressions for more information on regular expressions.
get(), put(), reset(), connect(), disconnect(), and isConnected(): See Essential BatchFTP OTD Methods.
Provider: The sub-nodes contained in this node are methods that implement the adapter’s provider interface in this OTD (FtpFileProvider). These methods allow you to do the general FTP operations that can be performed using the OTD.
The BatchFTP OTD nodes allow you to configure specific adapter configuration parameters for the Collaboration controlling the FTP process. Once you have set the configuration parameters, you do not have to define the same parameters in each corresponding adapter component that uses this Collaboration.
The Payload node in the BatchFTP OTD is predefined as a byte array (byte[]). This definition allows the adapter to handle both binary and character data.
For example, you could use another OTD (such as an OTD from another adapter or a user-defined OTD) where the “data” node has been defined as a String (java.lang.String). If you were to map that String to the BatchFTP OTD’s Payload node, the Java CAPS Collaboration Editor can do an automatic type conversion and create code similar to that shown in the following example.
Note - You must use care with this feature. While it works in many situations, there can be occasions when the default encoding causes errors in the translation.
For example, in a string-to-byte array conversion (or vice versa), the generated Java code could be:
getoutput().setPayload(STCTypeConverter.toByteArray (getinput().getBlob()));
or
getinput().setBlob(STCTypeConverter.toString (getoutput().getPayload()));
If you define the blob data as a byte array, no type conversion is necessary. When there is a conversion, the Collaboration Editor uses the Java Virtual Machine (JVM) default encoding to do the conversion to code, as shown in the previous examples.
As explained previously, the default encoding and translation works for many situations. There are cases, however (for example, binary data such as a .zip file), when the encoding could cause errors in the translation. Depending on the data character set and JVM default encoding, you must choose the appropriate encoding. In most cases, using the encoding string “ISO-8859-1” is the best choice.
To use this encoding, you can modify the code manually by adding the encoding String. Taking the previous examples, the resulting code using “ISO-8859-1” is:
getoutput().setPayload(STCTypeConverter.toByteArray (getinput().getBlob(), "ISO-8859-1"));
or
getinput().setBlob(STCTypeConverter.toString (getoutput().getPayload(), "ISO-8859-1"));
Using this String solves this type conversion problem. For more information, see the appropriate JVM encoding reference manuals.
In addition to the field elements, the BatchFTP OTD’s Client node contains methods that extend the client interface functionality of the adapter. These methods are essential to the proper use of the OTD and require some additional explanation. They are:
get(): Retrieves a file from the remote FTP server then stores its contents as a data payload. The method retrieves the first matching file based on the Target Directory Name and Target File Name parameters and stores the contents as a data payload (a byte array). It then performs any Post Transfer Command.
Note - After this method call, you can get the payload’s contents via the method getPayload().
If no qualified file is available for retrieving, you get the exception containing java.io.FTPFileException as a nested exception.
put(): Places the payload data on the FTP server, that is, it performs an append or put action from the Payload node to the remote FTP server and performs any Post Transfer Command.
If no qualified file is available for sending, you get the exception containing java.io.FTPFileException as a nested exception.
Note - When you are using the adapter’s data-streaming feature, the get() and put() methods operate differently. See Streaming Data Between Components for details on this operation.
reset(): Allows you to return the Client node to its state immediately after the previous initialization.
Note - The reset() method is available in the Batch FTP OTDs and BatchLocalFile OTD. The reset method must be called when the OTD has to be reused for another transfer during the same execution of executeBusinessRules() (for example, when you are using the Dynamic Configuration feature). The reset() method resets the content of the Client node without resetting the whole OTD. If you attempt another transfer without calling reset() first, the system throws an exception and makes an entry in the adapter’s error log file.
restoreConfigValues(): Allows you to restore the configuration parameter defaults to the related adapter configuration.
connect(), disconnect(), and isConnected(): Perform connection-related operations with respect to the FTP server.
The sequence numbering feature allows you to set up the FTP target directory or file name to contain a sequence number. You can set the starting and maximum sequence numbers using the adapter configuration parameters for the OTD.
This parameter is used for the name pattern %#.
This feature is also available with the BatchLocalFile OTD. For more information on these configuration parameters, see Sequence Numbering (BatchFTP Connectivity Map).
The BatchFTP OTD also allows you to enter commands to be executed directly before and after the file transfer operation. See Pre/Post File Transfer Commands for details.