Using FioranoMQ LMS APIs

Interface ILargeMessage

Purpose

The ILargeMessage interface provides APIs with the ability to transfer large files and the ability to check the status and/or to resume a file transfer.

Method Summary

CODE

public LMTransferStatus getMessageStatus()

Retrieves the status of the message. 'Status' refers to the number of bytes transferred, the number of bytes left to be transferred, and so on.

CODE

public void setLMStatusListener(LMStatusListener listener, int updateFrequency);

Sets the status listener for the message. This API asynchronously detects the status of a message being transferred.

CODE

public LMStatusListener getLMStatusListener();

Retrieves the status listener for the message.

CODE

public void saveTo(String fileName, boolean isBlocking) throws FioranoException;

Saves the contents of the message in the file specified.

CODE

public void resumeSaveTo(boolean isBlocking) throws FioranoException;

Resumes an incomplete transfer. This API resumes the process of saving the contents of a message in the file specified.

CODE

public void resumeSend() throws FioranoException;

Resumes an incomplete transfer. This API resumes the process of sending a message. It is used when this process could not be completed due to either an internal error or due to a problem originating at the client's side.

CODE

public void cancelAllTransfers() throws FioranoException;

Cancels the transfer process of all messages for transferring this large message. Canceling a transfer removes the 'resume' information related to that transfer. A transfer once canceled, cannot be resumed.

CODE

public void cancelTransfer(int consumerID) throws FioranoException;

Cancels the transfer process of the message belonging to the consumer identified by the consumer ID. Every consumer has a unique consumer ID assigned by the producer when the transfer starts. The API can be used by the sender and by the receiver. Canceling a transfer removes the 'resume' information related to that transfer. A transfer, once canceled, cannot be resumed.

CODE

public void suspendAllTransfers() throws FioranoException;

Temporarily suspends all message transfers transferring this large message. Suspending a transfer only stops the thread that is performing the message transfer. No 'resume' related information is deleted. A transfer that is suspended can be resumed using resumeSend() and resumeSaveTo() APIs.

CODE

public void suspendTransfer(int consumerID) throws FioranoException;

Temporarily suspends the message transfer specified by the consumer ID. Suspending a transfer only stops the thread that is performing the message transfer. No 'resume' related information is deleted so a suspended transfer can be resumed using resumeSend () and resumeSaveTo() APIs.

CODE

public void setFragmentSize(int size)

Sets the fragment size of the message.

CODE

public int getFragmentSize()

Retrieves the fragment size of the message.

CODE

public void setWindowSize(int size)

Sets the window size for the message. Window size indicates the length of the time interval, after which the receiver sends an acknowledgment for message fragments received.

CODE

public int getWindowSize()

Retrieves the window size of the message.

CODE

public void setRequestTimeoutInterval(long timeout)

Sets the time duration for which sender waits for large message requests sent by the receiver.

CODE

public long getRequestTimeoutInterval()

Retrieves the time duration for which the sender waits for the receiver's request.

CODE

public void setResponseTimeoutInterval(long timeout)

Sets the time duration for which the receiver waits for a message fragment sent by the sender.

CODE

public long getResponseTimeoutInterval()

Retrieves the time duration for which the receiver waits to receive a message fragment from the sender.

Interface ILMConnection

Purpose

ILMConnection provides APIs to retrieve messages that could not be entirely sent or received.

Method Summary

CODE

public void setResumeDirectory(java.lang.String dir)

Sets the User directory within which the resume file is saved

CODE

public String getResumeDirectory()

Retrieves the user directory in which the resume file is saved

CODE

public java.util.Enumeration getUnfinishedMessagesToSend ()

Retrieves the enumeration of ILargeMessages that could not be sent in entirety.

CODE

public java.util.Enumeration getUnfinishedMessagesToReceive ()

Retrieves the enumeration of ILargeMessages that fail to be transferred in their entirety.

CODE

public boolean hasTransfersInExecution ()

Indicates whether a connection has any ongoing transfers. This API is used by the application to close the connection depending upon whether or not the connection has transfers in progress.

Class LMTransferStatus

Purpose

Class LMTransferStatus provides the status of a message transfer. The 'status' of a message transfer refers to the number of bytes transferred, the number of bytes to be transferred, the last fragment of bytes transferred successfully, the percentage of progress of the transfer, and so on.

Constants Summary

CODE

public static final byte LM_TRANSFER_NOT_INIT=0x01;

Indicates that the transfer has not yet started.

CODE

public static final byte LM_TRANSFER_IN_PROGRESS=0x02;

Indicates that the transfer is currently in progress.

CODE

public static final byte LM_TRANSFER_DONE

Indicates that the transfer is complete.

CODE

public status LM_TRANSFER_ERR

Indicates that an error occurred during the transfer.

Method Summary

CODE

public long getBytesTransferred()

Returns the number of bytes transferred.

CODE

public long getBytesToTransfer()

Returns the number of bytes left to be transferred.

CODE

public long getLastFragmentID()

Returns the fragment number of the last fragment sent successfully.

CODE

public float getPercentageProgress()

Returns the percentage of completion of the message transfer.

CODE

public byte getStatus()

Returns the status of the message transfer. The status of a message can be any one of the statuses mentioned above.

CODE

public boolean isTransferComplete()

Returns a Boolean value, indicative of whether or not the transfer was completed successfully.

CODE

public ILargeMessage getLargeMessage ()

Returns the reference of a large message whose status is displayed by LMTransferStatus.

Interface LMStatusListener

Purpose

The LMStatusListener interface is used to detect, asynchronously, the status of a message being transferred.

Method Summary

CODE

public void onLMStatus(fiorano.jms.lm.LMTransferStatus status, FioranoException exception)

Method callback is invoked in the event of a change in message transfer status, or in the event of an error that occurs during message transfer.

Class FioranoLMErrorCodes

Purpose
Class FioranoLMErrorCodes defines the error codes and error messages used by LMS.

CODE

LM_INVALID_SOURCE_FILE

This exception is encountered when the source file specified in the message is invalid.

CODE

LM_CSP_ENABLED

This exception is encountered when CSP/Durable connections are enabled when using LMS.

CODE

LM_REQUEST_TIMEOUT

This exception is encountered when a request for a large message is not received from any consumer in the specified time duration.

CODE

LM_DECODE_LMS_PROPERTIES_FAILURE

This exception is encountered when an error occurs in the process of decoding LMS properties

CODE

LM_ACK_NOT_RECEIVED

This exception is encountered when the producer does not receive any acknowledgement of receipt of message fragments from the consumer in the specified time duration.

CODE

LM_FRAGMENT_SEND_FAILURE

This exception is encountered when the producer is unable to send the message fragment to the consumer.

CODE

LM_ACK_PROCESS_FAILURE

This exception is encountered when the producer is unable to process the acknowledgement received from the consumer.

CODE

LM_MESSAGE_TRANSFER_ERROR

This exception is encountered when an error occurs on the producer's side during a message transfer.

CODE

LM_INITIALIZATION_ERROR

This exception is encountered when an error occurs while initializing the message transfer.

CODE

LM_REQUEST_PROCESS_FAILURE

This exception is encountered when an error occurs while processing the message request received from the consumer.

CODE

LM_SEND_AVAILABILITY_FAILURE

This exception is encountered when the producer is unable to send message availability notification to the consumer. The 'availability' message is a message that is sent by the producer to the consumer if there are any unfinished messages to resume.

CODE

LM_READ_DATA_ERROR

This exception is encountered when an error occurs while reading data from the source file.

CODE

LM_RECEIVE_FRAGMENT_ERROR

This exception is encountered when an error occurs while receiving message fragments sent by the producer.

CODE

LM_RECEIVE_FRAGMENT_TIMEOUT

This exception is encountered when the consumer is not able to receive the message fragment within the period of the specified 'timeout'.

CODE

LM_UNABLE_TO_SEND_FRAGMENT_ACK

This exception is encountered when the consumer is not able to the send an acknowledgement regarding a message fragment to the producer.

CODE

LM_UNABLE_TO_RESUME_SEND

This exception is encountered when the producer is not able to resume a message transfer.

CODE

LM_INVALID_TARGET_FILE

This exception is encountered when the target file specified by the consumer is not valid.

CODE

LM_UNABLE_TO_SAVE_TARGET_FILE

This exception is encountered when an error occurs while saving the target file due to the unavailability of free disk space.

CODE

LM_UNABLE_TO_RESUME_RECEIVE

This exception is encountered when the consumer is not able to resume the message transfer.

CODE

LM_WRITE_DATA_ERROR

This exception is encountered when an error occurs while writing data onto the target file.

CODE

LM_UNABLE_TO_SAVETO_FILE

This exception is encountered when saveTo() API is invoked for a message which is not considered a large message.

CODE

LM_TRANSFER_NOT_STARTED

This exception is encountered when cancellation of a transfer is invoked for a message that is not considered a large message.