Input Options

Input configuration properties are as follows:

Generate Message When No Response

The Generate Message When No Response configuration property is only used for Out->In mode and determines whether the (S)FTP Client Communication Point returns a response message or not when no files were available for download on the server. This property has no effect if files are available for download.

^{† Default option.}

Input Directory

Input Directory is the directory on the remote server to look for files. Defaults to the home directory.

Refresh Rate

Refresh Rate determines how often to look on the remote server for new files. This property is only applicable to cases where there were no files available on the remote server the last time Rhapsody checked. When files are available, Rhapsody fetches them all with no delay. The default is 60000 milliseconds.

Input Pattern Type

Input Pattern Type is used to filter which files are retrieved from the remote server.

^{† Default option.}

Input Pattern

Input Pattern defines the pattern used to filter input files. The default is *.

If Input Pattern Type is set to Filename with wildcards, the pattern is interpreted as a wildcard. The default * fetches all files, but by using * to match multiple characters or ? to match single characters, you can create a filter to fetch files with specific names. For example, a pattern of *.txt gets all files that have the suffix .txt, and ignores files with other suffixes. Wildcard pattern matching used by the (S)FTP Client communication point is case-sensitive, unlike the deprecated SFTP Client communication point. To emulate the same case-insensitive behavior of the deprecated SFTP Client communication point, set the Before Receive Commands property to CASE.

If Input Pattern Type is set to Regular expression, the pattern is interpreted as a regular expression, and only fetches files whose names match the regular expression. Rhapsody displays a configuration error if it is unable to understand your regular expression.

Input Order

Input Order defines the order in which files in a directory are read from the server.

^{† Default option.}

Comparison Script

Comparison Script refers to custom JavaScript used to order files returned from the server. If the standard input order options in the configuration property Input Order are not sufficient for your purposes, you can write a custom comparator using JavaScript. To enable the comparison script, set the Input Order property to Custom JavaScript. The JavaScript comparator can then be configured in the Comparison Script configuration property.

You are given access to two objects, left and right, which represent the two files to be compared. Your JavaScript code should compare those two files with a statement or series of statements that should evaluate to:

• A negative number if you want the left file to be processed first.
• A positive number if you want the right file to be processed first.
• Zero if the files are equivalent.

Compilation errors in the script prevent the communication point being successfully configured, and any runtime errors are treated as a connection error within the communication point.

Rules for Implementing Comparators

A comparison function must provide an absolute ordering of files, not a relative ordering of files. Specifically the rules are:

• Identity - compare(a, a) = 0.
• Reflective - compare(a, b) = −compare(b, a).
• Transitive - if compare(a, b) > 0 and compare(b, c) > 0, then compare(a, c) > 0.

Refer to java.util.Comparator for details on the comparator rules this communication point effectively uses.

JavaScript Variables

The following JavaScript variables are placed into the scope of the custom JavaScript comparator.

File Object

The left and right JavaScript variables are File objects. The methods and properties the File object takes are listed in the following table:

Connection Errors

Connection errors are raised by throwing an exception within the script. Normally this is done by throwing a string describing the problem, for example:

throw 'Failed to parse line \"' + line + '\".';

There is no need to raise an error if a line should not correspond to a file – simply do not call the contents.add() method and no file object will be created for it.

Example Script

In the following example, the script orders files by size such that the smallest file is processed first; if files are of the same size, it orders them by name:

var leftLength = left.size(), rightLength = right.size(), result = 0;
 
if (leftLength < rightLength) {
    result = -1;
}
 
if (rightLength < leftLength) {
    result = 1;
}
 
if (result == 0) {
    result = left.name().compareTo(right.name());
}
 
result;

Directory Traversal Mode

Directory Traversal Mode determines whether to fetch files from the specified input directory only or the sub-directories as well.

^{† Default option.}

Follow Symbolic Links

Follow Symbolic Links determines what should be done when symbolic links are encountered in an input directory when in Input and Out->In mode.

^{† Default option.}

Input Pattern applies when selecting file symbolic links, so that file symbolic links that do not match the input pattern are ignored. Directory symbolic links are followed regardless of whether or not they match the input pattern (as is the behavior of regular directories), but the input pattern is applied to files that are found inside that directory.

When the file that a file symbolic link links to has been downloaded into Rhapsody, the usual Post Download Action is taken. The action is taken on the symbolic link file itself, not to the file it links to. So for example, if the default delete Post Download Action is selected, the symbolic link is deleted after the file that it linked to has been downloaded.

For directory symbolic links, the Post Download Action is applied to the actual files in that directory after they have been downloaded, and the directory symbolic link remains (as is the behavior of regular directories).

If you are using symbolic links and getting errors (specifically where the stack trace has an error message similar to No such file or directory) when you believe that the files or directories do indeed exist, it is likely that the FTP server you are connecting to is denying you permission to access the files or permission to use symbolic links.

Avoiding Infinite Loops

In order to avoid infinite loops that could occur when following symbolic links, when the Follow Symbolic Links property is set to Follow directory symbolic links or Follow all symbolic links, Rhapsody takes the following precautions when navigating directories to look for input files:

• There is a hard limit to the number of consecutive symbolic links to other directories that can be followed. This limit is 10. Generally, on any file system, it is only likely that you would follow that many consecutive symbolic links if you had hit a loop situation, where some directories all contained symbolic links to each other.
• Once you have followed one symbolic link to a directory, Rhapsody also starts to count the depth of the path, whether it be regular folders or symbolic links to directories. This has a hard limit of 40. This is to avoid a situation where for example a folder had a symbolic link back up to a parent folder, which would cause a loop.
• If the Follow Symbolic Links property is not set to Follow directory symbolic links or Follow all symbolic links, then a maximum path depth is not enforced, as there is not much likelihood of infinite loops occurring when symbolic links are not being used.
• Care should be taken on Windows machines when using symbolic links (such as those created with the mklink command), as these may not be reported to Rhapsody as symbolic links. Looping could therefore occur; however, Windows seems to limit itself in these cases with its own hard limit on maximum path lengths.

Post Download Action

Post Download Action is the action to perform on the remote file after it has been downloaded onto Rhapsody.

^{† Default option.}

Rename To

Rename To determines what to rename the file after it has been downloaded onto Rhapsody.

Only available when either the Rename file option is selected for Post Download Action, or if the communication point is in dynamic mode.

After a successful download, the file on the FTP server is renamed to the configured name. If the target name evaluates to a path (which can be relative or absolute), in other words a move operation, then the communication point attempts to create any directories referenced. An error is thrown if the creation does not succeed. 

The following variables can be used to dynamically generate a target filename:

For example, a configured Rename To value of ../done/%baseFilename%-%datetime%.%suffix% moves the downloaded files into a sibling directory called done (which would be created if necessary), and renames them to insert the current date and time between the base filename and suffix. If the full path to the downloaded file is /home/ftp/available/someTextFile.txt, then the file is moved to /home/ftp/done/someTextFile-2013-09-17-06-55-43-831.txt, for example.

If the target filename is already in use on the FTP server, the (S)FTP Client communication point attempts to automatically rename the file by appending a number in parentheses to make the filename unique. For example, someTextFile.txt becomes someTextFile(1).txt or someTextFile(2).txt, etc., until a unique filename is found.

In static mode or when using XML configuration templates, a configuration error is raised if the Rename file option is selected but no Rename To value is provided, or if the Rename To value is configured specifically as %filename%. If either of these errors occurs while using message properties the outgoing message is instead sent directly to the error queue.

The default is %filename%.done.

Maximum File Size for Download (MB)

Maximum File Size for Download (MB) specifies the maximum size of a file in megabytes that can be downloaded. This limit is not enforced if the property is set to zero or if the (S)FTP server does not provide the file size. This property can be configured statically, dynamically via message properties or configuration templates.