javax.jms
Interface MessageProducer

A client uses a MessageProducer object to send messages to a
destination. A MessageProducer object is created by passing a
Destination object to a message-producer creation method
supplied by a session.

MessageProducer is the parent interface for all message
producers.

A client also has the option of creating a message producer without
supplying a destination. In this case, a destination must be provided with
every send operation. A typical use for this kind of message producer is
to send replies to requests using the request's JMSReplyTo
destination.

A client can specify a default delivery mode, priority, and time to live
for messages sent by a message producer. It can also specify the delivery
mode, priority, and time to live for an individual message.

A client can specify a time-to-live value in milliseconds for each
message it sends. This value defines a message expiration time that
is the sum of the message's time-to-live and the GMT when it is sent (for
transacted sends, this is the time the client sends the message, not
the time the transaction is committed).

A JMS provider should do its best to expire messages accurately;
however, the JMS API does not define the accuracy provided.

setDisableMessageID

Since message IDs take some effort to create and increase a
message's size, some JMS providers may be able to optimize message
overhead if they are given a hint that the message ID is not used by
an application. By calling the setDisableMessageID
method on this message producer, a JMS client enables this potential
optimization for all messages sent by this message producer. If the JMS
provider accepts this hint,
these messages must have the message ID set to null; if the provider
ignores the hint, the message ID must be set to its normal unique value.

Message IDs are enabled by default.

Parameters:

value - indicates if message IDs are disabled

Throws:

JMSException - if the JMS provider fails to set message ID to
disabled due to some internal error.

setDisableMessageTimestamp

Since timestamps take some effort to create and increase a
message's size, some JMS providers may be able to optimize message
overhead if they are given a hint that the timestamp is not used by an
application. By calling the setDisableMessageTimestamp
method on this message producer, a JMS client enables this potential
optimization for all messages sent by this message producer. If the
JMS provider accepts this hint,
these messages must have the timestamp set to zero; if the provider
ignores the hint, the timestamp must be set to its normal value.

Message timestamps are enabled by default.

Parameters:

value - indicates if message timestamps are disabled

Throws:

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

setPriority

The JMS API defines ten levels of priority value, with 0 as the
lowest priority and 9 as the highest. Clients should consider priorities
0-4 as gradations of normal priority and priorities 5-9 as gradations
of expedited priority. Priority is set to 4 by default.

Parameters:

defaultPriority - the message priority for this message producer;
must be a value between 0 and 9

Throws:

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

close

Since a provider may allocate some resources on behalf of a
MessageProducer outside the Java virtual machine, clients
should close them when they
are not needed. Relying on garbage collection to eventually reclaim
these resources may not be timely enough.

Throws:

JMSException - if the JMS provider fails to close the producer
due to some internal error.

send

Sends a message to a destination for an unidentified message producer.
Uses the MessageProducer's default delivery mode, priority,
and time to live.

Typically, a message producer is assigned a destination at creation
time; however, the JMS API also supports unidentified message producers,
which require that the destination be supplied every time a message is
sent.

Parameters:

destination - the destination to send this message to

message - the message to send

Throws:

JMSException - if the JMS provider fails to send the message
due to some internal error.

MessageFormatException - if an invalid message is specified.

InvalidDestinationException - if a client uses
this method with an invalid destination.

java.lang.UnsupportedOperationException - if a client uses this
method with a MessageProducer that
specified a destination at creation time.

send

Sends a message to a destination for an unidentified message producer,
specifying delivery mode, priority and time to live.

Typically, a message producer is assigned a destination at creation
time; however, the JMS API also supports unidentified message producers,
which require that the destination be supplied every time a message is
sent.

Parameters:

destination - the destination to send this message to

message - the message to send

deliveryMode - the delivery mode to use

priority - the priority for this message

timeToLive - the message's lifetime (in milliseconds)

Throws:

JMSException - if the JMS provider fails to send the message
due to some internal error.

MessageFormatException - if an invalid message is specified.

InvalidDestinationException - if a client uses
this method with an invalid destination.