javax.jms.JMSProducer Maven / Gradle / Ivy
Show all versions of ow2-jms-2.0-spec Show documentation
/**
* Copyright 2013 ScalAgent Distributed Technologies
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* ---------------------------------------------------------------------
* $Id: JMSProducer.java 6347 2013-03-13 08:52:02Z tachker $
* ---------------------------------------------------------------------
*/
package javax.jms;
import java.io.Serializable;
import java.util.Map;
import java.util.Set;
/**
* A {@code JMSProducer} is a simple object used to send messages on behalf of a
* {@code JMSContext}. An instance of {@code JMSProducer} is created by calling
* the {@code createProducer} method on a {@code JMSContext}. It provides
* various {@code send} 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.
*
* This interface therefore does not provide a {@code close} method.
*
* @version JMS 2.0
* @since JMS 2.0
*
*/
public interface JMSProducer {
/**
* Sends a message to the specified destination, using any send options,
* message properties and message headers that have been defined on this
* {@code JMSProducer}.
*
* @param destination
* the destination to send this message to
* @param message
* the message to send
* @return this {@code JMSProducer}
* @throws MessageFormatRuntimeException
* if an invalid message is specified.
* @throws InvalidDestinationRuntimeException
* if a client uses this method with an invalid destination.
* @throws MessageNotWriteableRuntimeException
* if this {@code JMSProducer} has been configured to set a message
* property, but the message's properties are read-only
* @throws JMSRuntimeException
* if the JMS provider fails to send the message due to some
* internal error.
*/
JMSProducer send(Destination destination, Message message);
/**
* Send a {@code TextMessage} with the specified body to the specified
* destination, using any send options.
*
* @param destination
* the destination to send this message to
* @param body
* the body of the {@code TextMessage} that will be sent. If a null
* value is specified then a {@code TextMessage} with no body will be
* sent.
* @return this {@code JMSProducer}
* @throws MessageFormatRuntimeException
* if an invalid message is specified.
* @throws InvalidDestinationRuntimeException
* if a client uses this method with an invalid destination.
* @throws JMSRuntimeException
* if the JMS provider fails to send the message due to some
* internal error.
*/
JMSProducer send(Destination destination, String body);
/**
* Send a {@code MapMessage} with the specified body to the specified
* destination, using any send options.
*
* @param destination
* the destination to send this message to
* @param body
* the body of the {@code MapMessage} that will be sent. If a null
* value is specified then a {@code MapMessage} with no map entries
* will be sent.
* @return this {@code JMSProducer}
* @throws MessageFormatRuntimeException
* if an invalid message is specified.
* @throws InvalidDestinationRuntimeException
* if a client uses this method with an invalid destination.
* @throws JMSRuntimeException
* if the JMS provider fails to send the message due to some
* internal error.
*/
JMSProducer send(Destination destination, Map body);
/**
* Send a {@code BytesMessage} with the specified body to the specified
* destination, using any send options.
*
* @param destination
* the destination to send this message to
* @param body
* the body of the {@code BytesMessage} that will be sent. If a null
* value is specified then a {@code BytesMessage} with no body will
* be sent.
* @return this {@code JMSProducer}
* @throws MessageFormatRuntimeException
* if an invalid message is specified.
* @throws InvalidDestinationRuntimeException
* if a client uses this method with an invalid destination.
* @throws JMSRuntimeException
* if the JMS provider fails to send the message due to some
* internal error.
*/
JMSProducer send(Destination destination, byte[] body);
/**
* Send an {@code ObjectMessage} with the specified body to the specified
* destination, using any send options.
*
* @param destination
* the destination to send this message to
* @param body
* the body of the ObjectMessage that will be sent. If a null value
* is specified then an {@code ObjectMessage} with no body will be
* sent.
* @return this {@code JMSProducer}
* @throws MessageFormatRuntimeException
* if an invalid message is specified.
* @throws InvalidDestinationRuntimeException
* if a client uses this method with an invalid destination.
* @throws JMSRuntimeException
* if JMS provider fails to send the message due to some internal
* error.
*/
JMSProducer send(Destination destination, Serializable body);
/**
* Specifies whether message IDs may be disabled for messages that are sent
* using this {@code JMSProducer}
*
*
* @param value
* indicates whether message IDs may be disabled
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set message ID to disabled due to
* some internal error.
*
* @see javax.jms.JMSProducer#getDisableMessageID
*/
JMSProducer setDisableMessageID(boolean value);
/**
* Gets an indication of whether message IDs are disabled.
*
* @return an indication of whether message IDs are disabled
*
* @throws JMSRuntimeException
* if the JMS provider fails to determine if message IDs are
* disabled due to some internal error.
*
* @see javax.jms.JMSProducer#setDisableMessageID
*/
boolean getDisableMessageID();
/**
* Specifies whether message timestamps may be disabled for messages that are
* sent using this {@code JMSProducer}. Message timestamps are enabled by
* default.
*
* @param value
* indicates whether message timestamps may be disabled
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set timestamps to disabled due to
* some internal error.
*
* @see javax.jms.JMSProducer#getDisableMessageTimestamp
*/
JMSProducer setDisableMessageTimestamp(boolean value);
/**
* Gets an indication of whether message timestamps are disabled.
*
* @return an indication of whether message timestamps are disabled
*
* @throws JMSRuntimeException
* if the JMS provider fails to determine if timestamps are disabled
* due to some internal error.
* @see javax.jms.JMSProducer#setDisableMessageTimestamp
*/
boolean getDisableMessageTimestamp();
/**
* Defines the delivery mode of messages that are sent using this
* {@code JMSProducer}
*
* Delivery mode is set to {@code PERSISTENT} by default.
*
* @param deliveryMode
* the message delivery mode to be used; legal values are
* {@code DeliveryMode.NON_PERSISTENT} and
* {@code DeliveryMode.PERSISTENT}
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the delivery mode due to some
* internal error.
*
* @see javax.jms.JMSProducer#getDeliveryMode
* @see javax.jms.DeliveryMode#NON_PERSISTENT
* @see javax.jms.DeliveryMode#PERSISTENT
* @see javax.jms.Message#DEFAULT_DELIVERY_MODE
*/
JMSProducer setDeliveryMode(int deliveryMode);
/**
* Gets the delivery mode of messages that are sent using this
* {@code JMSProducer}
*
* @return the message delivery mode
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the delivery mode due to some
* internal error.
*
* @see javax.jms.JMSProducer#setDeliveryMode
*/
int getDeliveryMode();
/**
* Defines the priority of messages that are sent using this
* {@code JMSProducer}
*
* @param priority
* the message priority to be used; must be a value between 0 and 9
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the priority due to some
* internal error.
*
* @see javax.jms.JMSProducer#getPriority
* @see javax.jms.Message#DEFAULT_PRIORITY
*/
JMSProducer setPriority(int priority);
/**
* Returns the priority of messages that are sent using this
* {@code JMSProducer}
*
*
* @return the message priority
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the priority due to some
* internal error.
*
* @see javax.jms.JMSProducer#setPriority
*/
int getPriority();
/**
* Specifies the time to live of messages that are sent using this
* {@code JMSProducer}. This is used to determine the expiration time of a
* message.
*
* @param timeToLive
* the message time to live to be used, in milliseconds; a value of
* zero means that a message never expires.
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the time to live due to some
* internal error.
*
* @see javax.jms.JMSProducer#getTimeToLive
* @see javax.jms.Message#DEFAULT_TIME_TO_LIVE
*/
JMSProducer setTimeToLive(long timeToLive);
/**
* Returns the time to live of messages that are sent using this
* {@code JMSProducer}.
*
* @return the message time to live in milliseconds; a value of zero means
* that a message never expires.
* @throws JMSRuntimeException
* if the JMS provider fails to get the time to live due to some
* internal error.
*
* @see javax.jms.JMSProducer#setTimeToLive
*/
long getTimeToLive();
/**
* 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.
*
* @param deliveryDelay
* the delivery delay in milliseconds.
* @return this {@code JMSProducer}
*
* @throws JMSRuntimeException
* if the JMS provider fails to set the delivery delay due to some
* internal error.
*
* @see javax.jms.JMSProducer#getDeliveryDelay
* @see javax.jms.Message#DEFAULT_DELIVERY_DELAY
*/
JMSProducer setDeliveryDelay(long deliveryDelay);
/**
* 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.
*
* @return the delivery delay in milliseconds.
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the delivery delay due to some
* internal error.
*
* @see javax.jms.JMSProducer#setDeliveryDelay
*/
long getDeliveryDelay();
/**
* Specifies whether subsequent calls to {@code send} on this
* {@code JMSProducer} object should be synchronous or asynchronous. If the
* specified {@code CompletionListener} is not null then subsequent calls to
* {@code send} will be asynchronous. If the specified
* {@code CompletionListener} is null then subsequent calls to {@code send}
* will be synchronous. Calls to {@code send} are synchronous by default.
*
* @param completionListener
* If asynchronous send behaviour is required, this should be set to
* a {@code CompletionListener} to be notified when the send has
* completed. If synchronous send behaviour is required, this should
* be set to {@code null}.
* @return this {@code JMSProducer}
*
* @throws JMSRuntimeException
* if an internal error occurs
*
* @see javax.jms.JMSProducer#getAsync
* @see javax.jms.CompletionListener
*
*/
JMSProducer setAsync(CompletionListener completionListener);
/**
* If subsequent calls to {@code send} on this {@code JMSProducer} object have
* been configured to be asynchronous then this method returns the
* {@code CompletionListener} that has previously been configured. If
* subsequent calls to {@code send} have been configured to be synchronous
* then this method returns {@code null}.
*
* @return the {@code CompletionListener} or {@code null}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the required information due to
* some internal error.
*
* @see javax.jms.JMSProducer#setAsync
*/
CompletionListener getAsync();
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified {@code boolean} value.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the {@code boolean} value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
*
* @see javax.jms.JMSProducer#getBooleanProperty
*/
JMSProducer setProperty(String name, boolean value);
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified {@code byte} value.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the {@code byte} value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
*
* @see javax.jms.JMSProducer#getByteProperty
*/
JMSProducer setProperty(String name, byte value);
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified {@code short} value.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the {@code short} property value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
*
* @see javax.jms.JMSProducer#getShortProperty
*/
JMSProducer setProperty(String name, short value);
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified {@code int} value.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the {@code int} property value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
*
* @see javax.jms.JMSProducer#getIntProperty
*/
JMSProducer setProperty(String name, int value);
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified {@code long} value.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the {@code long} property value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
*
* @see javax.jms.JMSProducer#getLongProperty
*/
JMSProducer setProperty(String name, long value);
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified {@code float} value.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the {@code float} property value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
*
* @see javax.jms.JMSProducer#getFloatProperty
*/
JMSProducer setProperty(String name, float value);
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified {@code double} value.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the {@code double} property value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
*
* @see javax.jms.JMSProducer#getDoubleProperty
*/
JMSProducer setProperty(String name, double value);
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified {@code String} value.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the {@code String} property value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
*
* @see javax.jms.JMSProducer#getStringProperty
*/
JMSProducer setProperty(String name, String value);
/**
* Specifies that messages sent using this {@code JMSProducer} will have the
* specified property set to the specified Java object value.
*
* Note that this method works only for the objectified primitive object types
* ({@code Integer}, {@code Double}, {@code Long} ...) and {@code String}
* objects.
*
* This will replace any property of the same name that is already set on the
* message being sent.
*
* @param name
* the name of the property
* @param value
* the Java object property value to set
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the property due to some
* internal error.
* @throws IllegalArgumentException
* if the name is null or if the name is an empty string.
* @throws MessageFormatRuntimeException
* if the object is invalid
*
* @see javax.jms.JMSProducer#getObjectProperty
*/
JMSProducer setProperty(String name, Object value);
/**
* Clears any message properties set on this {@code JMSProducer}
*
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to clear the message properties due to
* some internal error.
*/
JMSProducer clearProperties();
/**
* Indicates whether a message property with the specified name has been set
* on this {@code JMSProducer}
*
* @param name
* the name of the property
*
* @return true whether the property exists
*
* @throws JMSRuntimeException
* if the JMS provider fails to determine whether the property
* exists due to some internal error.
*/
boolean propertyExists(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, converted to a {@code boolean}.
*
* @param name
* the name of the property
*
* @return the property value, converted to a {@code boolean}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
* @throws MessageFormatRuntimeException
* if this type conversion is invalid.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,boolean)
*/
boolean getBooleanProperty(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, converted to a {@code String}.
*
* @param name
* the name of the property
*
* @return the property value, converted to a {@code byte}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
* @throws MessageFormatRuntimeException
* if this type conversion is invalid.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,byte)
*/
byte getByteProperty(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, converted to a {@code short}.
*
* @param name
* the name of the property
*
* @return the property value, converted to a {@code short}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
* @throws MessageFormatRuntimeException
* if this type conversion is invalid.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,short)
*/
short getShortProperty(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, converted to a {@code int}.
*
* @param name
* the name of the property
*
* @return the property value, converted to a {@code int}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
* @throws MessageFormatRuntimeException
* if this type conversion is invalid.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,int)
*/
int getIntProperty(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, converted to a {@code long}.
*
* @param name
* the name of the property
*
* @return the property value, converted to a {@code long}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
* @throws MessageFormatRuntimeException
* if this type conversion is invalid.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,long)
*/
long getLongProperty(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, converted to a {@code float}.
*
* @param name
* the name of the property
*
* @return the property value, converted to a {@code float}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
* @throws MessageFormatRuntimeException
* if this type conversion is invalid.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,float)
*/
float getFloatProperty(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, converted to a {@code double}.
*
* @param name
* the name of the property
*
* @return the property value, converted to a {@code double}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
* @throws MessageFormatRuntimeException
* if this type conversion is invalid.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,double)
*/
double getDoubleProperty(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, converted to a {@code String}.
*
* @param name
* the name of the property
*
* @return the property value, converted to a {@code boolean}; if there is no
* property by this name, a null value is returned
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
* @throws MessageFormatRuntimeException
* if this type conversion is invalid.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,String)
*/
String getStringProperty(String name);
/**
* Returns the message property with the specified name that has been set on
* this {@code JMSProducer}, 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
* {@code setObjectProperty} method call, or its equivalent primitive
* {@code settypeProperty} method.
*
* @param name
* the name of the property
*
* @return the Java object property value with the specified name, in
* objectified format (for example, if the property was set as an
* {@code int}, an {@code Integer} is returned); if there is no
* property by this name, a null value is returned
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property value due to some
* internal error.
*
* @see javax.jms.JMSProducer#setProperty(java.lang.String,java.lang.Object)
*/
Object getObjectProperty(String name);
/**
* Returns an unmodifiable {@code Set} view of the names of all the message
* properties that have been set on this JMSProducer.
*
* Note that JMS standard header fields are not considered properties and are
* not returned in this Set.
*
* The set is backed by the {@code 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 an {@code java.lang.UnsupportedOperationException}. Its behaviour
* matches that defined in the {@code java.util.Collections} method
* {@code unmodifiableSet}.
*
* @return a {@code Set} containing the names of all the message properties
* that have been set on this {@code JMSProducer}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the property names due to some
* internal error.
*
* @see java.util.Collections#unmodifiableSet
*/
Set getPropertyNames();
/**
* Specifies that messages sent using this {@code JMSProducer} will have their
* {@code JMSCorrelationID} header value set to the specified correlation ID,
* where correlation ID is specified as an array of bytes.
*
* This will override any {@code JMSCorrelationID} header value that is
* already set on the message being sent.
*
* @param correlationID
* the correlation ID value as an array of bytes
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the correlation ID due to some
* internal error.
*
* @see javax.jms.JMSProducer#setJMSCorrelationID(String)
* @see javax.jms.JMSProducer#getJMSCorrelationID()
* @see javax.jms.JMSProducer#getJMSCorrelationIDAsBytes()
*/
JMSProducer setJMSCorrelationIDAsBytes(byte[] correlationID);
/**
* Returns the {@code JMSCorrelationID} header value that has been set on this
* {@code JMSProducer}, as an array of bytes.
*
* The use of a {@code byte[]} value for {@code JMSCorrelationID} is
* non-portable.
*
* @return the correlation ID as an array of bytes
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the correlation ID due to some
* internal error.
*
* @see javax.jms.JMSProducer#setJMSCorrelationID(String)
* @see javax.jms.JMSProducer#getJMSCorrelationID()
* @see javax.jms.JMSProducer#setJMSCorrelationIDAsBytes(byte[])
*/
byte[] getJMSCorrelationIDAsBytes();
/**
* Specifies that messages sent using this {@code JMSProducer} will have their
* {@code JMSCorrelationID} header value set to the specified correlation ID,
* where correlation ID is specified as a {@code String}.
*
* This will override any {@code JMSCorrelationID} header value that is
* already set on the message being sent.
*
* A client can use the {@code JMSCorrelationID} header field to link one
* message with another. A typical use is to link a response message with its
* request message.
*
* {@code JMSCorrelationID} can hold one of the following:
*
* - A provider-specific message ID
*
- An application-specific {@code String}
*
- A provider-native {@code byte[]} value
*
*
* Since each message sent by a JMS provider is assigned a message ID value,
* it is convenient to link messages via message ID. All message ID values
* must start with the {@code '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 {@code JMSCorrelationID} to hold a value referencing
* some external information. Application-specified values must not start with
* the {@code 'ID:'} prefix; this is reserved for provider-generated message
* ID values.
*
* If a provider supports the native concept of correlation ID, a JMS client
* may need to assign specific {@code JMSCorrelationID} values to match those
* expected by clients that do not use the JMS API. A {@code byte[]} value is
* used for this purpose. JMS providers without native correlation ID values
* are not required to support {@code byte[]} values. The use of a
* {@code byte[]} value for {@code JMSCorrelationID} is non-portable.
*
* @param correlationID
* the message ID of a message being referred to
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the correlation ID due to some
* internal error.
*
* @see javax.jms.JMSProducer#getJMSCorrelationID()
* @see javax.jms.JMSProducer#getJMSCorrelationIDAsBytes()
* @see javax.jms.JMSProducer#setJMSCorrelationIDAsBytes(byte[])
*/
JMSProducer setJMSCorrelationID(String correlationID);
/**
* Returns the {@code JMSCorrelationID} header value that has been set on this
* {@code JMSProducer}, as a {@code String}.
*
* This method is used to return correlation ID values that are either
* provider-specific message IDs or application-specific {@code String}
* values.
*
* @return the correlation ID of a message as a {@code String}
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the correlation ID due to some
* internal error.
*
* @see javax.jms.JMSProducer#setJMSCorrelationID(String)
* @see javax.jms.JMSProducer#getJMSCorrelationIDAsBytes()
* @see javax.jms.JMSProducer#setJMSCorrelationIDAsBytes(byte[])
*/
String getJMSCorrelationID();
/**
* Specifies that messages sent using this {@code JMSProducer} will have their
* {@code JMSType} header value set to the specified message type.
*
* This will override any {@code JMSType} header value that is already set on
* the message being sent.
*
* Some JMS providers use a message repository that contains the definitions
* of messages sent by applications. The {@code JMSType} header field may
* reference a message's definition in the provider's repository.
*
* The JMS 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 JMS providers, JMS clients should assign a value to
* {@code 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, JMS clients should use symbolic values for
* {@code 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 JMS providers.
*
* @param type
* the message type
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the message type due to some
* internal error.
*
* @see javax.jms.JMSProducer#getJMSType()
*/
JMSProducer setJMSType(String type);
/**
* Returns the {@code JMSType} header value that has been set on this
* {@code JMSProducer}.
*
* @return the message type
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the message type due to some
* internal error.
*
* @see javax.jms.JMSProducer#setJMSType(String)
*/
String getJMSType();
/**
* Specifies that messages sent using this {@code JMSProducer} will have their
* {@code JMSReplyTo} header value set to the specified {@code Destination}
* object.
*
* This will override any {@code JMSReplyTo} header value that is already set
* on the message being sent.
*
* The {@code 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 a {@code Queue} object or a {@code Topic}
* object.
*
* Messages sent with a null {@code 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 {@code 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 {@code JMSCorrelationID}
* header field for this purpose.
*
* @param replyTo
* {@code Destination} to which to send a response to this message
* @return this {@code JMSProducer}
* @throws JMSRuntimeException
* if the JMS provider fails to set the {@code JMSReplyTo}
* destination due to some internal error.
*
* @see javax.jms.JMSProducer#getJMSReplyTo()
*/
JMSProducer setJMSReplyTo(Destination replyTo);
/**
* Returns the {@code JMSReplyTo} header value that has been set on this
* {@code JMSProducer}.
*
*
* @return {@code Destination} the {@code JMSReplyTo} header value
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the {@code JMSReplyTo}
* destination due to some internal error.
*
* @see javax.jms.JMSProducer#setJMSReplyTo(Destination)
*/
Destination getJMSReplyTo();
}