com.waveset.util.jms
Interface JmsWriter


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


Field Summary
static java.lang.String code_id
           
static java.lang.String DELIVERY_MODE
           
static java.lang.String DELIVERY_MODE_OPT_NONPERSISTENT
           
static java.lang.String DELIVERY_MODE_OPT_PERSISTENT
           
static java.lang.String DESTINATION_NAME
           
static java.lang.String FACTORY_NAME
           
static java.lang.String JNDI_PROPERTIES
           
static java.lang.String PASSWORD
           
static java.lang.String PRIORITY
           
static java.lang.String RELIABILITY_MODE
           
static java.lang.String TIME_TO_LIVE
           
static java.lang.String USERNAME
           
 
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.
 

Field Detail

code_id

static final java.lang.String code_id
See Also:
Constant Field Values

DELIVERY_MODE

static final java.lang.String DELIVERY_MODE
See Also:
Constant Field Values

DELIVERY_MODE_OPT_NONPERSISTENT

static final java.lang.String DELIVERY_MODE_OPT_NONPERSISTENT
See Also:
Constant Field Values

DELIVERY_MODE_OPT_PERSISTENT

static final java.lang.String DELIVERY_MODE_OPT_PERSISTENT
See Also:
Constant Field Values

DESTINATION_NAME

static final java.lang.String DESTINATION_NAME
See Also:
Constant Field Values

FACTORY_NAME

static final java.lang.String FACTORY_NAME
See Also:
Constant Field Values

JNDI_PROPERTIES

static final java.lang.String JNDI_PROPERTIES
See Also:
Constant Field Values

PASSWORD

static final java.lang.String PASSWORD
See Also:
Constant Field Values

PRIORITY

static final java.lang.String PRIORITY
See Also:
Constant Field Values

RELIABILITY_MODE

static final java.lang.String RELIABILITY_MODE
See Also:
Constant Field Values

TIME_TO_LIVE

static final java.lang.String TIME_TO_LIVE
See Also:
Constant Field Values

USERNAME

static final java.lang.String USERNAME
See Also:
Constant Field Values
Method Detail

close

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().


commit

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.

createBytesMessage

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.

createMapMessage

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.

createObjectMessage

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.

createStreamMessage

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.

createTextMessage

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

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.

isTransacted

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.

rollback

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.

write

void write(javax.jms.Message message,
           java.util.Map writeOptions)
           throws com.waveset.util.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:
com.waveset.util.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

void writeAndCommit(javax.jms.Message message,
                    java.util.Map writeOptions)
                    throws com.waveset.util.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:
com.waveset.util.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

void writeAndCommitAndClose(javax.jms.Message message,
                            java.util.Map writeOptions)
                            throws com.waveset.util.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:
com.waveset.util.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.