test

Developing OTDs for Communication Adapters

Using the Batch Adapter OTDs

Overview of the Batch OTDs

An OTD contains a set of rules that define an object. The object encodes data as it travels through OTDs which are used as the basis for creating Collaboration Definitions for a Project.

Each OTD acts as a template with a unique set of features of the adapter. The Batch Adapter OTD template is not customizable and cannot be edited.

The four parts of an OTD are:

A high-level view of the OTD folder structure shows methods and attributes you can use in creating Business Rules that invoke FTP, secure FTP, batch record, or local file data exchange.

Types of Batch Adapter OTDs

The figure shows the specialized OTDs available with the adapter.

Table 1–1 Batch Adapter OTDs

OTD Name

Description

BatchFTP 

Provides FTP access to remote systems. 

BatchFTPOverSSL 

Provides secure data transfer using FTP over SSL. 

BatchSCP 

Provides secure data transfer using Secure Copy Protocol with Secure Shell (SSH) as an underlying protocol. 

BatchSFTP 

Provides secure data transfer using SSH File Transfer Protocol or SFTP protocol. 

BatchLocalFile 

Provides easy access to local file systems. 

BatchRecord 

Allows the adapter to parse or create (or both) payloads of records in specified formats. 

BatchInbound 

Polls for input file, renames the file to a GUID, and triggers the Business Process or Collaboration. 

This chapter describes each of these OTDs and how to use them with the adapter.

OTD Functions

OTDs provide the following functions:

All OTDs must be configured and administered using NetBeans IDE. Any client components relevant to these OTDs have their own requirements. See the client system’s documentation for details.

For the BatchFTP, BatchLocalFile, and BatchRecord OTDs, only those nodes for which there is a corresponding section in the Environment or Connectivity Map properties (From the Properties Editor) are implemented on the OTD. The remaining nodes are not implemented and are reserved for potential future use.

For the BatchFTP, BatchLocalFile, and BatchRecord OTDs, only those configuration parameters which appear in the Environment or Connectivity Map properties (From the Properties Editor) are supported for use on the OTD. The remaining configuration parameters are not implemented, and are reserved for potential future use. Even though an implemented configuration parameter might be accessed and used from a non-implemented node, such use is not recommended.

BatchFTP OTD

The Batch Adapter includes four OTDs that allow you to perform FTP data-transfer functions. The BatchFTP OTD enables the Sun Enterprise Service Bus 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.

BatchFTP OTD Structure

The BatchFTP OTD contains three top-level nodes, Client, Configuration, Provider, State, and StateManager. Expand these nodes to reveal additional sub-nodes.

Figure 1–6 BatchFTP OTD Structure

BatchFTP OTD Structure

Configuration Node

Each field sub-node in the Configuration node of the OTD corresponds to one of the adapter’s FTP configuration parameters.

Client and Provider Nodes

This OTD includes two additional top-level nodes, the Client and Provider. These nodes implement their respective functionality interfaces in the adapter.

BatchFTP OTD Node Functions

The following list provides an explanation of various nodes in the BatchFTP OTD, including primary functions:

Using the BatchFTP 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.

Handling Type Conversions

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

Code Conversion and Generation

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.

Type Conversion Troubleshooting

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

Essential BatchFTP OTD Methods

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:

Sequence Numbering

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

Additional FTP File Transfer Commands

The BatchFTP OTD also allows you to enter commands to be executed directly before and after the file transfer operation. See the Pre/Post File Transfer Commands section for details.

BatchFTPOverSSL OTD

The Batch Secure FTP over SSL OTD (BatchFTPOverSSL) provides secure data transfer using Secure Sockets Layer (SSL) protocol.

For information about configuring external FTP servers, SSL servers, and so forth, refer to the application’s documentation.

BatchFTPOverSSL OTD Structure

The BatchFTPOverSSL OTD contains two top-level nodes, Client and Configuration. Expand these nodes to reveal additional sub-nodes.

Figure 1–7 BatchFTPOverSSL OTD Structure

BatchFTPOverSSL OTD Structure

BatchFTPOverSSL OTD Node Functions

The following list provides an explanation of various nodes in the BatchFTPOverSSL OTD, including primary functions:

BatchFTPOverSSL: Represents the OTD’s root node.

Configuration Node

The BatchFTPOverSSL sub-nodes under the Configuration node correspond to BatchFTPOverSSL adapter’s Connectivity Map and Environment configuration parameters.

BatchFTPOverSSL Client Node

The Client node contains sub-nodes that implement the adapter’s client interface in the OTDs. The BatchFTPOverSSL Client node includes the following methods:

BatchSFTP OTD

The Batch Secure SFTP OTD (BatchSFTP) provides secure data transfer using SSH File Transfer Protocol or SFTP. SFTP provides a range of operations on remote files, such as resuming interrupted transfers, directory listings, and remote file removal.

SFTP is one means of securely transferring computer files between a local and a remote host or between two remote hosts, using the Secure Shell (SSH) protocol. The BatchSFTP OTD uses SFTP to copy a file to or from a remote host.

BatchSFTP OTD Structure

The BatchSFTP OTD contains two top-level nodes, Client and Configuration (see the following figure). Expand these nodes to reveal additional sub-nodes.

Figure 1–8 BatchSFTP OTD Structure

BatchSFTP OTD Structure

BatchSFTP OTD Node Functions

The following list provides an explanation of various nodes in the BatchSFTP OTD, including primary functions:

BatchSFTP: Represents the OTD’s root node.

Configuration Node

The BatchSFTP sub-nodes under the Configuration node correspond to the BatchSFTP adapter’s Connectivity Map and Environment configuration parameters.

BatchSFTP Client Node

The BatchSFTP OTD’s Client node includes the following methods:

BatchSCP OTD

The Batch Secure SCP OTD (BatchSCP) provides secure data transfer using Secure Copy Protocol with Secure Shell (SSH) as an underlying protocol. SCP is similar to RCP (remote copy), but the file is copied over secure shell (SSH) rather than RSH (remote shell). When files are copied using SCP the data is encrypted during transfer.

For information about configuring external FTP servers, SSH servers, and so forth, refer to the application’s documentation.

BatchSCP OTD Structure

The BatchSCP OTD contains two top-level nodes, Client and Configuration (see the following figure). Expand these nodes to reveal additional sub-nodes.

Figure 1–9 BatchSCP OTD Structure

BatchSCP OTD Structure

BatchSCP OTD Node Functions

The following list provides an explanation of various nodes in the BatchSCP OTD, including primary functions:

BatchSCP: Represents the OTD’s root node.

Configuration Node

The BatchSCP sub-nodes under the Configuration node correspond to BatchSCP adapter’s Connectivity Map and Environment configuration parameters.

BatchSCP Client Node

The BatchSCP OTD’s Client node includes the following methods:

BatchLocalFile OTD

The BatchLocalFile OTD provides access to files on your local system. While file access is not always necessary in the Sun Enterprise Service Bus, it makes sense for the Batch Adapter to have this feature because file processing is one of its core functions.

Additional BatchLocalFile features include regular expressions for accessing files and a sequence-numbering scheme for creating files.

BatchLocalFile OTD Structure

The BatchLocalFile OTD contains four top-level nodes, Client, Configuration, PersistentState, and State Manager. Expand these nodes to reveal additional sub-nodes.

Figure 1–10 BatchLocalFile OTD Structure

BatchLocalFile OTD Structure

Configuration Node

As it iw with each of the Batch OTDs, each field sub-node under the Configuration node in the BatchLocalFile OTD corresponds to one of the adapter’s configuration parameters for that OTD. See the BatchLocalFile Connectivity Map Properties for details.

Client Node

This OTD includes an additional top-level node, the Client. This node implements its respective functionality interface in the adapter.

The client interface represents how the functionality of the OTD is actually used. This functionality includes the basic operations and features of the OTD. The client interface provides the OTD’s the file services those who want to use them.

BatchLocalFile OTD Node Functions

The following list explains the nodes in the BatchLocalFile OTD, including primary functions:

Using the BatchLocalFile OTD

This section explains how to use the BatchLocalFile OTD’s features.

There is no required particular order for the calls that can be made on the BatchLocalFile OTD. The only required call is reset() after a transfer, if it is used for more than one transfer per Collaboration Rule execution. An example of this would be a dynamic batch order with multiple files to be transferred.

If you are using a Java Collaboration to generate multiple files with sequence numbers, using the BatchLocalFile interface, you must call the reset() method to indicate the end of one file and the start of the next one.

BatchLocalFile Specific Features

Using the BatchLocalFile OTD to read records from a local file has the following advantages:

Pre/Post File Transfer Commands

The adapter has features that allow you to execute desired actions directly before or after the actual file transfer. You can enter these settings at the adapter configuration parameters or in the Configuration node of the desired OTD.

These features are available with both the BatchLocalFile OTD and the BatchFTP OTD.

Pre Commands

For an inbound transfer, the file can be made unavailable to other clients polling the target system with the same directory and file pattern or name (Rename). For an outbound transfer, you can perform an automatic backup of the existing file (Copy).

Your pre-transfer options are:

To gain proper protection, backup, or recovery, you must choose the appropriate setting that serves your purpose. For example, to recover from failures on an outbound appending transfer, use the Copy setting. When specifying file and directory names you can use regular expressions, special characters, or both.

Post Commands

For an inbound transfer, you can mark the transferred file as “consumed” by making an automatic backup (Rename) or by destroying it permanently (Delete). For an outbound transfer, you can make the transferred file available to other clients by renaming it. When specifying file and directory names you can use regular expressions, special characters, or both.

Your post-transfer options are:

For more information on Pre and Post Transfer commands see the following:

BatchFTP OTD

BatchLocalFile OTD

Essential BatchLocalFile OTD Methods

In addition to the field elements, the BatchLocalFile 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. These methods include:

Resume Reading Feature

The purpose of this feature is to allow an application to read large files in parts instead of processing the whole file at once. Resume Reading allows your system to read files in a number of subsequent Business Rule executions, when you are using data streaming.

General Operation

The Resume Reading feature’s operation is achieved by keeping persistent information about the current successful file read operation, breaking, then resuming the next read operation from that last stored break position. As a result, the current file is read in parts, and the beginning and end of each part is determined by a predefined break condition.

You determine the break condition through the definition of your Business Rules. Since the Resume Reading feature operates based on reading one part of a file at a time per Business Rule, these rules must determine the break. Each Business Rule executes reading a part of the file, breaks, then passes to the next rule, which reads the next part up to the break, and so on, until the entire file is read.

A break condition can be any type of stopping point you determine in your Collaboration Rules. For example, this condition could be a fixed number of records, a delimiter, or reaching a specific character string.

The Client node in the OTD has a read-only property (ResumeReadingInProgress node) indicating whether there is a resume-reading operation in progress. This node is for informational purposes only. Also, the Resume Reading feature is available in the data-streaming mode only.

The feature has no special operational requirements besides setting the adapter configuration option. The adapter configuration has an option to enable or disable this feature. This option is also accessible at run time.

Note –

If this feature is enabled, the adapter always checks first for a resume-reading operation in progress. If this feature is not in progress, the adapter determines the next file based on the adapter configuration settings.

Step-by-step Operation

The figure shows how the Resume Reading feature operates along with pre- and post-file-transfer commands. In this example, the Collaboration executes the same Business Rule four times. Each execution causes the Collaboration to read another section of the file. When the Collaboration reads the final records, it executes the Post-Transfer commands

Figure 1–11 Resume Reading Operation

Resume Reading Operation

In this example, the reading happens in the following steps:

  1. The adapter starts reading the file then reaches a break condition after a partial data read (the end of Part 1), the adapter’s pre-transfer commands have already been executed. The resume-reading state is stored, and no post-transfer commands are executed. The adapter is waiting for the next execution of the Business Rule.

  2. The resume-reading operation is in progress but still attains only partial data reads. The adapter reads from one break condition to the next (Part 2 and Part 3 in the figure) The resume-reading state is stored in each case, and the adapter executes the Business Rule once per each part.

  3. The resume-reading operation is in progress and completes its data read during the final execution of the Business Rule (Part 4). The adapter reads from a break condition to the end of a file. No resume-reading state is stored, and any post-transfer commands are then executed.

In all of the previous steps, the Business Rule is executed repeatedly, and the current read position in the file changes on each execution. If the file is smaller than Part 1 in the figure, the adapter does not reach a break condition. The operation is normal, and no resume-reading state is stored. The pre- and post-transfer commands are executed.

Operation Without Resume Reading Enabled

If the Resume Reading feature is not enabled:

To Avoid Storing a Resume Reading State

Sometimes a partial data-stream read is necessary even when the Resume Reading feature is enabled. For example, there could be some application logic on top of the record parsers, which might abandon the rest of the file because of a corrupted record and close the file successfully after reading only part of the file’s content.

In this case, you must set the LocalFileOTD.Configuration.ResumeReading node to False before calling finish(). This setting tells the BatchLocalFile OTD to complete the operation without storing a resume-reading state. You can set up the Collaboration Rule to then send notifications or take other measures, as desired.

Data Stream-adapter Provider

You can use the BatchLocalFile OTD to implement the adapter’s data streaming feature. This feature is also available with the FTP and record-processing OTDs. However, the BatchLocalFile OTD is a data stream-adapter provider, while the other two OTDs are only consumers. See Streaming Data Between Components for details on how to use the OTD’s data streaming feature.

Sequence Numbering

Sequence numbering for the BatchLocalFile OTD operates similar to sequence numbering for the BatchFTP OTD. See Sequence Numbering for details.

Generating Multiple Files with Sequence Numbering

When using a Java Collaboration to generate multiple files that have sequence numbering using the BatchLocalFile interface, reset() must be called to signify the end of one file and the start of the next.

Handling Type Conversions

This feature in this OTD operates in the same way as type conversion for the BatchFTP OTD. See Handling Type Conversions for details.

Recommended Practice

To parse records or construct payloads in your Collaboration, we recommend that you use the record-processing BatchRecord OTD together with the BatchLocalFile OTD. Using the two OTD together provides a number of advantages over just using the BatchFTP OTD.

Example 1: Parsing a Large File

For example, you have set up a Collaboration Rule to parse a large file and submit the records to a database or a JMS IQ Manager. If something goes wrong during the parsing process, the whole file needs to be transmitted again from the FTP server.

In contrast, streaming from a local file system can avoid later FTP transfers of the same file in case of error. This approach has the advantage of allowing you to use data streaming and the Resume Reading feature with large files (see Streaming Data Between Components and Resume Reading Feature.

Example 2: Slow and Complex Query

Another scenario could be a case where a slow, complex SQL query is used to retrieve a number of records. The Collaboration Rule packs them into a Payload node using the record-processing OTD then sends them through FTP to an external system. If the FTP transfer fails, the SQL query must be executed again.

In contrast, if the data payload has been stored locally with the BatchLocalFile OTD, the FTP transfer can be repeated without the need to re-execute the SQL query. In such cases, you can also use data streaming and local-file appending.

In both cases, the use of a data-streaming link can significantly reduce the memory requirements compared to the in-memory data-payload transfer used with the BatchFTP OTD.

OTD Limitations

The BatchLocalFile OTD supports mapped drives and NFS mounted drives. It does not, however, support the mapping of the drives. That is, the drive must already be mapped or mounted. The adapter itself does not perform any mapping or mounting.

The OTD supports Universal Reference Identifiers (URIs) but the scheme must be left off, for example,\\drive\directory\file_name.

BatchRecord OTD

BatchRecord, the Batch Adapter’s record-processing OTD, allows you to parse (extract) records from an incoming payload (payload data) or to create an outgoing payload consisting of records. Understanding the operation of this OTD and how to use it requires an explanation of some of these terms.

The word payload here refers to an in-memory buffer, that is, a sequence of bytes or a stream. Also, records in this context are not records in the database sense. Instead, a record simply means a sequence of bytes with a known and simple structure, for example, fixed-length or delimited records.

For example, each of the following record types can be parsed or created by this OTD:

The record-processing OTD can handle records in the following formats:

When using character delimiters with DBCS data, use single byte character(s) or equivalent hex values with hex values that do not coincide with either byte of the double byte character.

BatchRecord OTD Structure

The BatchRecord OTD contains two top-level nodes, Client, Configuration, PersistentState, and StateManager (see the following figure). Expand these nodes to reveal additional sub-nodes.

Figure 1–12 BatchRecord OTD Structure

BatchRecord OTD Structure

OTD Structure and Operation

Each field node under the Configuration node of the OTD, corresponds to one of the adapter’s record-processing configuration parameters.

Record-Processing OTD Node Functions

The following list explains these primary nodes in the record-processing OTD, including their functions:

Using the Record-Processing OTD

This OTD has the following basic uses:

A single instance of the OTD is not designed to be used for both purposes at the same time in the same Collaboration. To enforce this restriction, there is a setting under the adapter’s General Settings parameters called Parse or Create Mode, for which you can select either Parse or Create.

Using get() and put()

The get() and put() methods are the heart of the OTD’s functionality. If you call either method, the record retrieved or added is assumed to be of the type specified in the adapter configuration, for example, fixed-length or delimited.

The get() method can throw an exception, but generally this action only happens when there is a severe failure. One such failure is an attempt to call get() before the payload data (or stream if you are streaming) has been set. However, the best practice is to code the Collaboration to check the return value from a get() call. A return of true means a successful get operation; a false means the opposite.

Choosing the Parse or Create Mode

The adapter checks to ensure that the proper calls are made according to your mode setting. For example, calling put() in a parse-mode environment would cause the adapter to throw an exception with an appropriate error message explaining why. Calling get() in the create mode would also result in an error.

The adapter requires these restrictions because:

As a result, you can place the OTD on the source or destination side of a given Collaboration, as desired, and use the OTD for either parsing or creating a payload. However, you cannot parse and create at the same time. Implement your OTD in a Collaboration using the Collaboration Rules Editor.

Creating a Payload

When you want the payload data sent to an external system, you can place the OTD on the outbound side of the Collaboration interfacing with that system. Successive calls to put() build up the payload data in the format defined in the adapter configuration.

Once all the records have been added to the payload, you can drag and drop the payload onto the node or nodes that represent the Collaboration’s outbound destination. Also, you can set an output stream as the payload’s destination (see Table 1–3 for details on payload streaming).

When you are building a data payload, you must take into account the type and format of the data you are sending. The adapter allows you to use the following formats:

Parsing a Payload

To represent payload data inbound from an external system, you map the data to the payload node in the OTD (from the Collaboration Rules Editor). In addition, you can specify an input stream as a source.

Either way, each successive call to get() extracts the next record from the payload. The type of record extracted depends on the parameters you set in the adapter’s configuration, for example, fixed size or delimited.

You must design the parsing Collaboration with instructions on what to do with each record extracted. Normally, the record can be sent to another Collaboration where a custom OTD describes the record format and carries on further processing.

Fully Consuming a Payload

It is possible to fully consume a payload. That is, after a number of successive calls to get(), you can retrieve all the records in the payload. After this point, successive calls to get() return the Boolean false. You must design the business rules in the subject Collaboration to take this possibility into account.

Using Record Processing with Data Streaming

If you are using the record-processing OTD with data streaming, you must be careful not to overwrite the output files. If the OTD is continually streaming to a BatchLocalFile OTD that uses the same output file name, the OTD can write over files on the output side.

To avoid this problem, you must use either file sequence numbering or change the output file names in the Collaboration Rules. Sequence numbering allows the BatchLocalFile OTD to distinguish individual files by adding a sequence number to them. If you use target file names, post-transfer file names, or both, you can change the name of the output file to a different file name.

For more information on how to use these features, see Sequence Numbering and Pre/Post File Transfer Commands.

BatchInbound OTD

The BatchInbound Input (Trigger) File adapter polls for an input file, renames the file with a GUID prefix, and triggers the Business Process or Collaboration.

The Batch adapter’s BatchInbound OTD acts similar to the inbound File adapter, in that it regularly polls an input directory for inbound target files. But unlike the File adapter, when a file with the appropriate name is received by the BatchInbound adapter, the target file is renamed with the following pattern: GUID.original_filename to ensure that the file is not over-written and is only sent once. A GUID (Globally Unique Identifier) provides a unique, formatted string that represents a 128-bit value.

The BatchInbound OTD does not read the file, but renames the file in such a way that it provides the name of the file that triggers the Business Process or Collaboration.

BatchInbound OTD Structure

The BatchInbound OTD contains one top-level node, BatchAppconnMessage, with three fields, PathDirName, OriginalFileName, and GUIDFileName (see the following figure). These nodes provide the external input directory, original file name, and the GUID file name.

Figure 1–13 BatchInbound OTD Structure

BatchInbound OTD Structure

Using Regular Expressions With the Batch Adapter

A regular expression is a character string in which some characters provide special meaning in regard to matching patterns. This section explains some basic guidelines on how to use regular expressions with the HTTPS.

Regular Expressions: Overview

Regular expressions allow you to specify patterns for file names and directory names. Regular expressions are used for “get” operations (receiving or source), as opposed to name patterns which are used for “put” operations (sending or destination).

The BatchFTP, Batch FTPOverSSL, BatchSFTP, BatchLocalFile, and BatchInbound OTDs allow you to use regular expressions, for example, if you want to access all files with a specific extension.

Regular expressions operate as follows:

Entering Regular Expressions

You can enter a regular expression for the FTP or local file name in a variety of ways, for example, .*\.dat$ or ^xyz.*\.dat$. The first case indicates all files with an extension of .dat. The second case indicates all file names with an extension of .dat whose names start with xyz.

Another example could be file[0-9]\.dat. This expression specifies file0.dat, file1.dat, file2.dat, and so on, through file9.dat. This will also match xyz.file0.dat, xyz.file1.dat, and so on. This type of expression will not exclude anything in front of “file”. To exclude any characters before “file” (to make “file” the exact beginning) use ^file[0-9].dat or \Afile[0-9].dat.

These types of regular expression patterns can be used for a get operation.

Regular Expressions and the Adapter

The adapter provides a File Name Is Pattern or Directory Name Is Pattern configuration parameter after every property that allows a regular expression as an option. This feature allows you to specify that the pattern entered is a regular expression or just a static text entry to be interpreted literally.

Note –

Regular expressions will resolve even with a partial match to the file name. The resolution process searches for the file name contents rather than the file name.

Rules for Directory Regular Expressions

There are special considerations you must be aware of when you use regular expressions for directory names. This section describes these restrictions and provides some examples.

Restrictions for Using Regular Expressions as Directory Names

The following restrictions apply when using regular expressions as directory names:

Regular Expression Directory Name Examples

The following are several examples of regular expression directory name usage:

Using Name Patterns With the Batch Adapter

The Batch adapter allows you to use a Name Pattern, that is, special characters that symbolize often-used information as short-hand. You can use these character combinations to specify place holders for this specific information. Using these characters, you can quickly convey date/time, number, and file-name information.

The BatchFTP, Batch FTPOverSSL, BatchSFTP, BatchLocalFile, and BatchInbound OTDs allow you to use special characters or specify a name pattern. A name pattern allows you to specify patterns for file names and directory names. Name patterns are used for “put” operations (sending or destination) , as opposed to regular expressions which are used for “get” operations (receiving or source).

Special characters are utilities the adapters use for file-name pattern. The general rules for their use are:

For example, for a put operation, a pattern such as file%#.dat can be used. This pattern uses the sequence number setting in the configuration, and each put creates successive files named file1.dat, file2.dat, and so on.

For information on regular expressions, see Using Regular Expressions With the Batch Adapter.

Types of Name Patterns

The adapter provides the following types of name patterns:

The sequence of expansion operates in the reverse order of the previous list, that is, first the file name is expanded, then the sequence number, and finally the time stamp.

Some additional examples of name pattern:

Resolving Names

Typically, the pre/post names with name patterns or regular expressions are resolved during get() and put() method calls. But sometimes, in using Collaboration Rules, the adapter has to get the resolved names before the actual get() or put() call.

In such cases, you can get the resolved names in this way through the ResolvedNamesForGet and ResolvedNamesForPut nodes in the BatchFTP OTD, for example:

getResolvedNamesForPut().getTargetFileName()

The previous code yields file1 based on the pattern file%#. In this usage, the OTD nodes can be used to make the desired method call.

Date and Time Format Syntax

The adapter uses the Java simple default date and time format syntax (U.S. locale). To specify these formats for name pattern, you must use a time pattern string.

Note –

The adapter uses the Java standard for date/time stamps from the Java class java.text.SimpleDateFormat. Some of these formats can differ from the list given here, depending on the Java SDK version you are using.

In these patterns, all ASCII letters are reserved as pattern letters. See Table 1–2 for a complete list.

Table 1–2 Time Pattern Strings and Meanings

Symbol 

Meaning 

Presentation 

Example 

%G 

Era designator 

Text 

AD 

%y 

Year 

Number 

1996 

%M 

Month in year 

Text and number 

July & 07 

%d 

Day in month 

Number 

10 

%h 

Hour in a.m./p.m. (1 through 12) 

Number 

12 

%H 

Hour in day (0 through 23) 

Number 

0 

%m 

Minute in hour 

Number 

30 

%s 

Second in minute 

Number 

55 

%S 

Millisecond 

Number 

978 

%E 

Day in week 

Text 

Tuesday 

%D 

Day in year 

Number 

189 

%F 

Day of week in month 

Number 

2 (second Wednesday in July) 

%w 

Week in year 

Number 

27 

%W 

Week in month 

Number 

2 

%a 

Marker for a.m./p.m. 

Text 

PM 

%k 

Hour in day (1 through 24) 

Number 

24 

%K 

Hour in a.m./p.m. (0 through 1) 

Number 

0 

%z 

Time zone 

Text 

Pacific Standard Time 

The general rules for date/time formats are:

Table 1–3 U.S. Locale Date and Time Patterns

Format Pattern 

Result 

yyyy.MM.dd, G, ’at’ hh:mm:ss, z 

1996.07.10 AD at 15:08:56 PDT 

E, M, dd, ’’yy 

Wednesday, July 10, ’96 

h:mm, a 

12:08 PM 

h, ’o’’clock’ a, z 

12 o’clock PM., Pacific Daylight Time 

K:mm a, z 

0:00 p.m., PST 

yyyyy.M.dd, G, hh:mm, a 

1996.July.10 AD 12:08 PM