-
public interface JMSProducer
AJMSProducer
is a simple object used to send messages on behalf of aJMSContext
. An instance ofJMSProducer
is created by calling thecreateProducer
method on aJMSContext
. It provides varioussend
methods to send a message to a specified destination. It also provides methods to allow message send options, message properties and message headers to be specified prior to sending a message or set of messages.Message send options may be specified using one or more of the following methods:
setDeliveryMode
,setPriority
,setTimeToLive
,setDeliveryDelay
,setDisableMessageTimestamp
,setDisableMessageID
andsetAsync
.Message properties may be may be specified using one or more of nine
setProperty
methods. Any message properties set using these methods will override any message properties that have been set directly on the message.Message headers may be specified using one or more of the following methods:
setJMSCorrelationID
,setJMSCorrelationIDAsBytes
,setJMSType
orsetJMSReplyTo
. Any message headers set using these methods will override any message headers that have been set directly on the message.All the above methods return the
JMSProducer
to allow method calls to be chained together, allowing a fluid programming style. For example:context.createProducer().setDeliveryMode(DeliveryMode.NON_PERSISTENT).setTimeToLive(1000).send(destination, message);
Instances of
JMSProducer
are intended to be lightweight objects which can be created freely and which do not consume significant resources. This interface therefore does not provide aclose
method.- Since:
- JMS 2.0
- Version:
- Jakarta Messaging 2.0
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description JMSProducer
clearProperties()
Clears any message properties set on thisJMSProducer
CompletionListener
getAsync()
If subsequent calls tosend
on thisJMSProducer
object have been configured to be asynchronous then this method returns theCompletionListener
that has previously been configured.boolean
getBooleanProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to aboolean
.byte
getByteProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to aString
.long
getDeliveryDelay()
Gets the minimum length of time in milliseconds that must elapse after a message is sent before the Jakarta Messaging provider may deliver the message to a consumer.int
getDeliveryMode()
Returns the delivery mode of messages that are sent using thisJMSProducer
boolean
getDisableMessageID()
Gets an indication of whether message IDs are disabled.boolean
getDisableMessageTimestamp()
Gets an indication of whether message timestamps are disabled.double
getDoubleProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to adouble
.float
getFloatProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to afloat
.int
getIntProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to aint
.String
getJMSCorrelationID()
Returns theJMSCorrelationID
header value that has been set on thisJMSProducer
, as aString
.byte[]
getJMSCorrelationIDAsBytes()
Returns theJMSCorrelationID
header value that has been set on thisJMSProducer
, as an array of bytes.Destination
getJMSReplyTo()
Returns theJMSReplyTo
header value that has been set on thisJMSProducer
.String
getJMSType()
Returns theJMSType
header value that has been set on thisJMSProducer
.long
getLongProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to along
.Object
getObjectProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to objectified format.int
getPriority()
Return the priority of messages that are sent using thisJMSProducer
Set<String>
getPropertyNames()
Returns an unmodifiableSet
view of the names of all the message properties that have been set on this JMSProducer.short
getShortProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to ashort
.String
getStringProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to aString
.long
getTimeToLive()
Returns the time to live of messages that are sent using thisJMSProducer
.boolean
propertyExists(String name)
Indicates whether a message property with the specified name has been set on thisJMSProducer
JMSProducer
send(Destination destination, byte[] body)
Send aBytesMessage
with the specified body to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.JMSProducer
send(Destination destination, Message message)
Sends a message to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.JMSProducer
send(Destination destination, Serializable body)
Send anObjectMessage
with the specified body to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.JMSProducer
send(Destination destination, String body)
Send aTextMessage
with the specified body to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.JMSProducer
send(Destination destination, Map<String,Object> body)
Send aMapMessage
with the specified body to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.JMSProducer
setAsync(CompletionListener completionListener)
Specifies whether subsequent calls tosend
on thisJMSProducer
object should be synchronous or asynchronous.JMSProducer
setDeliveryDelay(long deliveryDelay)
Sets the minimum length of time in milliseconds that must elapse after a message is sent before the Jakarta Messaging provider may deliver the message to a consumer.JMSProducer
setDeliveryMode(int deliveryMode)
Specifies the delivery mode of messages that are sent using thisJMSProducer
JMSProducer
setDisableMessageID(boolean value)
Specifies whether message IDs may be disabled for messages that are sent using thisJMSProducer
JMSProducer
setDisableMessageTimestamp(boolean value)
Specifies whether message timestamps may be disabled for messages that are sent using thisJMSProducer
.JMSProducer
setJMSCorrelationID(String correlationID)
Specifies that messages sent using thisJMSProducer
will have theirJMSCorrelationID
header value set to the specified correlation ID, where correlation ID is specified as aString
.JMSProducer
setJMSCorrelationIDAsBytes(byte[] correlationID)
Specifies that messages sent using thisJMSProducer
will have theirJMSCorrelationID
header value set to the specified correlation ID, where correlation ID is specified as an array of bytes.JMSProducer
setJMSReplyTo(Destination replyTo)
Specifies that messages sent using thisJMSProducer
will have theirJMSReplyTo
header value set to the specifiedDestination
object.JMSProducer
setJMSType(String type)
Specifies that messages sent using thisJMSProducer
will have theirJMSType
header value set to the specified message type.JMSProducer
setPriority(int priority)
Specifies the priority of messages that are sent using thisJMSProducer
JMSProducer
setProperty(String name, boolean value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedboolean
value.JMSProducer
setProperty(String name, byte value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedbyte
value.JMSProducer
setProperty(String name, double value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifieddouble
value.JMSProducer
setProperty(String name, float value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedfloat
value.JMSProducer
setProperty(String name, int value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedint
value.JMSProducer
setProperty(String name, long value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedlong
value.JMSProducer
setProperty(String name, short value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedshort
value.JMSProducer
setProperty(String name, Object value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specified Java object value.JMSProducer
setProperty(String name, String value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedString
value.JMSProducer
setTimeToLive(long timeToLive)
Specifies the time to live of messages that are sent using thisJMSProducer
.
-
-
-
Method Detail
-
send
JMSProducer send(Destination destination, Message message)
Sends a message to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.- Parameters:
destination
- the destination to send this message tomessage
- the message to send- Returns:
- this
JMSProducer
- Throws:
MessageFormatRuntimeException
- if an invalid message is specified.InvalidDestinationRuntimeException
- if a client uses this method with an invalid destination.MessageNotWriteableRuntimeException
- if thisJMSProducer
has been configured to set a message property, but the message's properties are read-onlyJMSRuntimeException
- if the Jakarta Messaging provider fails to send the message due to some internal error.
-
send
JMSProducer send(Destination destination, String body)
Send aTextMessage
with the specified body to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.- Parameters:
destination
- the destination to send this message tobody
- the body of theTextMessage
that will be sent. If a null value is specified then aTextMessage
with no body will be sent.- Returns:
- this
JMSProducer
- Throws:
MessageFormatRuntimeException
- if an invalid message is specified.InvalidDestinationRuntimeException
- if a client uses this method with an invalid destination.JMSRuntimeException
- if the Jakarta Messaging provider fails to send the message due to some internal error.
-
send
JMSProducer send(Destination destination, Map<String,Object> body)
Send aMapMessage
with the specified body to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.- Parameters:
destination
- the destination to send this message tobody
- the body of theMapMessage
that will be sent. If a null value is specified then aMapMessage
with no map entries will be sent.- Returns:
- this
JMSProducer
- Throws:
MessageFormatRuntimeException
- if an invalid message is specified.InvalidDestinationRuntimeException
- if a client uses this method with an invalid destination.JMSRuntimeException
- if the Jakarta Messaging provider fails to send the message due to some internal error.
-
send
JMSProducer send(Destination destination, byte[] body)
Send aBytesMessage
with the specified body to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.- Parameters:
destination
- the destination to send this message tobody
- the body of theBytesMessage
that will be sent. If a null value is specified then aBytesMessage
with no body will be sent.- Returns:
- this
JMSProducer
- Throws:
MessageFormatRuntimeException
- if an invalid message is specified.InvalidDestinationRuntimeException
- if a client uses this method with an invalid destination.JMSRuntimeException
- if the Jakarta Messaging provider fails to send the message due to some internal error.
-
send
JMSProducer send(Destination destination, Serializable body)
Send anObjectMessage
with the specified body to the specified destination, using any send options, message properties and message headers that have been defined on thisJMSProducer
.- Parameters:
destination
- the destination to send this message tobody
- the body of the ObjectMessage that will be sent. If a null value is specified then anObjectMessage
with no body will be sent.- Returns:
- this
JMSProducer
- Throws:
MessageFormatRuntimeException
- if an invalid message is specified.InvalidDestinationRuntimeException
- if a client uses this method with an invalid destination.JMSRuntimeException
- if Jakarta Messaging provider fails to send the message due to some internal error.
-
setDisableMessageID
JMSProducer setDisableMessageID(boolean value)
Specifies whether message IDs may be disabled for messages that are sent using thisJMSProducer
Since message IDs take some effort to create and increase a message's size, some Jakarta Messaging 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 Jakarta Messaging application enables this potential optimisation for all messages sent using this
JMSProducer
. If the Jakarta Messaging 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 whether message IDs may be disabled- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set message ID to disabled due to some internal error.- See Also:
getDisableMessageID()
-
getDisableMessageID
boolean getDisableMessageID()
Gets an indication of whether message IDs are disabled.- Returns:
- an indication of whether message IDs are disabled
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to determine if message IDs are disabled due to some internal error.- See Also:
setDisableMessageID(boolean)
-
setDisableMessageTimestamp
JMSProducer setDisableMessageTimestamp(boolean value)
Specifies whether message timestamps may be disabled for messages that are sent using thisJMSProducer
.Since timestamps take some effort to create and increase a message's size, some Jakarta Messaging 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 Jakarta Messaging application enables this potential optimisation for all messages sent using this
JMSProducer
. 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 whether message timestamps may be disabled- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set timestamps to disabled due to some internal error.- See Also:
getDisableMessageTimestamp()
-
getDisableMessageTimestamp
boolean getDisableMessageTimestamp()
Gets an indication of whether message timestamps are disabled.- Returns:
- an indication of whether message timestamps are disabled
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to determine if timestamps are disabled due to some internal error.- See Also:
setDisableMessageTimestamp(boolean)
-
setDeliveryMode
JMSProducer setDeliveryMode(int deliveryMode)
Specifies the delivery mode of messages that are sent using thisJMSProducer
Delivery mode is set to
PERSISTENT
by default.- Parameters:
deliveryMode
- the message delivery mode to be used; legal values areDeliveryMode.NON_PERSISTENT
andDeliveryMode.PERSISTENT
- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the delivery mode due to some internal error.- See Also:
getDeliveryMode()
,DeliveryMode.NON_PERSISTENT
,DeliveryMode.PERSISTENT
,Message.DEFAULT_DELIVERY_MODE
-
getDeliveryMode
int getDeliveryMode()
Returns the delivery mode of messages that are sent using thisJMSProducer
- Returns:
- the message delivery mode
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the delivery mode due to some internal error.- See Also:
setDeliveryMode(int)
-
setPriority
JMSProducer setPriority(int priority)
Specifies the priority of messages that are sent using thisJMSProducer
The Jakarta Messaging 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:
priority
- the message priority to be used; must be a value between 0 and 9- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the priority due to some internal error.- See Also:
getPriority()
,Message.DEFAULT_PRIORITY
-
getPriority
int getPriority()
Return the priority of messages that are sent using thisJMSProducer
- Returns:
- the message priority
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the priority due to some internal error.- See Also:
setPriority(int)
-
setTimeToLive
JMSProducer setTimeToLive(long timeToLive)
Specifies the time to live of messages that are sent using thisJMSProducer
. This is used to determine the expiration time of a message.The expiration time of a message is the sum of the message's time to live and the time it is sent. For transacted sends, this is the time the client sends the message, not the time the transaction is committed.
Clients should not receive messages that have expired; however, Jakarta Messaging does not guarantee that this will not happen.
A Jakarta Messaging provider should do its best to accurately expire messages; however, Jakarta Messaging does not define the accuracy provided. It is not acceptable to simply ignore time-to-live.
Time to live is set to zero by default, which means a message never expires.
- Parameters:
timeToLive
- the message time to live to be used, in milliseconds; a value of zero means that a message never expires.- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the time to live due to some internal error.- See Also:
getTimeToLive()
,Message.DEFAULT_TIME_TO_LIVE
-
getTimeToLive
long getTimeToLive()
Returns the time to live of messages that are sent using thisJMSProducer
.- Returns:
- the message time to live in milliseconds; a value of zero means that a message never expires.
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the time to live due to some internal error.- See Also:
setTimeToLive(long)
-
setDeliveryDelay
JMSProducer setDeliveryDelay(long deliveryDelay)
Sets the minimum length of time in milliseconds that must elapse after a message is sent before the Jakarta Messaging provider may deliver the message to a consumer.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.
- Parameters:
deliveryDelay
- the delivery delay in milliseconds.- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the delivery delay due to some internal error.- See Also:
getDeliveryDelay()
,Message.DEFAULT_DELIVERY_DELAY
-
getDeliveryDelay
long getDeliveryDelay()
Gets the minimum length of time in milliseconds that must elapse after a message is sent before the Jakarta Messaging provider may deliver the message to a consumer.- Returns:
- the delivery delay in milliseconds.
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the delivery delay due to some internal error.- See Also:
setDeliveryDelay(long)
-
setAsync
JMSProducer setAsync(CompletionListener completionListener)
Specifies whether subsequent calls tosend
on thisJMSProducer
object should be synchronous or asynchronous. If the specifiedCompletionListener
is not null then subsequent calls tosend
will be asynchronous. If the specifiedCompletionListener
is null then subsequent calls tosend
will be synchronous. Calls tosend
are synchronous by default.If a call to
send
is asynchronous then part of the work involved in sending the message will be performed in a separate thread and the specified CompletionListener will be notified when the operation has completed.When the message has been successfully sent the Jakarta Messaging provider invokes the callback method onCompletion on the 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 the send had been synchronous. 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 Jakarta Messaging providers, a normal synchronous send involves sending the message to a remote Jakarta Messaging 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 Jakarta Messaging server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the Jakarta Messaging 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 Jakarta Messaging provider would notify the application by invoking the CompletionListener's onException method.
In those cases where the Jakarta Messaging 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 Jakarta Messaging provider would send the message to the remote Jakarta Messaging server and then return without waiting for an acknowledgement. However the Jakarta Messaging 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 Jakarta Messaging 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 Jakarta Messaging 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 Jakarta Messaging 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 JMSContext is used to send multiple messages then Jakarta Messaging 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 JMSContext 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 JMSContext's commit or rollback method is called the JMS provider must block until any incomplete send operations have been completed and allCompletionListener
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, commit or rollback on its own JMSContext. Doing so will cause the close, commit or rollback to throw an IllegalStateRuntimeException.
Restrictions on usage in Jakarta EE This method must not be used in a Jakarta EE EJB or web container. Doing so may cause a
JMSRuntimeException
to be thrown though this is not guaranteed.Message headers Jakarta Messaging defines a number of message header fields and message properties which must be set by the "Jakarta Messaging 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 Jakarta Messaging provider: A session will only invoke one CompletionListener callback method at a time. For a given JMSContext, callbacks (both
onCompletion
andonException
) will be performed in the same order as the corresponding calls to the send method. A Jakarta Messaging provider must not invoke the CompletionListener from the thread that is calling the 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 Jakarta Messaging provider may be modifying the Message object in another thread during this time. The Jakarta Messaging 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 Jakarta Messaging provider does not throw an exception then the behaviour is undefined.
- Parameters:
completionListener
- If asynchronous send behaviour is required, this should be set to aCompletionListener
to be notified when the send has completed. If synchronous send behaviour is required, this should be set tonull
.- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if an internal error occurs- See Also:
getAsync()
,CompletionListener
-
getAsync
CompletionListener getAsync()
If subsequent calls tosend
on thisJMSProducer
object have been configured to be asynchronous then this method returns theCompletionListener
that has previously been configured. If subsequent calls tosend
have been configured to be synchronous then this method returnsnull
.- Returns:
- the
CompletionListener
ornull
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the required information due to some internal error.- See Also:
setAsync(jakarta.jms.CompletionListener)
-
setProperty
JMSProducer setProperty(String name, boolean value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedboolean
value.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- theboolean
value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.- See Also:
getBooleanProperty(java.lang.String)
-
setProperty
JMSProducer setProperty(String name, byte value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedbyte
value.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- thebyte
value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.- See Also:
getByteProperty(java.lang.String)
-
setProperty
JMSProducer setProperty(String name, short value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedshort
value.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- theshort
property value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.- See Also:
getShortProperty(java.lang.String)
-
setProperty
JMSProducer setProperty(String name, int value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedint
value.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- theint
property value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.- See Also:
getIntProperty(java.lang.String)
-
setProperty
JMSProducer setProperty(String name, long value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedlong
value.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- thelong
property value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.- See Also:
getLongProperty(java.lang.String)
-
setProperty
JMSProducer setProperty(String name, float value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedfloat
value.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- thefloat
property value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.- See Also:
getFloatProperty(java.lang.String)
-
setProperty
JMSProducer setProperty(String name, double value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifieddouble
value.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- thedouble
property value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.- See Also:
getDoubleProperty(java.lang.String)
-
setProperty
JMSProducer setProperty(String name, String value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specifiedString
value.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- theString
property value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.- See Also:
getStringProperty(java.lang.String)
-
setProperty
JMSProducer setProperty(String name, Object value)
Specifies that messages sent using thisJMSProducer
will have the specified property set to the specified Java object value.Note that this method works only for the objectified primitive object types (
Integer
,Double
,Long
...) andString
objects.This will replace any property of the same name that is already set on the message being sent.
- Parameters:
name
- the name of the propertyvalue
- the Java object property value to set- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the property due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageFormatRuntimeException
- if the object is invalid- See Also:
getObjectProperty(java.lang.String)
-
clearProperties
JMSProducer clearProperties()
Clears any message properties set on thisJMSProducer
- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to clear the message properties due to some internal error.
-
propertyExists
boolean propertyExists(String name)
Indicates whether a message property with the specified name has been set on thisJMSProducer
- Parameters:
name
- the name of the property- Returns:
- true whether the property exists
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to determine whether the property exists due to some internal error.
-
getBooleanProperty
boolean getBooleanProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to aboolean
.- Parameters:
name
- the name of the property- Returns:
- the property value, converted to a
boolean
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.MessageFormatRuntimeException
- if this type conversion is invalid.- See Also:
setProperty(java.lang.String,boolean)
-
getByteProperty
byte getByteProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to aString
.- Parameters:
name
- the name of the property- Returns:
- the property value, converted to a
byte
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.MessageFormatRuntimeException
- if this type conversion is invalid.- See Also:
setProperty(java.lang.String,byte)
-
getShortProperty
short getShortProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to ashort
.- Parameters:
name
- the name of the property- Returns:
- the property value, converted to a
short
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.MessageFormatRuntimeException
- if this type conversion is invalid.- See Also:
setProperty(java.lang.String,short)
-
getIntProperty
int getIntProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to aint
.- Parameters:
name
- the name of the property- Returns:
- the property value, converted to a
int
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.MessageFormatRuntimeException
- if this type conversion is invalid.- See Also:
setProperty(java.lang.String,int)
-
getLongProperty
long getLongProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to along
.- Parameters:
name
- the name of the property- Returns:
- the property value, converted to a
long
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.MessageFormatRuntimeException
- if this type conversion is invalid.- See Also:
setProperty(java.lang.String,long)
-
getFloatProperty
float getFloatProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to afloat
.- Parameters:
name
- the name of the property- Returns:
- the property value, converted to a
float
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.MessageFormatRuntimeException
- if this type conversion is invalid.- See Also:
setProperty(java.lang.String,float)
-
getDoubleProperty
double getDoubleProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to adouble
.- Parameters:
name
- the name of the property- Returns:
- the property value, converted to a
double
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.MessageFormatRuntimeException
- if this type conversion is invalid.- See Also:
setProperty(java.lang.String,double)
-
getStringProperty
String getStringProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to aString
.- Parameters:
name
- the name of the property- Returns:
- the property value, converted to a
boolean
; if there is no property by this name, a null value is returned - Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.MessageFormatRuntimeException
- if this type conversion is invalid.- See Also:
setProperty(java.lang.String,String)
-
getObjectProperty
Object getObjectProperty(String name)
Returns the message property with the specified name that has been set on thisJMSProducer
, converted to objectified format.This method can be used to return, in objectified format, an object that has been stored as a property in the message with the equivalent
setObjectProperty
method call, or its equivalent primitivesettypeProperty
method.- Parameters:
name
- the name of the property- Returns:
- the Java object property value with the specified name, in objectified format (for example, if the property
was set as an
int
, anInteger
is returned); if there is no property by this name, a null value is returned - Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property value due to some internal error.- See Also:
setProperty(java.lang.String,java.lang.Object)
-
getPropertyNames
Set<String> getPropertyNames()
Returns an unmodifiableSet
view of the names of all the message properties that have been set on this JMSProducer.Note that Jakarta Messaging standard header fields are not considered properties and are not returned in this Set.
The set is backed by the
JMSProducer
, so changes to the map are reflected in the set. However the set may not be modified. Attempts to modify the returned collection, whether directly or via its iterator, will result in anjava.lang.UnsupportedOperationException
. Its behaviour matches that defined in thejava.util.Collections
methodunmodifiableSet
.- Returns:
- a
Set
containing the names of all the message properties that have been set on thisJMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the property names due to some internal error.- See Also:
Collections.unmodifiableSet(java.util.Set<? extends T>)
-
setJMSCorrelationIDAsBytes
JMSProducer setJMSCorrelationIDAsBytes(byte[] correlationID)
Specifies that messages sent using thisJMSProducer
will have theirJMSCorrelationID
header value set to the specified correlation ID, where correlation ID is specified as an array of bytes.This will override any
JMSCorrelationID
header value that is already set on the message being sent.The array is copied before the method returns, so future modifications to the array will not alter the value in this
JMSProducer
.If a provider supports the native concept of correlation ID, a Jakarta Messaging client may need to assign specific
JMSCorrelationID
values to match those expected by native messaging clients. Jakarta Messaging providers without native correlation ID values are not required to support this method and its corresponding get method; their implementation may throw ajava.lang.UnsupportedOperationException
.The use of a
byte[]
value forJMSCorrelationID
is non-portable.- Parameters:
correlationID
- the correlation ID value as an array of bytes- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the correlation ID due to some internal error.- See Also:
setJMSCorrelationID(String)
,getJMSCorrelationID()
,getJMSCorrelationIDAsBytes()
-
getJMSCorrelationIDAsBytes
byte[] getJMSCorrelationIDAsBytes()
Returns theJMSCorrelationID
header value that has been set on thisJMSProducer
, as an array of bytes.The use of a
byte[]
value forJMSCorrelationID
is non-portable.- Returns:
- the correlation ID as an array of bytes
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the correlation ID due to some internal error.- See Also:
setJMSCorrelationID(String)
,getJMSCorrelationID()
,setJMSCorrelationIDAsBytes(byte[])
-
setJMSCorrelationID
JMSProducer setJMSCorrelationID(String correlationID)
Specifies that messages sent using thisJMSProducer
will have theirJMSCorrelationID
header value set to the specified correlation ID, where correlation ID is specified as aString
.This will override any
JMSCorrelationID
header value that is already set on the message being sent.A client can use the
JMSCorrelationID
header field to link one message with another. A typical use is to link a response message with its request message.JMSCorrelationID
can hold one of the following:- A provider-specific message ID
- An application-specific
String
- A provider-native
byte[]
value
Since each message sent by a Jakarta Messaging provider is assigned a message ID value, it is convenient to link messages via message ID. All message ID values must start with the
'ID:'
prefix.In some cases, an application (made up of several clients) needs to use an application-specific value for linking messages. For instance, an application may use
JMSCorrelationID
to hold a value referencing some external information. Application-specified values must not start with the'ID:'
prefix; this is reserved for provider-generated message ID values.If a provider supports the native concept of correlation ID, a Jakarta Messaging client may need to assign specific
JMSCorrelationID
values to match those expected by clients that do not use the Jakarta Messaging API. Abyte[]
value is used for this purpose. Jakarta Messaging providers without native correlation ID values are not required to supportbyte[]
values. The use of abyte[]
value forJMSCorrelationID
is non-portable.- Parameters:
correlationID
- the message ID of a message being referred to- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the correlation ID due to some internal error.- See Also:
getJMSCorrelationID()
,getJMSCorrelationIDAsBytes()
,setJMSCorrelationIDAsBytes(byte[])
-
getJMSCorrelationID
String getJMSCorrelationID()
Returns theJMSCorrelationID
header value that has been set on thisJMSProducer
, as aString
.This method is used to return correlation ID values that are either provider-specific message IDs or application-specific
String
values.- Returns:
- the correlation ID of a message as a
String
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the correlation ID due to some internal error.- See Also:
setJMSCorrelationID(String)
,getJMSCorrelationIDAsBytes()
,setJMSCorrelationIDAsBytes(byte[])
-
setJMSType
JMSProducer setJMSType(String type)
Specifies that messages sent using thisJMSProducer
will have theirJMSType
header value set to the specified message type.This will override any
JMSType
header value that is already set on the message being sent.Some Jakarta Messaging providers use a message repository that contains the definitions of messages sent by applications. The
JMSType
header field may reference a message's definition in the provider's repository.The Jakarta Messaging API does not define a standard message definition repository, nor does it define a naming policy for the definitions it contains.
Some messaging systems require that a message type definition for each application message be created and that each message specify its type. In order to work with such Jakarta Messaging providers, Jakarta Messaging clients should assign a value to
JMSType
, whether the application makes use of it or not. This ensures that the field is properly set for those providers that require it.To ensure portability, Jakarta Messaging clients should use symbolic values for
JMSType
that can be configured at installation time to the values defined in the current provider's message repository. If string literals are used, they may not be valid type names for some Jakarta Messaging providers.- Parameters:
type
- the message type- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set the message type due to some internal error.- See Also:
getJMSType()
-
getJMSType
String getJMSType()
Returns theJMSType
header value that has been set on thisJMSProducer
.- Returns:
- the message type
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get the message type due to some internal error.- See Also:
setJMSType(String)
-
setJMSReplyTo
JMSProducer setJMSReplyTo(Destination replyTo)
Specifies that messages sent using thisJMSProducer
will have theirJMSReplyTo
header value set to the specifiedDestination
object.This will override any
JMSReplyTo
header value that is already set on the message being sent.The
JMSReplyTo
header field contains the destination where a reply to the current message should be sent. If it is null, no reply is expected. The destination may be either aQueue
object or aTopic
object.Messages sent with a null
JMSReplyTo
value may be a notification of some event, or they may just be some data the sender thinks is of interest.Messages with a
JMSReplyTo
value typically expect a response. A response is optional; it is up to the client to decide. These messages are called requests. A message sent in response to a request is called a reply.In some cases a client may wish to match a request it sent earlier with a reply it has just received. The client can use the
JMSCorrelationID
header field for this purpose.- Parameters:
replyTo
-Destination
to which to send a response to this message- Returns:
- this
JMSProducer
- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to set theJMSReplyTo
destination due to some internal error.- See Also:
getJMSReplyTo()
-
getJMSReplyTo
Destination getJMSReplyTo()
Returns theJMSReplyTo
header value that has been set on thisJMSProducer
.- Returns:
Destination
theJMSReplyTo
header value- Throws:
JMSRuntimeException
- if the Jakarta Messaging provider fails to get theJMSReplyTo
destination due to some internal error.- See Also:
setJMSReplyTo(Destination)
-
-