com.sssw.jms.api
Interface JMQFileMessage

All Superinterfaces:

BytesMessage, Message

public interface JMQFileMessage

extends BytesMessage

A JMQFileMessage object is used to send a message containing one or more files (java.io.File objects). It inherits from the BytesMessage interface and treats the bytes of the file(s) as the message body. Although a BytesMessage can be used to send files, this message provides a more convenient way of doing so.

The bytes message is encoded as follows. For each file in the message body three data items are present. First, there is an integer with the length of the file data. Then a UTF string with the canonical file name. Finally, a byte[] with the raw file data.

When a consumer receives a JMQFileMessage, it is in read-only mode. If a client attempts to write to the message at this point, a MessageNotWriteableException is thrown. If clearBody is called, the message can now be both read from and written to.

A consumer will typically typecast the incoming message to a JMQFileMessage object and access the files using the methods of this class. However, the JMQFileMessage can also be treated as a BytesMessage where the body data is encoded as described above.

Since:

jBroker MQ 2.1

See Also:

File, BytesMessage, JMQSession

Field Summary

Fields inherited from interface javax.jms.Message

DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE

Method Summary

byte[]	getFile() Gets the next file in the byte stream.
byte[][]	getFiles() Gets all files in the message body.
String	getName() Get the name of the file last read from the stream.
void	save(File file) Save the next file in the byte stream to the specified file.
void	save(String file) Convenience method for saving the next file in the byte stream.
void	setFile(File file) Sets the specified file as the body of this message.
void	setFile(String file) Convenience method for setting file using string argument.
void	setFiles(File[] file) Sets the specified files as the body of this message.
void	setFiles(String[] file) Convenience method for setting file using string argument.

Methods inherited from interface javax.jms.BytesMessage

readBoolean, readByte, readBytes, readBytes, readChar, readDouble, readFloat, readInt, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, reset, writeBoolean, writeByte, writeBytes, writeBytes, writeChar, writeDouble, writeFloat, writeInt, writeLong, writeObject, writeShort, writeUTF

Methods inherited from interface javax.jms.Message

acknowledge, clearBody, clearProperties, getBooleanProperty, getByteProperty, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, propertyExists, setBooleanProperty, setByteProperty, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty

Method Detail

setFile

public void setFile(File file)
             throws JMSException

Sets the specified file as the body of this message. If one or more files were previously set as the message's data, they will be replaced with this file.

Parameters:

file - the File containing the message's data

Throws:

JMSException - if the JMS provider fails to set the file due to some internal error.

MessageNotWriteableException - if the message is in read-only mode.

setFile

public void setFile(String file)
             throws JMSException

Convenience method for setting file using string argument.

Parameters:

file - name of file containing the message's data

Throws:

JMSException - if the JMS provider fails to set the file due to some internal error.

MessageNotWriteableException - if the message is in read-only mode.

setFiles

public void setFiles(File[] file)
              throws JMSException

Sets the specified files as the body of this message. If one or more files were previously set as the message's data, they will be replaced with these files.

Parameters:

file - the File's containing the message's data

Throws:

JMSException - if the JMS provider fails to set the files due to some internal error.

MessageNotWriteableException - if the message is in read-only mode.

setFiles

public void setFiles(String[] file)
              throws JMSException

Convenience method for setting file using string argument.

Parameters:

file - names of files containing the message's data

Throws:

JMSException - if the JMS provider fails to set the file due to some internal error.

MessageNotWriteableException - if the message is in read-only mode.

getFile

public byte[] getFile()
               throws JMSException

Gets the next file in the byte stream. After reading the file, the stream will be positioned right before the next file (if any).

Returns:

a byte array with the file data

Throws:

JMSException - if the JMS provider fails to get the text due to some internal error.

save

public void save(File file)
          throws JMSException

Save the next file in the byte stream to the specified file. After invoking this method, the stream will be positioned right before the next file (if any).

Parameters:

file - the File where the file data will be saved.

Throws:

JMSException - if the JMS provider fails to save the file.

save

public void save(String file)
          throws JMSException

Convenience method for saving the next file in the byte stream.

Parameters:

file - the name of the file where the file data will be saved.

Throws:

JMSException - if the JMS provider fails to save the file.

getFiles

public byte[][] getFiles()
                  throws JMSException

Gets all files in the message body. If some files have already been read, the remaining files in the message body are returned. After invoking this method, the stream is positioned at the end and no more data can be read.

Returns:

an array of byte arrays with the file data

Throws:

JMSException - if the JMS provider fails to get the text due to some internal error.

getName

public String getName()
               throws JMSException

Get the name of the file last read from the stream. The name is derived from the name of the file added to the message at the producer side.

Returns:

the name of the file last read from the byte stream

Throws:

JMSException - if the JMS provider fails to get the text due to some internal error.