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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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