KMMessageProducer Class Reference
| Inherits from | KCObject : NSObject |
| Declared in | KMMessageProducer.h |
Overview
A client uses a MessageProducer object to send messages to a destination. A MessageProducer object is created by passing a Destination object to a message-producer creation method supplied by a session.
MessageProducer is the parent interface for all message producers.
A client also has the option of creating a message producer without supplying a destination. In this case, a destination must be provided with every send operation. A typical use for this kind of message producer is to send replies to requests using the request’s JMSReplyTo 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 the delivery mode, priority, and time to live for an individual message.
A client can specify a time-to-live value in milliseconds for each message it sends. This value defines a message expiration time that is the sum of the message’s time-to-live and the GMT when 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 expire messages accurately; however, the JMS API does not define the accuracy provided.
Tasks
-
– setDisableMessageID:Sets whether message IDs are disabled.
-
– disableMessageIDGets an indication of whether message IDs are disabled.
-
– setDisableMessageTimestamp:Sets whether message timestamps are disabled.
-
– disableMessageTimestampGets an indication of whether message timestamps are disabled.
-
– setDeliveryMode:Sets the producer’s default delivery mode.
-
– deliveryModeGets the producer’s default delivery mode.
-
– setPriority:Sets the producer’s default priority.
-
– priorityGets the producer’s default priority.
-
– setTimeToLive:Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
-
– timeToLiveGets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
-
– destinationGets the destination associated with this MessageProducer.
-
– closeCloses the message producer.
-
– send:Sends a message using the MessageProducer’s default delivery mode, priority, and time to live.
-
– send:deliveryMode:priority:timeToLive:Sends a message to the destination, specifying delivery mode, priority, and time to live.
-
– send:message:Sends a message to a destination for an unidentified message producer. Uses the MessageProducer’s default delivery mode, priority, and time to live.
-
– send:message:deliveryMode:priority:timeToLive:Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to live.
Instance Methods
close
Closes the message producer.
- (void)closeDiscussion
Since a provider may allocate some resources on behalf of a MessageProducer outside the application, clients should close them when they are no longer needed.
Exceptions
- KMJMSException
if the JMS provider fails to close the producer due to some internal error.
Declared In
KMMessageProducer.hdeliveryMode
Gets the producer’s default delivery mode.
- (int)deliveryModeReturn Value
the message delivery mode for this message producer
Exceptions
- KMJMSException
if the JMS provider fails to get the delivery mode due to some internal error.
See Also
Declared In
KMMessageProducer.hdestination
Gets the destination associated with this MessageProducer.
- (KMDestination *)destinationReturn Value
this producer’s Destination
Exceptions
- KMJMSException
if the JMS provider fails to get the destination for this MessageProducer due to some internal error.
Declared In
KMMessageProducer.hdisableMessageID
Gets an indication of whether message IDs are disabled.
- (BOOL)disableMessageIDReturn Value
an indication of whether message IDs are disabled
Exceptions
- KMJMSException
if the JMS provider fails to determine if message IDs are disabled due to some internal error.
Declared In
KMMessageProducer.hdisableMessageTimestamp
Gets an indication of whether message timestamps are disabled.
- (BOOL)disableMessageTimestampReturn Value
an indication of whether message timestamps are disabled
Exceptions
- KMJMSException
if the JMS provider fails to determine if timestamps are disabled due to some internal error.
Declared In
KMMessageProducer.hpriority
Gets the producer’s default priority.
- (int)priorityReturn Value
the message priority for this message producer
Exceptions
- KMJMSException
if the JMS provider fails to get the priority due to some internal error.
See Also
Declared In
KMMessageProducer.hsend:
Sends a message using the MessageProducer’s default delivery mode, priority, and time to live.
- (void)send:(KMMessage *)messageParameters
- message
the message to send
Exceptions
- KMJMSException
if the JMS provider fails to send the message due to some internal error.
- KMMessageFormatException
if an invalid message is specified.
- KMInvalidDestinationException
if a client uses this method with a MessageProducer with an invalid destination.
- KMUnsupportedOperationException
if a client uses this method with a MessageProducer that did not specify a destination at creation time.
See Also
Declared In
KMMessageProducer.hsend:deliveryMode:priority:timeToLive:
Sends a message to the destination, specifying delivery mode, priority, and time to live.
- (void)send:(KMMessage *)message deliveryMode:(int)deliveryMode priority:(int)priority timeToLive:(long long)timeToLiveParameters
- message
the message to send
- deliveryMode
the delivery mode to use
- priority
the priority for this message
- timeToLive
the message’s lifetime (in milliseconds)
Exceptions
- KMJMSException
if the JMS provider fails to send the message due to some internal error.
- KMMessageFormatException
if an invalid message is specified.
- KMInvalidDestinationException
if a client uses this method with a MessageProducer with an invalid destination.
- KMUnsupportedOperationException
if a client uses this method with a MessageProducer that did not specify a destination at creation time.
See Also
Declared In
KMMessageProducer.hsend:message:
Sends a message to a destination for an unidentified message producer. Uses the MessageProducer’s default delivery mode, priority, and time to live.
- (void)send:(KMDestination *)destination message:(KMMessage *)messageDiscussion
Typically, a message producer is assigned a destination at creation time; however, the JMS API also supports unidentified message producers, which require that the destination be supplied every time a message is sent.
Exceptions
- KMJMSException
if the JMS provider fails to send the message due to some internal error.
- KMMessageFormatException
if an invalid message is specified.
- KMInvalidDestinationException
if a client uses this method with an invalid destination.
- KMUnsupportedOperationException
if a client uses this method with a MessageProducer that specified a destination at creation time.
See Also
Declared In
KMMessageProducer.hsend:message:deliveryMode:priority:timeToLive:
Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to live.
- (void)send:(KMDestination *)destination message:(KMMessage *)message deliveryMode:(int)deliveryMode priority:(int)priority timeToLive:(long long)timeToLiveParameters
- destination
the destination to send this message to
- message
the message to send
- deliveryMode
the delivery mode to use
- priority
the priority for this message
- timeToLive
the message’s lifetime (in milliseconds)
Discussion
Typically, a message producer is assigned a destination at creation time; however, the JMS API also supports unidentified message producers, which require that the destination be supplied every time a message is sent.
Exceptions
- KMJMSException
if the JMS provider fails to send the message due to some internal error.
- KMMessageFormatException
if an invalid message is specified.
- KMInvalidDestinationException
if a client uses this method with an invalid destination.
See Also
Declared In
KMMessageProducer.hsetDeliveryMode:
Sets the producer’s default delivery mode.
- (void)setDeliveryMode:(int)deliveryModeParameters
- deliveryMode
the message delivery mode for this message producer; legal values are DeliveryModeNonPersistent and DeliveryModePersistent
Discussion
Delivery mode is set to PERSISTENT by default.
Exceptions
- KMJMSException
if the JMS provider fails to set the delivery mode due to some internal error.
See Also
Declared In
KMMessageProducer.hsetDisableMessageID:
Sets whether message IDs are disabled.
- (void)setDisableMessageID:(BOOL)valueParameters
- value
indicates if message IDs are disabled
Discussion
Since message IDs 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 the message ID is not used by an application. By calling the setDisableMessageID method on this message producer, a JMS client enables this potential optimization for all messages sent by this message producer. 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.
Exceptions
- KMJMSException
if the JMS provider fails to set message ID to disabled due to some internal error.
Declared In
KMMessageProducer.hsetDisableMessageTimestamp:
Sets whether message timestamps are disabled.
- (void)setDisableMessageTimestamp:(BOOL)valueParameters
- value
indicates if message timestamps are disabled
Discussion
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 the timestamp is not used by an application. By calling the setDisableMessageTimestamp method on this message producer, a JMS client enables this potential optimization for all messages sent by this message producer. 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.
Exceptions
- KMJMSException
if the JMS provider fails to set timestamps to disabled due to some internal error.
Declared In
KMMessageProducer.hsetPriority:
Sets the producer’s default priority.
- (void)setPriority:(int)defaultPriorityParameters
- defaultPriority
the message priority for this message producer; must be a value between 0 and 9
Discussion
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.
Exceptions
- KMJMSException
if the JMS provider fails to set the priority due to some internal error.
See Also
Declared In
KMMessageProducer.hsetTimeToLive:
Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
- (void)setTimeToLive:(long long)timeToLiveParameters
- timeToLive
the message time to live in milliseconds; zero is unlimited
Discussion
Time to live is set to zero by default.
Exceptions
- KMJMSException
if the JMS provider fails to set the time to live due to some internal error.
See Also
Declared In
KMMessageProducer.htimeToLive
Gets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
- (long long)timeToLiveReturn Value
the message time to live in milliseconds; zero is unlimited
Exceptions
- KMJMSException
if the JMS provider fails to get the time to live due to some internal error.
See Also
Declared In
KMMessageProducer.h