| SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
| Constructor Summary | |
MessageProducer()
A client uses a MessageProducer object to send messages to a
destination.
|
|
| Method Summary | |
void
|
close()
Closes the message producer. |
Number
|
getDeliveryMode()
Gets the producer's default delivery mode. |
Destination
|
getDestination()
Gets the destination associated with this MessageProducer.
|
boolean
|
getDisableMessageID()
Gets an indication of whether message IDs are disabled. |
boolean
|
getDisableMessageTimestamp()
Gets an indication of whether message timestamps are disabled. |
Number
|
getPriority()
Gets the producer's default priority. |
Number
|
getTimeToLive()
Gets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system. |
VoidFuture
|
send(destination, message, deliveryMode, priority, timeToLive, callback)
Sends a message to a destination for an "unidentified" message producer, specifying the destination in the send method directly, as well as delivery mode, priority and time to live. |
void
|
setDeliveryMode(deliveryMode)
Sets the producer's default delivery mode. |
void
|
setDisableMessageID(value)
Sets whether message IDs are disabled. |
void
|
setDisableMessageTimestamp(value)
Sets whether message timestamps are disabled. |
void
|
setPriority(defaultPriority)
Sets the producer's default priority. |
void
|
setTimeToLive(timeToLive)
Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system. |
| Constructor Detail |
MessageProducer()
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.
| Method Detail |
void close()
Since a provider may allocate some resources on behalf of a
MessageProducer, clients should close them when they
are not needed.
void
JMSException if the JMS provider fails to close the producer
due to some internal error.
Number getDeliveryMode()
Number the message delivery mode for this message producer
JMSException if the JMS provider fails to get the delivery
mode due to some internal error.
Destination getDestination()
MessageProducer.
Destination this producer's Destination/
JMSException if the JMS provider fails to get the destination for
this MessageProducer
due to some internal error.
boolean getDisableMessageID()
boolean an indication of whether message IDs are disabled
JMSException if the JMS provider fails to determine if
message IDs are disabled due to some internal
error.
boolean getDisableMessageTimestamp()
boolean an indication of whether message timestamps are disabled
JMSException if the JMS provider fails to determine if
timestamps are disabled due to some internal
error.
Number getPriority()
Number the message priority for this message producer
JMSException if the JMS provider fails to get the priority
due to some internal error.
Number getTimeToLive()
Number the message time to live in milliseconds; zero is unlimited
JMSException if the JMS provider fails to get the time to
live due to some internal error.
VoidFuture send(destination, message, deliveryMode, priority, timeToLive, callback)
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. If the optional destination parameter is not supplied or its value
is null then the producer's default destination is used.
This is an asynchronous call. The call returns immediately, but the
operation continues until the message has been sent by the connected Gateway.
The optional callback passed to send is called
when the message is finally confirmed as sent. Note that even though this is
an asyncrhonous call, invoking this function again while a prior call to
send is still not complete will result in IllegalStateException.
Use the callback function with send to fetch outbound messages off
a queue so that only one outbound message is being sent at a time.
Note that deliveryMode, priority, and timeToLive parameters must either all be present or none.
destination - the destination to send this message to (optional)
message - the message to send
deliveryMode - the delivery mode to use (optional)
priority - the priority for this message (optional)
timeToLive - the message's lifetime (in milliseconds) (optional)
callback - called when the operation has completed or thrown an exception
VoidFuture
JMSException if the JMS provider fails to send the message
due to some internal error.
MessageFormatException if an invalid message is specified.
IllegalStateException while a message send is in progress, if
an application tries to invoke this
function again
InvalidDestinationException if a client uses
this method with an invalid destination.
void setDeliveryMode(deliveryMode)
Delivery mode is set to PERSISTENT by default.
deliveryMode - the message delivery mode for this message
producer; legal values are DeliveryMode.NON_PERSISTENT
and DeliveryMode.PERSISTENT
void
JMSException if the JMS provider fails to set the delivery
mode due to some internal error.
void setDisableMessageID(value)
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.
value - indicates if message IDs are disabled
void
JMSException if the JMS provider fails to set message ID to
disabled due to some internal error.
void setDisableMessageTimestamp(value)
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.
value - indicates if message timestamps are disabled
void
JMSException if the JMS provider fails to set timestamps to
disabled due to some internal error.
void setPriority(defaultPriority)
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.
Number defaultPriority - the message priority for this message producer;
must be a value between 0 and 9
void
JMSException if the JMS provider fails to set the priority
due to some internal error.
void setTimeToLive(timeToLive)
Time to live is set to zero by default.
timeToLive - the message time to live in milliseconds; zero is
unlimited
void
JMSException if the JMS provider fails to set the time to
live due to some internal error.