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