public class ActiveMQMessageProducer extends Object implements MessageProducer, QueueSender, TopicPublisher
Modifier | Constructor and Description |
---|---|
protected |
ActiveMQMessageProducer(ActiveMQConnection connection,
ClientProducer producer,
ActiveMQDestination defaultDestination,
ClientSession clientSession,
ConnectionFactoryOptions options) |
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes the message producer.
|
long |
getDeliveryDelay()
Gets the minimum length of time in milliseconds that must elapse after a
message is sent before the JMS provider may deliver the message to a
consumer.
|
int |
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.
|
int |
getPriority()
Gets the producer's default priority.
|
Queue |
getQueue()
Gets the queue associated with this
QueueSender . |
long |
getTimeToLive()
Gets the default length of time in milliseconds from its dispatch time
that a produced message should be retained by the message system.
|
Topic |
getTopic()
Gets the topic associated with this
TopicPublisher . |
void |
publish(Message message)
Publishes a message to the topic.
|
void |
publish(Message message,
int deliveryMode,
int priority,
long timeToLive)
Publishes a message to the topic, specifying delivery mode,
priority, and time to live.
|
void |
publish(Topic topic,
Message message)
Publishes a message to a topic for an unidentified message producer.
|
void |
publish(Topic topic,
Message message,
int deliveryMode,
int priority,
long timeToLive)
Publishes a message to a topic for an unidentified message
producer, specifying delivery mode, priority and time to live.
|
void |
send(Destination destination,
Message message)
Sends a message to a destination for an unidentified message producer
using the
MessageProducer 's default delivery mode, priority,
and time to live. |
void |
send(Destination destination,
Message message,
CompletionListener completionListener)
Sends a message to a destination for an unidentified message producer,
using the
MessageProducer 's default delivery mode, priority,
and time to live, performing part of the work involved in sending the
message in a separate thread and notifying the specified
CompletionListener when the operation has completed. |
void |
send(Destination destination,
Message message,
int deliveryMode,
int priority,
long timeToLive)
Sends a message to a destination for an unidentified message producer,
specifying delivery mode, priority and time to live.
|
void |
send(Destination destination,
Message message,
int deliveryMode,
int priority,
long timeToLive,
CompletionListener completionListener)
Sends a message to a destination for an unidentified message producer,
specifying delivery mode, priority and time to live, performing part of
the work involved in sending the message in a separate thread and
notifying the specified CompletionListener when the operation
has completed.
|
void |
send(Message message)
Sends a message using the
MessageProducer 's default delivery
mode, priority, and time to live. |
void |
send(Message message,
CompletionListener completionListener)
Sends a message using the
MessageProducer 's default delivery
mode, priority, and time to live, performing part of the work involved in
sending the message in a separate thread and notifying the specified
CompletionListener when the operation has completed. |
void |
send(Message message,
int deliveryMode,
int priority,
long timeToLive)
Sends a message, specifying delivery mode, priority, and time to live.
|
void |
send(Message message,
int deliveryMode,
int priority,
long timeToLive,
CompletionListener completionListener)
Sends a message, specifying delivery mode, priority and time to live,
performing part of the work involved in sending the message in a separate
thread and notifying the specified CompletionListener when the
operation has completed.
|
void |
send(Queue queue,
Message message)
Sends a message to a queue for an unidentified message producer.
|
void |
send(Queue queue,
Message message,
int deliveryMode,
int priority,
long timeToLive)
Sends a message to a queue for an unidentified message producer,
specifying delivery mode, priority and time to live.
|
void |
setDeliveryDelay(long deliveryDelay)
Sets the minimum length of time in milliseconds that must elapse after a
message is sent before the JMS provider may deliver the message to a
consumer.
|
void |
setDeliveryMode(int deliveryMode)
Sets the producer's default delivery mode.
|
void |
setDisableMessageID(boolean value)
Specify whether message IDs may be disabled.
|
void |
setDisableMessageTimestamp(boolean value)
Specify whether message timestamps may be disabled.
|
void |
setPriority(int defaultPriority)
Sets the producer's default priority.
|
void |
setTimeToLive(long timeToLive)
Sets the default length of time in milliseconds from its dispatch time
that a produced message should be retained by the message system.
|
String |
toString() |
protected ActiveMQMessageProducer(ActiveMQConnection connection, ClientProducer producer, ActiveMQDestination defaultDestination, ClientSession clientSession, ConnectionFactoryOptions options) throws JMSException
JMSException
public void setDisableMessageID(boolean value) throws JMSException
MessageProducer
Since message IDs take some effort to create and increase a message's
size, some JMS providers may be able to optimise message overhead if they
are given a hint that the message ID is not used by an application. By
calling this method, a JMS application enables this potential optimisation for all
messages sent using this MessageProducer
. 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.
setDisableMessageID
in interface MessageProducer
value
- indicates if message IDs may be disabledJMSException
- if the JMS provider fails to set message ID to disabled
due to some internal error.public boolean getDisableMessageID() throws JMSException
MessageProducer
getDisableMessageID
in interface MessageProducer
JMSException
- if the JMS provider fails to determine if message IDs are
disabled due to some internal error.public void setDisableMessageTimestamp(boolean value) throws JMSException
MessageProducer
Since timestamps take some effort to create and increase a message's
size, some JMS providers may be able to optimise message overhead if they
are given a hint that the timestamp is not used by an application. By
calling this method, a JMS application enables this potential optimisation for
all messages sent using this MessageProducer
. 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.
setDisableMessageTimestamp
in interface MessageProducer
value
- indicates whether message timestamps may be disabledJMSException
- if the JMS provider fails to set timestamps to disabled
due to some internal error.public boolean getDisableMessageTimestamp() throws JMSException
MessageProducer
getDisableMessageTimestamp
in interface MessageProducer
JMSException
- if the JMS provider fails to determine if timestamps are
disabled due to some internal error.public void setDeliveryMode(int deliveryMode) throws JMSException
MessageProducer
Delivery mode is set to PERSISTENT
by default.
setDeliveryMode
in interface MessageProducer
deliveryMode
- the message delivery mode for this message producer; legal
values are DeliveryMode.NON_PERSISTENT
and
DeliveryMode.PERSISTENT
JMSException
- if the JMS provider fails to set the delivery mode due to
some internal error.MessageProducer.getDeliveryMode()
,
DeliveryMode.NON_PERSISTENT
,
DeliveryMode.PERSISTENT
,
Message.DEFAULT_DELIVERY_MODE
public int getDeliveryMode() throws JMSException
MessageProducer
getDeliveryMode
in interface MessageProducer
JMSException
- if the JMS provider fails to get the delivery mode due to
some internal error.MessageProducer.setDeliveryMode(int)
public void setPriority(int defaultPriority) throws JMSException
MessageProducer
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.
setPriority
in interface MessageProducer
defaultPriority
- the message priority for this message producer; must be a
value between 0 and 9JMSException
- if the JMS provider fails to set the priority due to some
internal error.MessageProducer.getPriority()
,
Message.DEFAULT_PRIORITY
public int getPriority() throws JMSException
MessageProducer
getPriority
in interface MessageProducer
JMSException
- if the JMS provider fails to get the priority due to some
internal error.MessageProducer.setPriority(int)
public void setTimeToLive(long timeToLive) throws JMSException
MessageProducer
Time to live is set to zero by default.
setTimeToLive
in interface MessageProducer
timeToLive
- the message time to live in milliseconds; zero is unlimitedJMSException
- if the JMS provider fails to set the time to live due to
some internal error.MessageProducer.getTimeToLive()
,
Message.DEFAULT_TIME_TO_LIVE
public long getTimeToLive() throws JMSException
MessageProducer
getTimeToLive
in interface MessageProducer
JMSException
- if the JMS provider fails to get the time to live due to
some internal error.MessageProducer.setTimeToLive(long)
public Destination getDestination() throws JMSException
MessageProducer
MessageProducer
.getDestination
in interface MessageProducer
Destination
JMSException
- if the JMS provider fails to get the destination for this
MessageProducer
due to some internal error.public void close() throws JMSException
MessageProducer
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.
This method must not return until any incomplete asynchronous send operations for this MessageProducer have been completed and any CompletionListener callbacks have returned. Incomplete sends should be allowed to complete normally unless an error occurs.
A CompletionListener callback method must not call close on its own MessageProducer. Doing so will cause an IllegalStateException to be thrown.
close
in interface AutoCloseable
close
in interface MessageProducer
IllegalStateException
- this method has
been called by a CompletionListener callback
method on its own MessageProducerJMSException
- if the JMS provider fails to close the producer due to
some internal error.public void send(Message message) throws JMSException
MessageProducer
MessageProducer
's default delivery
mode, priority, and time to live.send
in interface MessageProducer
send
in interface QueueSender
message
- the message to sendJMSException
- 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 a
MessageProducer
with an invalid destination.Session.createProducer(javax.jms.Destination)
public void send(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
MessageProducer
send
in interface MessageProducer
send
in interface QueueSender
message
- the message to senddeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)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 a
MessageProducer
with an invalid destination.Session.createProducer(javax.jms.Destination)
public void send(Destination destination, Message message) throws JMSException
MessageProducer
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.
send
in interface MessageProducer
destination
- the destination to send this message tomessage
- the message to sendJMSException
- 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.Session.createProducer(javax.jms.Destination)
public void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
MessageProducer
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.
send
in interface MessageProducer
destination
- the destination to send this message tomessage
- the message to senddeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)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.Session.createProducer(javax.jms.Destination)
public void setDeliveryDelay(long deliveryDelay) throws JMSException
MessageProducer
For transacted sends, this time starts when the client sends the message, not when the transaction is committed.
deliveryDelay is set to zero by default.
setDeliveryDelay
in interface MessageProducer
deliveryDelay
- the delivery delay in milliseconds.JMSException
- if the JMS provider fails to set the delivery delay due to
some internal error.MessageProducer.getDeliveryDelay()
,
Message.DEFAULT_DELIVERY_DELAY
public long getDeliveryDelay() throws JMSException
MessageProducer
getDeliveryDelay
in interface MessageProducer
JMSException
- if the JMS provider fails to get the delivery delay due to
some internal error.MessageProducer.setDeliveryDelay(long)
public void send(Message message, CompletionListener completionListener) throws JMSException
MessageProducer
MessageProducer
's default delivery
mode, priority, and time to live, performing part of the work involved in
sending the message in a separate thread and notifying the specified
CompletionListener when the operation has completed. JMS refers
to this as an "asynchronous send".
When the message has been successfully sent the JMS provider invokes the callback method onCompletion on an application-specified CompletionListener object. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing.
The following information is intended to give an indication of how an asynchronous send would typically be implemented.
In some JMS providers, a normal synchronous send involves sending the message to a remote JMS server and then waiting for an acknowledgement to be received before returning. It is expected that such a provider would implement an asynchronous send by sending the message to the remote JMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the JMS provider would notify the application by invoking the onCompletion method on the application-specified CompletionListener object. If for some reason the acknowledgement is not received the JMS provider would notify the application by invoking the CompletionListener's onException method.
In those cases where the JMS specification permits a lower level of reliability, a normal synchronous send might not wait for an acknowledgement. In that case it is expected that an asynchronous send would be similar to a synchronous send: the JMS provider would send the message to the remote JMS server and then return without waiting for an acknowledgement. However the JMS provider would still notify the application that the send had completed by invoking the onCompletion method on the application-specified CompletionListener object.
It is up to the JMS provider to decide exactly what is performed in the calling thread and what, if anything, is performed asynchronously, so long as it satisfies the requirements given below:
Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the CompletionListener's onCompletion method. The CompletionListener must not be invoked earlier than this.
Exceptions: If an exception is encountered during the call to the send method then an appropriate exception should be thrown in the thread that is calling the send method. In this case the JMS provider must not invoke the CompletionListener's onCompletion or onException method. If an exception is encountered which cannot be thrown in the thread that is calling the send method then the JMS provider must call the CompletionListener's onException method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.
Message order: If the same MessageProducer is used to send multiple messages then JMS message ordering requirements must be satisfied. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.
Close, commit or rollback: If the close method is called
on the MessageProducer or its Session or
Connection then the JMS provider must block until any incomplete
send operations have been completed and all
CompletionListener
callbacks have returned before closing
the object and returning. If the session is transacted (uses a local
transaction) then when the Session's commit or
rollback method is called the JMS provider must block until any
incomplete send operations have been completed and all
CompletionListener
callbacks have returned before performing
the commit or rollback. Incomplete sends should be allowed to complete
normally unless an error occurs.
A CompletionListener callback method must not call close on its own Connection, Session or MessageProducer or call commit or rollback on its own Session. Doing so will cause the close, commit or rollback to throw an IllegalStateException.
Restrictions on usage in Java EE This method must not be used in a
Java EE EJB or web container. Doing so may cause a JMSException
to be thrown though this is not guaranteed.
Message headers JMS defines a number of message header fields and message properties which must be set by the "JMS provider on send". If the send is asynchronous these fields and properties may be accessed on the sending client only after the CompletionListener has been invoked. If the CompletionListener's onException method is called then the state of these message header fields and properties is undefined.
Restrictions on threading: Applications that perform an asynchronous send must confirm to the threading restrictions defined in JMS. This means that the session may be used by only one thread at a time.
Setting a CompletionListener does not cause the session to be dedicated to the thread of control which calls the CompletionListener. The application thread may therefore continue to use the session after performing an asynchronous send. However the CompletionListener's callback methods must not use the session if an application thread might be using the session at the same time.
Use of the CompletionListener by the JMS provider: A
session will only invoke one CompletionListener callback method
at a time. For a given MessageProducer, callbacks (both
onCompletion
and onException
) will be performed
in the same order as the corresponding calls to the asynchronous send
method.
A JMS provider must not invoke the CompletionListener from the
thread that is calling the asynchronous send method.
Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a Message object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.
After the send method has returned, the application must not attempt to read the headers, properties or body of the Message object until the CompletionListener's onCompletion or onException method has been called. This is because the JMS provider may be modifying the Message object in another thread during this time. The JMS provider may throw an JMSException if the application attempts to access or modify the Message object after the send method has returned and before the CompletionListener has been invoked. If the JMS provider does not throw an exception then the behaviour is undefined.
send
in interface MessageProducer
message
- the message to sendcompletionListener
- a CompletionListener
to be notified when the send
has completedJMSException
- if an internal error occursMessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method with a
MessageProducer
with an invalid destination.Session.createProducer(javax.jms.Destination)
,
CompletionListener
public void send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener) throws JMSException
MessageProducer
When the message has been successfully sent the JMS provider invokes the callback method onCompletion on an application-specified CompletionListener object. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing.
The following information is intended to give an indication of how an asynchronous send would typically be implemented.
In some JMS providers, a normal synchronous send involves sending the message to a remote JMS server and then waiting for an acknowledgement to be received before returning. It is expected that such a provider would implement an asynchronous send by sending the message to the remote JMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the JMS provider would notify the application by invoking the onCompletion method on the application-specified CompletionListener object. If for some reason the acknowledgement is not received the JMS provider would notify the application by invoking the CompletionListener's onException method.
In those cases where the JMS specification permits a lower level of reliability, a normal synchronous send might not wait for an acknowledgement. In that case it is expected that an asynchronous send would be similar to a synchronous send: the JMS provider would send the message to the remote JMS server and then return without waiting for an acknowledgement. However the JMS provider would still notify the application that the send had completed by invoking the onCompletion method on the application-specified CompletionListener object.
It is up to the JMS provider to decide exactly what is performed in the calling thread and what, if anything, is performed asynchronously, so long as it satisfies the requirements given below:
Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the CompletionListener's onCompletion method. The CompletionListener must not be invoked earlier than this.
Exceptions: If an exception is encountered during the call to the send method then an appropriate exception should be thrown in the thread that is calling the send method. In this case the JMS provider must not invoke the CompletionListener's onCompletion or onException method. If an exception is encountered which cannot be thrown in the thread that is calling the send method then the JMS provider must call the CompletionListener's onException method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.
Message order: If the same MessageProducer is used to send multiple messages then JMS message ordering requirements must be satisfied. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.
Close, commit or rollback: If the close method is called
on the MessageProducer or its Session or
Connection then the JMS provider must block until any incomplete
send operations have been completed and all
CompletionListener
callbacks have returned before closing
the object and returning. If the session is transacted (uses a local
transaction) then when the Session's commit or
rollback method is called the JMS provider must block until any
incomplete send operations have been completed and all
CompletionListener
callbacks have returned before performing
the commit or rollback. Incomplete sends should be allowed to complete
normally unless an error occurs.
A CompletionListener callback method must not call close on its own Connection, Session or MessageProducer or call commit or rollback on its own Session. Doing so will cause the close, commit or rollback to throw an IllegalStateException.
Restrictions on usage in Java EE This method must not be used in a
Java EE EJB or web container. Doing so may cause a JMSException
to be thrown though this is not guaranteed.
Message headers JMS defines a number of message header fields and message properties which must be set by the "JMS provider on send". If the send is asynchronous these fields and properties may be accessed on the sending client only after the CompletionListener has been invoked. If the CompletionListener's onException method is called then the state of these message header fields and properties is undefined.
Restrictions on threading: Applications that perform an asynchronous send must confirm to the threading restrictions defined in JMS. This means that the session may be used by only one thread at a time.
Setting a CompletionListener does not cause the session to be dedicated to the thread of control which calls the CompletionListener. The application thread may therefore continue to use the session after performing an asynchronous send. However the CompletionListener's callback methods must not use the session if an application thread might be using the session at the same time.
Use of the CompletionListener by the JMS provider: A
session will only invoke one CompletionListener callback method
at a time. For a given MessageProducer, callbacks (both
onCompletion
and onException
) will be performed
in the same order as the corresponding calls to the asynchronous send
method.
A JMS provider must not invoke the CompletionListener from the
thread that is calling the asynchronous send method.
Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a Message object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.
After the send method has returned, the application must not attempt to read the headers, properties or body of the Message object until the CompletionListener's onCompletion or onException method has been called. This is because the JMS provider may be modifying the Message object in another thread during this time. The JMS provider may throw an JMSException if the application attempts to access or modify the Message object after the send method has returned and before the CompletionListener has been invoked. If the JMS provider does not throw an exception then the behaviour is undefined.
send
in interface MessageProducer
message
- the message to senddeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)completionListener
- a CompletionListener
to be notified when the send
has completedJMSException
- if an internal error occursMessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method with a
MessageProducer
with an invalid destination.Session.createProducer(javax.jms.Destination)
,
CompletionListener
public void send(Destination destination, Message message, CompletionListener completionListener) throws JMSException
MessageProducer
MessageProducer
's default delivery mode, priority,
and time to live, performing part of the work involved in sending the
message in a separate thread and notifying the specified
CompletionListener when the operation has completed. JMS refers
to this as an "asynchronous send".
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.
When the message has been successfully sent the JMS provider invokes the callback method onCompletion on an application-specified CompletionListener object. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing.
The following information is intended to give an indication of how an asynchronous send would typically be implemented.
In some JMS providers, a normal synchronous send involves sending the message to a remote JMS server and then waiting for an acknowledgement to be received before returning. It is expected that such a provider would implement an asynchronous send by sending the message to the remote JMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the JMS provider would notify the application by invoking the onCompletion method on the application-specified CompletionListener object. If for some reason the acknowledgement is not received the JMS provider would notify the application by invoking the CompletionListener's onException method.
In those cases where the JMS specification permits a lower level of reliability, a normal synchronous send might not wait for an acknowledgement. In that case it is expected that an asynchronous send would be similar to a synchronous send: the JMS provider would send the message to the remote JMS server and then return without waiting for an acknowledgement. However the JMS provider would still notify the application that the send had completed by invoking the onCompletion method on the application-specified CompletionListener object.
It is up to the JMS provider to decide exactly what is performed in the calling thread and what, if anything, is performed asynchronously, so long as it satisfies the requirements given below:
Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the CompletionListener's onCompletion method. The CompletionListener must not be invoked earlier than this.
Exceptions: If an exception is encountered during the call to the send method then an appropriate exception should be thrown in the thread that is calling the send method. In this case the JMS provider must not invoke the CompletionListener's onCompletion or onException method. If an exception is encountered which cannot be thrown in the thread that is calling the send method then the JMS provider must call the CompletionListener's onException method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.
Message order: If the same MessageProducer is used to send multiple messages then JMS message ordering requirements must be satisfied. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.
Close, commit or rollback: If the close method is called
on the MessageProducer or its Session or
Connection then the JMS provider must block until any incomplete
send operations have been completed and all
CompletionListener
callbacks have returned before closing
the object and returning. If the session is transacted (uses a local
transaction) then when the Session's commit or
rollback method is called the JMS provider must block until any
incomplete send operations have been completed and all
CompletionListener
callbacks have returned before performing
the commit or rollback. Incomplete sends should be allowed to complete
normally unless an error occurs.
A CompletionListener callback method must not call close on its own Connection, Session or MessageProducer or call commit or rollback on its own Session. Doing so will cause the close, commit or rollback to throw an IllegalStateException.
Restrictions on usage in Java EE This method must not be used in a
Java EE EJB or web container. Doing so may cause a JMSException
to be thrown though this is not guaranteed.
Message headers JMS defines a number of message header fields and message properties which must be set by the "JMS provider on send". If the send is asynchronous these fields and properties may be accessed on the sending client only after the CompletionListener has been invoked. If the CompletionListener's onException method is called then the state of these message header fields and properties is undefined.
Restrictions on threading: Applications that perform an asynchronous send must confirm to the threading restrictions defined in JMS. This means that the session may be used by only one thread at a time.
Setting a CompletionListener does not cause the session to be dedicated to the thread of control which calls the CompletionListener. The application thread may therefore continue to use the session after performing an asynchronous send. However the CompletionListener's callback methods must not use the session if an application thread might be using the session at the same time.
Use of the CompletionListener by the JMS provider: A
session will only invoke one CompletionListener callback method
at a time. For a given MessageProducer, callbacks (both
onCompletion
and onException
) will be performed
in the same order as the corresponding calls to the asynchronous send
method. A JMS provider must not invoke the CompletionListener
from the thread that is calling the asynchronous send method.
Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a Message object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.
After the send method has returned, the application must not attempt to read the headers, properties or body of the Message object until the CompletionListener's onCompletion or onException method has been called. This is because the JMS provider may be modifying the Message object in another thread during this time. The JMS provider may throw an JMSException if the application attempts to access or modify the Message object after the send method has returned and before the CompletionListener has been invoked. If the JMS provider does not throw an exception then the behaviour is undefined.
send
in interface MessageProducer
destination
- the destination to send this message tomessage
- the message to sendcompletionListener
- a CompletionListener
to be notified when the send
has completedJMSException
- if an internal error occursMessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method with an invalid destinationSession.createProducer(javax.jms.Destination)
,
CompletionListener
public void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener) throws JMSException
MessageProducer
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.
When the message has been successfully sent the JMS provider invokes the callback method onCompletion on an application-specified CompletionListener object. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing.
The following information is intended to give an indication of how an asynchronous send would typically be implemented.
In some JMS providers, a normal synchronous send involves sending the message to a remote JMS server and then waiting for an acknowledgement to be received before returning. It is expected that such a provider would implement an asynchronous send by sending the message to the remote JMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the JMS provider would notify the application by invoking the onCompletion method on the application-specified CompletionListener object. If for some reason the acknowledgement is not received the JMS provider would notify the application by invoking the CompletionListener's onException method.
In those cases where the JMS specification permits a lower level of reliability, a normal synchronous send might not wait for an acknowledgement. In that case it is expected that an asynchronous send would be similar to a synchronous send: the JMS provider would send the message to the remote JMS server and then return without waiting for an acknowledgement. However the JMS provider would still notify the application that the send had completed by invoking the onCompletion method on the application-specified CompletionListener object.
It is up to the JMS provider to decide exactly what is performed in the calling thread and what, if anything, is performed asynchronously, so long as it satisfies the requirements given below:
Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the CompletionListener's onCompletion method. The CompletionListener must not be invoked earlier than this.
Exceptions: If an exception is encountered during the call to the send method then an appropriate exception should be thrown in the thread that is calling the send method. In this case the JMS provider must not invoke the CompletionListener's onCompletion or onException method. If an exception is encountered which cannot be thrown in the thread that is calling the send method then the JMS provider must call the CompletionListener's onException method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.
Message order: If the same MessageProducer is used to send multiple messages then JMS message ordering requirements must be satisfied. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.
Close, commit or rollback: If the close method is called
on the MessageProducer or its Session or
Connection then the JMS provider must block until any incomplete
send operations have been completed and all
CompletionListener
callbacks have returned before closing
the object and returning. If the session is transacted (uses a local
transaction) then when the Session's commit or
rollback method is called the JMS provider must block until any
incomplete send operations have been completed and all
CompletionListener
callbacks have returned before performing
the commit or rollback. Incomplete sends should be allowed to complete
normally unless an error occurs.
A CompletionListener callback method must not call close on its own Connection, Session or MessageProducer or call commit or rollback on its own Session. Doing so will cause the close, commit or rollback to throw an IllegalStateException.
Restrictions on usage in Java EE This method must not be used in a
Java EE EJB or web container. Doing so may cause a JMSException
to be thrown though this is not guaranteed.
Message headers JMS defines a number of message header fields and message properties which must be set by the "JMS provider on send". If the send is asynchronous these fields and properties may be accessed on the sending client only after the CompletionListener has been invoked. If the CompletionListener's onException method is called then the state of these message header fields and properties is undefined.
Restrictions on threading: Applications that perform an asynchronous send must confirm to the threading restrictions defined in JMS. This means that the session may be used by only one thread at a time.
Setting a CompletionListener does not cause the session to be dedicated to the thread of control which calls the CompletionListener. The application thread may therefore continue to use the session after performing an asynchronous send. However the CompletionListener's callback methods must not use the session if an application thread might be using the session at the same time.
Use of the CompletionListener by the JMS provider: A
session will only invoke one CompletionListener callback method
at a time. For a given MessageProducer, callbacks (both
onCompletion
and onException
) will be performed
in the same order as the corresponding calls to the asynchronous send
method.
A JMS provider must not invoke the CompletionListener from the
thread that is calling the asynchronous send method.
Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a Message object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.
After the send method has returned, the application must not attempt to read the headers, properties or body of the Message object until the CompletionListener's onCompletion or onException method has been called. This is because the JMS provider may be modifying the Message object in another thread during this time. The JMS provider may throw an JMSException if the application attempts to access or modify the Message object after the send method has returned and before the CompletionListener has been invoked. If the JMS provider does not throw an exception then the behaviour is undefined.
send
in interface MessageProducer
destination
- the destination to send this message tomessage
- the message to senddeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)completionListener
- a CompletionListener
to be notified when the send
has completedJMSException
- if an internal error occursMessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method with an invalid destination.Session.createProducer(javax.jms.Destination)
,
CompletionListener
public Topic getTopic() throws JMSException
TopicPublisher
TopicPublisher
.getTopic
in interface TopicPublisher
JMSException
- if the JMS provider fails to get the topic for
this TopicPublisher
due to some internal error.public void publish(Message message) throws JMSException
TopicPublisher
TopicPublisher
's default delivery mode, priority,
and time to live.publish
in interface TopicPublisher
message
- the message to publishJMSException
- if the JMS provider fails to publish the message
due to some internal error.MessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method
with a TopicPublisher
with
an invalid topic.MessageProducer.getDeliveryMode()
,
MessageProducer.getTimeToLive()
,
MessageProducer.getPriority()
public void publish(Topic topic, Message message) throws JMSException
TopicPublisher
TopicPublisher
's default delivery mode,
priority, and time to live.
Typically, a message producer is assigned a topic at creation time; however, the JMS API also supports unidentified message producers, which require that the topic be supplied every time a message is published.
publish
in interface TopicPublisher
topic
- the topic to publish this message tomessage
- the message to publishJMSException
- if the JMS provider fails to publish the message
due to some internal error.MessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses
this method with an invalid topic.MessageProducer.getDeliveryMode()
,
MessageProducer.getTimeToLive()
,
MessageProducer.getPriority()
public void publish(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
TopicPublisher
publish
in interface TopicPublisher
message
- the message to publishdeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)JMSException
- if the JMS provider fails to publish the message
due to some internal error.MessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method
with a TopicPublisher
with
an invalid topic.public void publish(Topic topic, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
TopicPublisher
Typically, a message producer is assigned a topic at creation time; however, the JMS API also supports unidentified message producers, which require that the topic be supplied every time a message is published.
publish
in interface TopicPublisher
topic
- the topic to publish this message tomessage
- the message to publishdeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)JMSException
- if the JMS provider fails to publish the message
due to some internal error.MessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses
this method with an invalid topic.public void send(Queue queue, Message message) throws JMSException
QueueSender
QueueSender
's default delivery mode, priority,
and time to live.
Typically, a message producer is assigned a queue at creation time; however, the JMS API also supports unidentified message producers, which require that the queue be supplied every time a message is sent.
send
in interface QueueSender
queue
- the queue to send this message tomessage
- the message to sendJMSException
- 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 queue.MessageProducer.getDeliveryMode()
,
MessageProducer.getTimeToLive()
,
MessageProducer.getPriority()
public void send(Queue queue, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
QueueSender
Typically, a message producer is assigned a queue at creation time; however, the JMS API also supports unidentified message producers, which require that the queue be supplied every time a message is sent.
send
in interface QueueSender
queue
- the queue to send this message tomessage
- the message to senddeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)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 queue.public Queue getQueue() throws JMSException
QueueSender
QueueSender
.getQueue
in interface QueueSender
JMSException
- if the JMS provider fails to get the queue for
this QueueSender
due to some internal error.Copyright © 2019 JBoss by Red Hat. All rights reserved.