javax.jms.JMSProducer Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2014 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
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.
*
* Message send options may be specified using one or more of the following
* methods: {@code setDeliveryMode}, {@code setPriority},
* {@code setTimeToLive}, {@code setDeliveryDelay},
* {@code setDisableMessageTimestamp}, {@code setDisableMessageID} and
* {@code setAsync}.
*
* Message properties may be may be specified using one or more of nine
* {@code 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:
* {@code setJMSCorrelationID}, {@code setJMSCorrelationIDAsBytes},
* {@code setJMSType} or {@code setJMSReplyTo}. 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 {@code 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 {@code 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 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, message properties and
* message headers that have been defined on this {@code JMSProducer}.
*
* @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, message properties and
* message headers that have been defined on this {@code JMSProducer}.
*
* @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, message properties and
* message headers that have been defined on this {@code JMSProducer}.
*
* @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, message properties and
* message headers that have been defined on this {@code JMSProducer}.
*
* @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}
*
* 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 {@code JMSProducer}.
* 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.
*
*
* @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}. 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 {@code 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.
*
* @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();
/**
* Specifies 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);
/**
* Returns 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();
/**
* Specifies the priority of messages that are sent using this
* {@code JMSProducer}
*
* 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.
*
*
* @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);
/**
* Return 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.
*
* 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, JMS does
* not guarantee that this will not happen.
*
* A JMS provider should do its best to accurately expire messages; however,
* JMS 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.
*
* @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.
*
* 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.
*
* @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.
*
* If a call to {@code 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 JMS 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 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 JMSContext 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 JMSContext then the JMS provider must block until any
* incomplete send operations have been completed and all
* {@code 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 all
* {@code 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, commit or rollback on its own
* JMSContext. Doing so will cause the close,
* commit or rollback to throw an
* IllegalStateRuntimeException.
*
* 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 {@code JMSRuntimeException}
* 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 JMSContext, callbacks (both
* {@code onCompletion} and {@code onException}) will be performed
* in the same order as the corresponding calls to the send method.
* A JMS 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 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.
*
* @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
* 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.
*
* The array is copied before the method returns, so future modifications to
* the array will not alter the value in this {@code JMSProducer}.
*
* 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 native messaging clients. JMS providers without native
* correlation ID values are not required to support this method and its
* corresponding get method; their implementation may throw a
* {@code java.lang.UnsupportedOperationException}.
*
* The use of a {@code byte[]} value for {@code JMSCorrelationID}
* is non-portable.
*
* @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();
}