com.waveset.util.jms
Interface JmsWriter

All Known Implementing Classes:
JmsWriterBase

public interface JmsWriter

A JmsWriter represents a simple, high-level mechanism to send messages to a JMS queue or topic.

You must use JmsWriterFactory to obtain an instance of a JmsWriter


Method Summary
 void close()
          Inform the system that no more messaging will occur on this object.
 void commit()
          Commit all messages done in the current transaction and release any locks currently held.
 javax.jms.BytesMessage createBytesMessage()
           
 javax.jms.MapMessage createMapMessage()
           
 javax.jms.ObjectMessage createObjectMessage()
           
 javax.jms.StreamMessage createStreamMessage()
           
 javax.jms.TextMessage createTextMessage()
           
 javax.jms.TextMessage createTextMessage(java.lang.String text)
           
 boolean isTransacted()
           
 void rollback()
          Rollback all messages done in the current transaction and release any locks currently held.
 void write(javax.jms.Message message, java.util.Map writeOptions)
          Write a message.
 void writeAndCommit(javax.jms.Message message, java.util.Map writeOptions)
          Write a message, and then immediately commit the session.
 void writeAndCommitAndClose(javax.jms.Message message, java.util.Map writeOptions)
          Write a message, commit the session, and close the connection.
 

Method Detail

createTextMessage

public javax.jms.TextMessage createTextMessage()
                                        throws javax.jms.JMSException
Returns:
an un-initialized TextMessage. A TextMessage is used to send a message containing a String.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error

createTextMessage

public javax.jms.TextMessage createTextMessage(java.lang.String text)
                                        throws javax.jms.JMSException
Parameters:
text - the string used to initialize this message
Returns:
an initialized TextMessage. A TextMessage is used to send a message containing a String.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createMapMessage

public javax.jms.MapMessage createMapMessage()
                                      throws javax.jms.JMSException
Returns:
a MapMessage. A MapMessage is used to send a self-defining set of name-value pairs where names are Strings and values are Java primitive types.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createStreamMessage

public javax.jms.StreamMessage createStreamMessage()
                                            throws javax.jms.JMSException
Returns:
a StreamMessage. A StreamMessage is used to send a self-defining stream of Java primitives.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createObjectMessage

public javax.jms.ObjectMessage createObjectMessage()
                                            throws javax.jms.JMSException
Returns:
an initialized ObjectMessage. An ObjectMessage is used to send a message that containing a serializable Java object.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createBytesMessage

public javax.jms.BytesMessage createBytesMessage()
                                          throws javax.jms.JMSException
Returns:
a BytesMessage. A BytesMessage is used to send a message containing a stream of uninterpreted bytes.
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

write

public void write(javax.jms.Message message,
                  java.util.Map writeOptions)
           throws WavesetException,
                  javax.jms.JMSException
Write a message.

Use this method if the JmsWriter is not transacted. If transacted, you can use this method when you wish to send multiple Messages within the same transaction .

NOTE: If transacted, the message will not truly be sent until commit() is called.

Parameters:
message - the message to be sent
writeOptions - Specify a non-null writeOptions map if you need to specify delivery mode, priority and time to live options.

The table below describes each expected key for the writeOptions map, and the significance of each key's value.

KeyValue typeReqd?UsageDefault
"deliveryMode" java.lang.String no Valid values are "PERSISTENT" and "NON_PERSISTENT" "PERSISTENT"
"priority" java.lang.String or java.lang.Integer no The message priority for this message. Priority must be a value between 0 and 9.

JMS defines a 10 level priority value with 0 as the lowest and 9 as the highest. Clients should consider 0-4 as gradients of normal priority and 5-9 as gradients of expedited priority. Priority is set to 4, by default.

4
"timeToLive" java.lang.String or java.lang.Integer no The length of time in milliseconds from its dispatch time that a produced message should be retained by the message system. zero is unlimited. 0
Throws:
WavesetException - if illegal values are found in writeOptions map
javax.jms.JMSException - if JMS fails to send the message due to some internal error

writeAndCommit

public void writeAndCommit(javax.jms.Message message,
                           java.util.Map writeOptions)
                    throws WavesetException,
                           javax.jms.JMSException
Write a message, and then immediately commit the session.

NOTE: The commit will be performed only if the session is transacted.

Parameters:
message - the message to be sent
writeOptions - same as described in write
Throws:
WavesetException - if illegal values are found in writeOptions map
javax.jms.JMSException - if JMS fails to send the message or to commit the transaction due to some internal error.

writeAndCommitAndClose

public void writeAndCommitAndClose(javax.jms.Message message,
                                   java.util.Map writeOptions)
                            throws WavesetException,
                                   javax.jms.JMSException
Write a message, commit the session, and close the connection.

This is the most succinct way to send a message, however it does not offer you the opportunity to send multiple messages over a single connection.

NOTE: The commit will be performed only if the session is transacted.

Parameters:
message - the message to be sent
writeOptions - same as described in write
Throws:
WavesetException - if illegal values are found in writeOptions map
javax.jms.JMSException - if JMS fails to send the message or to commit the transaction due to some internal error.

commit

public void commit()
            throws javax.jms.JMSException
Commit all messages done in the current transaction and release any locks currently held. The commit will be performed only if the session is transacted.

Throws:
javax.jms.JMSException - if JMS fails to commit the session due to some internal error.

rollback

public void rollback()
              throws javax.jms.JMSException
Rollback all messages done in the current transaction and release any locks currently held. The rollback will be performed only if the session is transacted.

Throws:
javax.jms.JMSException - if JMS fails to rollback the session due to some internal error.

close

public void close()
Inform the system that no more messaging will occur on this object. All resources will be freed.

Any transacted session will be rolled back.

Do not attempt to use this object again after calling close().


isTransacted

public boolean isTransacted()
                     throws javax.jms.JMSException
Returns:
true if the encapsulated javax.jms.Session is in transacted mode; otherwise return false.

If this was created with "LOCAL" reliabilityMode, then it is transacted.

Throws:
javax.jms.JMSException - if JMS fails to return the transaction mode due to internal error in JMS Provider.