com.tibco.ax.fw.runtime.transport.sshftp
Interface SSHFTPClient

public interface SSHFTPClient

The SSHFTPClient interface models an SSHFTP client that can connect to an SSH server utilzing its sftp subsystem and perform file manipulation based based on the SSH File Transfer Protocol. The SSHFTPClient exposes the functionality defined in this specification. The SSH File Transfer Protocol specification is available at:

 http://tools.ietf.org/html/draft-ietf-secsh-filexfer-03
 

The SSH Protocol specification is available at:

 http://www.ietf.org/rfc/rfc4250.txt
 

 http://www.ietf.org/rfc/rfc4251.txt
 

 http://www.ietf.org/rfc/rfc4252.txt
 

 http://www.ietf.org/rfc/rfc4253.txt
 

 http://www.ietf.org/rfc/rfc4254.txt
 

The SSHFTPClient operates only in secure mode, which is an inherent property of the ssh transport. It is possible to override the trading partner's server credential and the client's private key credential objects - which had to be specified (created) in the configuration store on the corresponding transport and business agreement - with alternative credentials. See setPeerPublicKey(String peerPublicKeyName), setHostPrivateKey(String hostPrivateKeyName).

Users of this interface will be given an SSHFTPClient object through the Job variable. One can get this object inside EcmaScript or JavaScript as shown below:

 var sshFtpClient = job.get(FTP_OBJ);

 Your logic ... // no need to connect or disconnect as the transport tunnel will be established and managed by the framework

 

This sshFtpClient object is available only during the duration of the script and is not a serializable or persistent object. Once the sshFtpClient object is obtained, users can call any of the methods described in the interface below if they have not configured for file transfer through an http proxy server. All the commands are supported if the connection is configured with a non-http proxy (e.g. socks4 or socks5).

The SSHFTP transport can only be configured with SOCKS4, SOCKS5 proxies or without proxies.

Apart from the ftpObj job variable, there are few variables to get information relating to local directories, filenames, trading partner, and trading host name.

The variables that are available for the SSHFTP transport configured in trading partner outbound transports (FTP outbound) are: To get the directory of the file (in cases where the payload is referenced by a file) located in the local directory, you can use

  var srcPath = job.get("srcFilePath");
 

To get the filename (in cases where the payload is referenced by a file) located in the local directory, you can use

  var srcFile = job.get("srcFileName");
 

To get the data object, which is not referenced by a filename

  var dataObject = job.get("dataObj");
 

To get the trading partner name

  var tpName = job.get("tpName");
 

To get the trading host name

  var hostName = job.get("hostName");
 

The variables that are available for the FTP inbound transport configured in business agreements (FTP inbound) are: To get the temporary directory, where the file(s) will be downloaded from the FTP server, you can use

  var getTmpDir = job.get("getTmpDir");
 

To get the trading partner name

  var tpName = job.get("tpName");
 

To get the trading host name

  var hostName = job.get("hostName");
 

Field Summary

static java.lang.String	ALL_FILE_LIST Optional, it can be used by business protocols during post processing messages.
static java.lang.String	COMMON_ALL_FILE_LIST Optional, it can be used by business protocols during post processing messages.
static java.lang.String	DATA_OBJ If the payload exists in memory and therefore it is not referenced by a filename, this slot holds the object, which can be retrieved through the method get("dataObj").
static int	DEFAULT_SSHFTP_PORT
static java.lang.String	DELETE_FILE Currently not used.
static java.lang.String	FTP_OBJ The name of the slot, which returns the ftp client itself.
static int	FTP_STATUS_ERROR Generic failure, possibly due to unknown reasons.
static int	FTP_STATUS_OK Generic successful completion.
static java.lang.String	HOSTNAME The host name
static java.lang.String	INPUT_SOURCE_DIR For FTP Get this is the path where the fetched files are to be stored
static java.lang.String	LOG_OBJ The log client extension handle for custom scripts to log.
static java.lang.String	OPERATION_ID The operation ID of the message.
static java.lang.String	ORIG_FILE_NAME Optional, it can be used by business protocols to indicate the original file name location of a file reference.
static java.lang.String	ORIG_FILE_PATH Optional, it can be used by business protocols to indicate the original path of a file reference.
static java.lang.String	OUTPUT_SOURCE_DIR For FTP Put this is the path where the referenced file is taken from.
static java.lang.String	RETRY_SLOT The value "true" or "false" depending on whether the custom script wants BusinessConnect to re-execute itself.
static java.lang.String	SRC_FILE_NAME The file name used specifically for outbound referenced payload.
static java.lang.String	TPNAME The partner name
static java.lang.String	TRANSACTION_ID The transaction ID of the message.
static java.lang.String	USER_STATUS_CODE The custom script can return a status code in this slot.
static java.lang.String	USER_STATUS_MSG The custom script can return a status message in this slot.

Method Summary

void	aeTrace(java.lang.String role, java.lang.String msgcode, java.lang.String desc, java.lang.String trackingInfo) Send information to the BusinessConnect log.
SSHFTPReply	executeAppendCmd(java.lang.String filename) Append a file to the ssh server.
SSHFTPReply	executeDelCmd(java.lang.String filename) Delete a file from the ssh server.
SSHFTPReply	executeGetCmd(java.lang.String filename) Retrieve the file specified.
SSHFTPReply	executeListCmd(java.lang.String filename) Retrieve a list of entries from a directory on the SSH server.
SSHFTPReply[]	executeMdelCmd(java.lang.String filename) Delete one or more files from the ssh server.
SSHFTPReply[]	executeMgetCmd(java.lang.String filename) Retrieve file(s) specified by a pattern.
SSHFTPReply	executeMkdirCmd(java.lang.String pathname) Create a directory on the ssh server.
SSHFTPReply[]	executeMputCmd(java.lang.String filename) Copy one or more files to the ssh server.
SSHFTPReply	executePutCmd(java.lang.Object data, boolean isreference, java.lang.String remotefilename) Copy a file to the ssh server and create the file with the name 'remotefilename'.
SSHFTPReply	executePutCmd(java.lang.Object data, boolean isreference, java.lang.String remotefilename, boolean append) Copy a file to the ssh server and create the file with the name 'remotefilename'.
SSHFTPReply	executePutCmd(java.lang.String filename) Copy a file to the ssh server.
SSHFTPReply	executePutCmd(java.lang.String filename, boolean append) Copy a file to the ssh server and possibly append it to an existing file with the same name.
SSHFTPReply	executePutCmd(java.lang.String filename, java.lang.String remotefilename) Copy a file to the ssh server and create the file with the name 'remotefilename' on the ssh server.
SSHFTPReply	executePutCmd(java.lang.String filename, java.lang.String remotefilename, boolean append) Copy a file to the ssh server and create the file with the name 'remotefilename'.
SSHFTPReply	executeRenameCmd(java.lang.String oldfilename, java.lang.String newfilename) Rename a file on the ssh server.
SSHFTPReply	executeRmdirCmd(java.lang.String pathname) Delete a directory from the ssh server.
IClientObject	getClientObject() Retrieve a client object, which can provide more context specific information about the transaction.
java.lang.String	getHost() Gets the hostname of the SSHFTP server.
java.lang.String	getName() Retrieve the name of the ssh client instance.
java.lang.String	getPassword() Gets the password that is used to connect to the SSHFTP server.
int	getPort() Gets the port number that is used to connect to the SSHFTP server.
java.lang.String	getRemoteDir() Retrieve the effective remote directory, which is currently used by the sshftp client instance.
int	getTimeout() Retrieve the timeout on a connected tunnel awaiting the peer's reply
java.lang.String	getUsername() Gets the username that is used to connect to the SSHFTP server.
void	setHostPrivateKey(java.lang.String hostPrivateKeyName) The ssh private key, which the custom script wants to use instead of the one configured for the transport.
void	setPeerPublicKey(java.lang.String peerPublicKeyName) The ssh public key, which the custom script wants to use instead of the one configured for the transport.
void	setRemoteDir(java.lang.String relativePath) Set the effective remote directory, which will be used by the sshftp client instance.
void	setTimeout(int timeout) Set the timeout on a connected tunnel awaiting the peer's reply
boolean	useProxyServer() Checks if a proxy server is used to connect to the SSHFTP server.

Field Detail

FTP_STATUS_OK

static final int FTP_STATUS_OK

Generic successful completion.

See Also:

Constant Field Values

FTP_STATUS_ERROR

static final int FTP_STATUS_ERROR

Generic failure, possibly due to unknown reasons.

See Also:

Constant Field Values

FTP_OBJ

static final java.lang.String FTP_OBJ

The name of the slot, which returns the ftp client itself. This means that the script variable 'job' is essnetially identical to job.get(Packages.com.tibco.ax.fw.runtime.transport.sshftp.FTP_OBJ).

See Also:

Constant Field Values

TPNAME

static final java.lang.String TPNAME

The partner name

See Also:

Constant Field Values

HOSTNAME

static final java.lang.String HOSTNAME

The host name

See Also:

Constant Field Values

LOG_OBJ

static final java.lang.String LOG_OBJ

The log client extension handle for custom scripts to log.

See Also:

Constant Field Values

SRC_FILE_NAME

static final java.lang.String SRC_FILE_NAME

The file name used specifically for outbound referenced payload.

See Also:

Constant Field Values

OUTPUT_SOURCE_DIR

static final java.lang.String OUTPUT_SOURCE_DIR

For FTP Put this is the path where the referenced file is taken from.

See Also:

Constant Field Values

ORIG_FILE_NAME

static final java.lang.String ORIG_FILE_NAME

Optional, it can be used by business protocols to indicate the original file name location of a file reference. Consult with the protocol documentation for more details.

See Also:

Constant Field Values

ORIG_FILE_PATH

static final java.lang.String ORIG_FILE_PATH

Optional, it can be used by business protocols to indicate the original path of a file reference. Consult with the protocol documentation for more details.

See Also:

Constant Field Values

TRANSACTION_ID

static final java.lang.String TRANSACTION_ID

The transaction ID of the message. E.g. Tid0001

See Also:

Constant Field Values

OPERATION_ID

static final java.lang.String OPERATION_ID

The operation ID of the message. E.g. BC/1.0/Notify

See Also:

Constant Field Values

DATA_OBJ

static final java.lang.String DATA_OBJ

If the payload exists in memory and therefore it is not referenced by a filename, this slot holds the object, which can be retrieved through the method get("dataObj").

See Also:

Constant Field Values

INPUT_SOURCE_DIR

static final java.lang.String INPUT_SOURCE_DIR

For FTP Get this is the path where the fetched files are to be stored

See Also:

Constant Field Values

RETRY_SLOT

static final java.lang.String RETRY_SLOT

The value "true" or "false" depending on whether the custom script wants BusinessConnect to re-execute itself. The script can only ask for re-execution at most as many times as the transport's "Retry Count" property has been configured to.

See Also:

Constant Field Values

USER_STATUS_CODE

static final java.lang.String USER_STATUS_CODE

The custom script can return a status code in this slot. This value is used by the framework to determine the outcome of the custom script. If this slot is not populated or populated with a value such that 200 <= code < 300, the framework assumes a successful execution, else an error will be assumed and the corresponding advisory will be generated.

See Also:

Constant Field Values

USER_STATUS_MSG

static final java.lang.String USER_STATUS_MSG

The custom script can return a status message in this slot.

See Also:

Constant Field Values

ALL_FILE_LIST

static final java.lang.String ALL_FILE_LIST

Optional, it can be used by business protocols during post processing messages. Consult with the protocol documentation for more details.

See Also:

Constant Field Values

COMMON_ALL_FILE_LIST

static final java.lang.String COMMON_ALL_FILE_LIST

Optional, it can be used by business protocols during post processing messages. Consult with the protocol documentation for more details.

See Also:

Constant Field Values

DELETE_FILE

static final java.lang.String DELETE_FILE

Currently not used.

See Also:

Constant Field Values

DEFAULT_SSHFTP_PORT

static final int DEFAULT_SSHFTP_PORT

See Also:

Constant Field Values

Method Detail

getUsername

java.lang.String getUsername()

Gets the username that is used to connect to the SSHFTP server.

Returns:

the username entered in configuration.

getPassword

java.lang.String getPassword()

Gets the password that is used to connect to the SSHFTP server. This is the password used to connect with the username returned from getUsername().

Returns:

the clear text password.

getHost

java.lang.String getHost()

Gets the hostname of the SSHFTP server.

Returns:

the hostname of the server.

getPort

int getPort()

Gets the port number that is used to connect to the SSHFTP server. The default is DEFAULT_SSHFTP_PORT if the url specifies no port.

Returns:

the port number specified in url.

setPeerPublicKey

void setPeerPublicKey(java.lang.String peerPublicKeyName)
                      throws java.lang.Exception

The ssh public key, which the custom script wants to use instead of the one configured for the transport. The overriding credential must also exist in the configuration and has to be assigned to the given trading partner.

Parameters:

peerPublicKeyName - The name of the alternative credential to be used.

Throws:

java.lang.Exception

setHostPrivateKey

void setHostPrivateKey(java.lang.String hostPrivateKeyName)
                       throws java.lang.Exception

The ssh private key, which the custom script wants to use instead of the one configured for the transport. The overriding credential must also exist in the configuration and has to be assigned to the given host.

Parameters:

hostPrivateKeyName - The name of the alternative credential to be used.

Throws:

java.lang.Exception

useProxyServer

boolean useProxyServer()

Checks if a proxy server is used to connect to the SSHFTP server.

Returns:

true if a proxy server is used to connect, false if a proxy server is not used to connect to the SSHFTP server.

executeListCmd

SSHFTPReply executeListCmd(java.lang.String filename)
                           throws java.lang.Exception

Retrieve a list of entries from a directory on the SSH server. The details of the list entries can be obtained through the returned SSHFTPReply object, using the IFTPFlavorReply.getRemoteFileList() method. This method returns a Vector object, whose elements are FileAttr objects, each representing one entry from the list.

Parameters:

filename - The name of the path from which to retrieve entries.

Returns:

The reply object, which contains zero or more entries. Note that each entry can be either a directory or a file.

Throws:

java.lang.Exception

executeGetCmd

SSHFTPReply executeGetCmd(java.lang.String filename)
                          throws java.lang.Exception

Retrieve the file specified.

Parameters:

filename - The file to be retrieved.

Returns:

The retrieved file.

Throws:

java.lang.Exception

executeMgetCmd

SSHFTPReply[] executeMgetCmd(java.lang.String filename)
                             throws java.lang.Exception

Retrieve file(s) specified by a pattern. it may return zero or more replies.

Parameters:

filename - The name of the file or a pattern. Currently, the '*' character can be used to match part(s) of the filename. Only files (not directories) will be returned that match the specified pattern.

Returns:

The replies that matched the criteria.

Throws:

java.lang.Exception

executePutCmd

SSHFTPReply executePutCmd(java.lang.String filename)
                          throws java.lang.Exception

Copy a file to the ssh server. If the file exists at the time of copying, it will be overwritten.

Parameters:

filename - The name of the file.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executePutCmd

SSHFTPReply executePutCmd(java.lang.String filename,
                          boolean append)
                          throws java.lang.Exception

Copy a file to the ssh server and possibly append it to an existing file with the same name. If the file exists at the time of copying, it will be overwritten.

Parameters:

filename - The name of the file.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executePutCmd

SSHFTPReply executePutCmd(java.lang.String filename,
                          java.lang.String remotefilename)
                          throws java.lang.Exception

Copy a file to the ssh server and create the file with the name 'remotefilename' on the ssh server. If the file exists at the time of copying, it will be overwritten.

Parameters:

filename - The name of the file on the local system.

remotefilename - The name to of the file.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executePutCmd

SSHFTPReply executePutCmd(java.lang.String filename,
                          java.lang.String remotefilename,
                          boolean append)
                          throws java.lang.Exception

Copy a file to the ssh server and create the file with the name 'remotefilename'. If the file exists at the time of copying, it will be overwritten unless 'append' is set to true.

Parameters:

filename - The name of the file on the local system.

remotefilename - The name to of the file.

append - true if want to append, false otherwise.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executePutCmd

SSHFTPReply executePutCmd(java.lang.Object data,
                          boolean isreference,
                          java.lang.String remotefilename)
                          throws java.lang.Exception

Copy a file to the ssh server and create the file with the name 'remotefilename'. If the file exists at the time of copying, it will be overwritten.

Parameters:

data - The name of the file on the local system.

isreference - true if data is a reference, false otherwise. E.g. if data is a filename, it refers to the content, therefore isreference should be true in this case.

remotefilename - The name to of the file.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executePutCmd

SSHFTPReply executePutCmd(java.lang.Object data,
                          boolean isreference,
                          java.lang.String remotefilename,
                          boolean append)
                          throws java.lang.Exception

Copy a file to the ssh server and create the file with the name 'remotefilename'. If the file exists at the time of copying, it will be overwritten unless 'append' is set to true.

Parameters:

data - The name of the file on the local system.

isreference - true if data is a reference, false otherwise. E.g. if data is a filename, it refers to the content, therefore isreference should be true in this case.

remotefilename - The name to of the file.

append - true if want to append, false otherwise.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executeMputCmd

SSHFTPReply[] executeMputCmd(java.lang.String filename)
                             throws java.lang.Exception

Copy one or more files to the ssh server.

Parameters:

filename - The name of the file to be copied ('*' can be used for wildcard)

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executeAppendCmd

SSHFTPReply executeAppendCmd(java.lang.String filename)
                             throws java.lang.Exception

Append a file to the ssh server. If the file doesn't exist, it will be created.

Parameters:

filename - The name of the file.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executeRenameCmd

SSHFTPReply executeRenameCmd(java.lang.String oldfilename,
                             java.lang.String newfilename)
                             throws java.lang.Exception

Rename a file on the ssh server.

Parameters:

oldfilename - The name of the file to be renamed from.

newfilename - The name of the file to be renamed to.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executeDelCmd

SSHFTPReply executeDelCmd(java.lang.String filename)
                          throws java.lang.Exception

Delete a file from the ssh server.

Parameters:

filename - The name of the file.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executeMdelCmd

SSHFTPReply[] executeMdelCmd(java.lang.String filename)
                             throws java.lang.Exception

Delete one or more files from the ssh server.

Parameters:

filename - The name of the file to be deleted ('*' can be used for wildcard)

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executeMkdirCmd

SSHFTPReply executeMkdirCmd(java.lang.String pathname)
                            throws java.lang.Exception

Create a directory on the ssh server.

Parameters:

pathname - The name of the directory to be created.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

executeRmdirCmd

SSHFTPReply executeRmdirCmd(java.lang.String pathname)
                            throws java.lang.Exception

Delete a directory from the ssh server.

Parameters:

pathname - The name of the directory to be deleted.

Returns:

The reply with the status of the operation.

Throws:

java.lang.Exception

aeTrace

void aeTrace(java.lang.String role,
             java.lang.String msgcode,
             java.lang.String desc,
             java.lang.String trackingInfo)

Send information to the BusinessConnect log.

Parameters:

role - any of the values "INFO", "ERROR", "WARN", "DEBUG".

msgcode - any message code that the script may want to return, e.g. 200.

desc - any message describing the event, e.g. "Message has been sent successfully."

trackingInfo - any optional info to track/identify the event, e.g. an identifier of the business message. May be null or empty.

getRemoteDir

java.lang.String getRemoteDir()

Retrieve the effective remote directory, which is currently used by the sshftp client instance. By default, it is the configured directory specified for the given transport.

Returns:

The remote directory.

setRemoteDir

void setRemoteDir(java.lang.String relativePath)

Set the effective remote directory, which will be used by the sshftp client instance. By default, it is the configured directory specified for the given transport.

Parameters:

relativePath - The remote directory that the sshftp client will use as the base for the available operations. This path is relative to the configured directory, that is, if the transport is confiured with .../mydir then providing 'mysubdir' will set the remote directory to .../mydir/mysubdir.

getName

java.lang.String getName()

Retrieve the name of the ssh client instance.

Returns:

It currently returns "SSHFTPClientImpl".

getClientObject

IClientObject getClientObject()

Retrieve a client object, which can provide more context specific information about the transaction.

Returns:

The client object IClientObject.

getTimeout

int getTimeout()

Retrieve the timeout on a connected tunnel awaiting the peer's reply

Returns:

the max blocking wait in seconds

setTimeout

void setTimeout(int timeout)

Set the timeout on a connected tunnel awaiting the peer's reply

Parameters:

timeout - the max blocking wait in seconds