javax.jms
Interface MessageProducer

All Known Subinterfaces:

QueueSender, TopicPublisher

public interface MessageProducer

A client uses a message producer to send messages to a Destination. It is created by passing a Destination to a create message producer method supplied by a Session.

A client also has the option of creating a message producer without supplying a Destination. In this case, a Destination must be input on every send operation. A typical use for this style of message producer is to send replies to requests using the request's replyTo Destination.

A client can specify a default delivery mode, priority and time-to-live for messages sent by a message producer. It can also specify delivery mode, priority and time-to-live per message.

A client can specify a time-to-live value in milliseconds for each message it sends. This value defines a message expiration time which is the sum of the message's time-to-live and the GMT it is sent (for transacted sends, this is the time the client sends the message, not the time the transaction is committed).

A JMS provider should do its best to accurately expire messages; however, JMS does not define the accuracy provided.

See Also:

TopicPublisher, QueueSender, Session

Method Summary

void	close() Since a provider may allocate some resources on behalf of a MessageProducer outside the JVM, clients should close them when they are not needed.
int	getDeliveryMode() Get the producer's default delivery mode.
boolean	getDisableMessageID() Get an indication of whether message IDs are disabled.
boolean	getDisableMessageTimestamp() Get an indication of whether message timestamps are disabled.
int	getPriority() Get the producer's default priority.
long	getTimeToLive() Get the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
void	setDeliveryMode(int deliveryMode) Set the producer's default delivery mode.
void	setDisableMessageID(boolean value) Set whether message IDs are disabled.
void	setDisableMessageTimestamp(boolean value) Set whether message timestamps are disabled.
void	setPriority(int defaultPriority) Set the producer's default priority.
void	setTimeToLive(long timeToLive) Set the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.

Method Detail

setDisableMessageID

public void setDisableMessageID(boolean value)
                         throws JMSException

Set whether message IDs are disabled.

Since message ID's take some effort to create and increase a message's size, some JMS providers may be able to optimize message overhead if they are given a hint that message ID is not used by an application. JMS message Producers provide a hint to disable message ID. When a client sets a Producer to disable message ID they are saying that they do not depend on the value of message ID for the messages it produces. These messages must either have message ID set to null or, if the hint is ignored, messageID must be set to its normal unique value.

Message IDs are enabled by default.

Parameters:

value - indicates if message IDs are disabled.

Throws:

JMSException - if JMS fails to set disabled message Id due to some internal error.

getDisableMessageID

public boolean getDisableMessageID()
                            throws JMSException

Get an indication of whether message IDs are disabled.

Returns:

an indication of whether message IDs are disabled.

Throws:

JMSException - if JMS fails to get disabled message Id due to some internal error.

setDisableMessageTimestamp

public void setDisableMessageTimestamp(boolean value)
                                throws JMSException

Set whether message timestamps are disabled.

Since timestamps take some effort to create and increase a message's size, some JMS providers may be able to optimize message overhead if they are given a hint that timestamp is not used by an application. JMS message Producers provide a hint to disable timestamps. When a client sets a producer to disable timestamps they are saying that they do not depend on the value of timestamp for the messages it produces. These messages must either have timestamp set to null or, if the hint is ignored, timestamp must be set to its normal value.

Message timestamps are enabled by default.

Parameters:

value - indicates if message timestamps are disabled.

Throws:

JMSException - if JMS fails to set disabled message timestamp due to some internal error.

getDisableMessageTimestamp

public boolean getDisableMessageTimestamp()
                                   throws JMSException

Get an indication of whether message timestamps are disabled.

Returns:

an indication of whether message IDs are disabled.

Throws:

JMSException - if JMS fails to get disabled message timestamp due to some internal error.

setDeliveryMode

public void setDeliveryMode(int deliveryMode)
                     throws JMSException

Set the producer's default delivery mode.

Delivery mode is set to PERSISTENT by default.

Parameters:

deliveryMode - the message delivery mode for this message producer. Legal values are DeliveryMode.NON_PERSISTENT or DeliveryMode.PERSISTENT.

Throws:

JMSException - if JMS fails to set delivery mode due to some internal error.

See Also:

getDeliveryMode(), DeliveryMode.NON_PERSISTENT, DeliveryMode.PERSISTENT, Message.DEFAULT_DELIVERY_MODE

getDeliveryMode

public int getDeliveryMode()
                    throws JMSException

Get the producer's default delivery mode.

Returns:

the message delivery mode for this message producer.

Throws:

JMSException - if JMS fails to get delivery mode due to some internal error.

See Also:

setDeliveryMode(int)

setPriority

public void setPriority(int defaultPriority)
                 throws JMSException

Set the producer's default priority.

JMS defines a 10 level priority value with 0 as the lowest and 9 as the highest. Clients should consider 0-4 as gradients of normal priority and 5-9 as gradients of expedited priority. Priority is set to 4, by default.

Parameters:

priority - the message priority for this message producer. Priority must be a value between 0 and 9.

Throws:

JMSException - if JMS fails to set priority due to some internal error.

See Also:

getPriority(), Message.DEFAULT_PRIORITY

getPriority

public int getPriority()
                throws JMSException

Get the producer's default priority.

Returns:

the message priority for this message producer.

Throws:

JMSException - if JMS fails to get priority due to some internal error.

See Also:

setPriority(int)

setTimeToLive

public void setTimeToLive(long timeToLive)
                   throws JMSException

Set the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.

Time to live is set to zero by default.

Parameters:

timeToLive - the message time to live in milliseconds; zero is unlimited

Throws:

JMSException - if JMS fails to set Time to Live due to some internal error.

See Also:

getTimeToLive(), Message.DEFAULT_TIME_TO_LIVE

getTimeToLive

public long getTimeToLive()
                   throws JMSException

Get the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.

Returns:

the message time to live in milliseconds; zero is unlimited

Throws:

JMSException - if JMS fails to get Time to Live due to some internal error.

See Also:

setTimeToLive(long)

close

public void close()
           throws JMSException

Since a provider may allocate some resources on behalf of a MessageProducer outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Throws:

JMSException - if JMS fails to close the producer due to some error.