org.qbroker.jms

Class SFTPMessenger

java.lang.Object

org.qbroker.net.SFTPConnector

org.qbroker.jms.SFTPMessenger

All Implemented Interfaces:

Connector

public class SFTPMessenger
extends SFTPConnector

SFTPMessenger connects to a SSH server and initializes one of the operations, such as retrieve, download and store. It carries out the operation with JMS Messages.

There are seven methods, retrieve(), download(), list(), store(), copy(), upload() and pickup(). The first method, retrieve(), is used to retrieve files from SSH servers. The method of download() is used for synchronous requests. The method of store() is used for asynchronous storing content to remote SSH servers. The method of copy() is for copying a file from one SSH server to anther. Both upload() and pickup() are for large file transfers with JobPersister.

This is NOT MT-Safe. Therefore, you need to use multiple instances to achieve your MT goal.

Author:

yannanlu@yahoo.com

Field Summary

Fields inherited from class org.qbroker.net.SFTPConnector

ACTION_CWD, ACTION_DEL, ACTION_GET, ACTION_LIST, ACTION_MKD, ACTION_PUT, ACTION_PWD, ACTION_RMD, ACTION_SIZE, ACTION_TIME, FTP_ALL, FTP_DIRECTORY, FTP_FILE, FTP_LINK, FTP_UNKNOWN, uri

Constructor Summary

Constructors

Constructor and Description
SFTPMessenger(java.util.Map props) Creates new SFTPMessenger

Method Summary

Modifier and Type	Method and Description
void	copy(XQueue xq) It gets a JMS Message from the XQueue and retrieves the property map in JSON from its body.
void	download(XQueue xq) It gets a JMS message from xq that contains a filename to be downloaded and downloads the file via sftp.
java.lang.String	getOperation()
void	list(XQueue xq) It gets a JMS message from xq that contains a dirname for listing files in it and gets the list via sftp.
void	pickup(XQueue xq) It gets a JMS message from the uplink as the file transfer request that is either an init request for the file transfer or a query request for the progress of the file transfer.
void	retrieve(XQueue xq) retrieve a file from sftp server and put it to an XQ
void	store(XQueue xq) It gets a JMS Message from the XQueue and stores its body into a remote file via sftp continuously.
void	upload(XQueue xq) It gets a JMS message from the uplink as the file transfer request that is either an init request for the file transfer or a query request for the progress of the file transfer.

Methods inherited from class org.qbroker.net.SFTPConnector

close, connect, createDirectory, getChannelSftp, getParent, getSize, getTimestamp, getURI, isConnected, main, reconnect, retrieveFileStream, sftpCwd, sftpDelete, sftpGet, sftpGet, sftpGet, sftpList, sftpMkd, sftpPut, sftpPut, sftpPut, sftpPwd, sftpRmd, storeFileStream

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SFTPMessenger

public SFTPMessenger(java.util.Map props)
              throws com.jcraft.jsch.JSchException

Creates new SFTPMessenger

Throws:

com.jcraft.jsch.JSchException

Method Detail

retrieve

public void retrieve(XQueue xq)
              throws java.io.IOException,
                     javax.jms.JMSException

retrieve a file from sftp server and put it to an XQ

Throws:

java.io.IOException

javax.jms.JMSException

download

public void download(XQueue xq)
              throws java.io.IOException,
                     TimeoutException,
                     javax.jms.JMSException

It gets a JMS message from xq that contains a filename to be downloaded and downloads the file via sftp. If LocalStore is defined in the message, the downloaded file will be stored into the local filename. Otherwise, the content of the file will be put into the message body. The message will be removed from the XQueue so that the requester at the other end of the XQueue can easily process the content either out of the local filename or out of the message.

Since the download operation relies on a request, this method will intercept the request and processes it. The incoming message is required to be writeable. The method will set a String property of the message specified by the RCField with the return code, indicating the status of the process to fulfill the request. The requester is required to check the value of the property once it gets the message back. If the return code is 0, the download is successful. Otherwise, the download operation is failed. No matter what happens, it will not acknowledge the message.

If the MaxIdleTime is set to none-zero, it will monitor the idle time and will throw TimeoutException once the idle time exceeds MaxIdleTime. it is up to the caller to handle this exception.

Throws:

java.io.IOException

TimeoutException

javax.jms.JMSException

upload

public void upload(XQueue xq)
            throws java.io.IOException,
                   TimeoutException,
                   javax.jms.JMSException

It gets a JMS message from the uplink as the file transfer request that is either an init request for the file transfer or a query request for the progress of the file transfer. In case of the init file transfer request, it initializes the transfer job and starts to transfer the file. Meanwhile, it continues to listen to the xq for query request or other commands on the transfer job. For each query request, it loads the progress data and the status to the message and removes the message from the uplink so that the other end is able to collect it. When the transfer job completes, it cleans up the transfer job and acknowledges the init message before removing it from the uplink. In case that the incoming request is to abort the current transfer job, it will stop the transfer process and cleans up the job. The init message will be acknowledged and removed from the uplink.

Since the upload operation relies on requests, the method will intercept the requests and processes them. The incoming message is required to be writeable. The method will set a String property of the message specified by the RCField with the return code, indicating the status of the process to fulfill the request. The requester is required to check the value of the property once it gets the message back. If the return code is 0, the upload is successful. Otherwise, the message body will contain the failure reason out of upload operation.

If the MaxIdleTime is set to none-zero, it will monitor the idle time and will throw TimeoutException once the idle time exceeds MaxIdleTime. it is up to the caller to handle this exception.

Throws:

java.io.IOException

TimeoutException

javax.jms.JMSException

pickup

public void pickup(XQueue xq)
            throws java.io.IOException,
                   TimeoutException,
                   javax.jms.JMSException

It gets a JMS message from the uplink as the file transfer request that is either an init request for the file transfer or a query request for the progress of the file transfer. In case of the init file transfer request, it initializes the transfer job and starts to transfer the file. Meanwhile, it continues to listen to the xq for query request or other commands on the transfer job. For each query request, it loads the progress data and the status to the message and removes the message from the uplink so that the other end is able to collect it. When the transfer job completes, it cleans up the transfer job and acknowledges the init message before removing it from the uplink. In case that the incoming request is to abort the current transfer job, it will stop the transfer process and cleans up the job. The init message will be acknowledged and removed from the uplink.

Since the pickup operation relies on requests, the method will intercept the requests and processes them. The incoming message is required to be writeable. The method will set a String property of the message specified by the RCField with the return code, indicating the status of the process to fulfill the request. The requester is required to check the value of the property once it gets the message back. If the return code is 0, the pickup is successful. Otherwise, the message body will contain the failure reason out of upload operation.

If the MaxIdleTime is set to none-zero, it will monitor the idle time and will throw TimeoutException once the idle time exceeds MaxIdleTime. it is up to the caller to handle this exception.

Throws:

java.io.IOException

TimeoutException

javax.jms.JMSException

list

public void list(XQueue xq)
          throws java.io.IOException,
                 TimeoutException,
                 javax.jms.JMSException

It gets a JMS message from xq that contains a dirname for listing files in it and gets the list via sftp. It puts the list of files into the message body one name per line and sends it back. The requester at the other end of the XQueue can easily read the list out of the message.

Since the list operation relies on a request, this method will intercept the request and process it. The incoming message is required to be writeable. The method will set a String property of the message specified by the RCField with the return code, indicating the status of the process to fulfill the request. The requester is required to check the value of the property once it gets the message back. If the return code is 0, the list is successful. Otherwise, the message body will not contain the content out of the list operation.

If the MaxIdleTime is set to none-zero, it will monitor the idle time and will throw TimeoutException once the idle time exceeds MaxIdleTime. it is up to the caller to handle this exception.

Throws:

java.io.IOException

TimeoutException

javax.jms.JMSException

store

public void store(XQueue xq)
           throws java.io.IOException,
                  TimeoutException,
                  javax.jms.JMSException

It gets a JMS Message from the XQueue and stores its body into a remote file via sftp continuously.

It will always try to retrieve the URL from the field specified by FieldName property. If the message does not contain the URL, the method will use the default URL defined by URI property.

It also supports LocalStore feature so that it will read the content from the local file and stores the file to the remote filesystem. If the local file is a directory, it will transfer all the files and subdirectories to remote filesystem. In this case, there is no guarantee on the file transfer.

The store operation also supports the requests. If the XAMode has enabled the XA_CLIENT bit, it will treat the message as a request from the uplink. In this case, the incoming message is required to be writeable. The method will set a String property of the message specified by the RCField with the return code, indicating the status of the process to fulfill the request. The requester is supposed to check the value of the property once it gets the message back. If the return code is 0, the operation is successful. Otherwise, the request will be dropped due to failures. On the other hand, if the XA_CLIENT bit has been disabled by XAMode, the incoming message will not be modified.

If the MaxIdleTime is set to none-zero, it will monitor the idle time and will throw TimeoutException once the idle time exceeds MaxIdleTime. it is up to the caller to handle this exception.

If the XQueue has enabled the EXTERNAL_XA bit, it will also acknowledge the messages. This method is MT-Safe.

Throws:

java.io.IOException

TimeoutException

javax.jms.JMSException

copy

public void copy(XQueue xq)
          throws java.io.IOException,
                 TimeoutException,
                 javax.jms.JMSException

It gets a JMS Message from the XQueue and retrieves the property map in JSON from its body. It copies the source file defined in FileName to the remote file in LocalStore via sftp.

It will always try to retrieve the URL from the field specified by FileName property. If the message does not contain the URL, the method will use the default URL defined by URI property. The LocalStore specifies the target filename and its property map is required to be stored in message body.

The copy operation also supports the requests. If the XAMode has enabled the XA_CLIENT bit, it will treat the message as a request from the uplink. In this case, the incoming message is required to be writeable. The method will set a String property of the message specified by the RCField with the return code, indicating the status of the process to fulfill the request. The requester is supposed to check the value of the property once it gets the message back. If the return code is 0, the operation is successful. Otherwise, the request will be dropped due to failures. On the other hand, if the XA_CLIENT bit has been disabled by XAMode, the incoming message will not be modified.

If the MaxIdleTime is set to none-zero, it will monitor the idle time and will throw TimeoutException once the idle time exceeds MaxIdleTime. it is up to the caller to handle this exception.

If the XQueue has enabled the EXTERNAL_XA bit, it will also acknowledge the messages. This method is MT-Safe.

Throws:

java.io.IOException

TimeoutException

javax.jms.JMSException

getOperation

public java.lang.String getOperation()