io.openmessaging.producer

Interface Producer

All Superinterfaces:

MessageFactory, ServiceLifecycle

public interface Producer
extends MessageFactory, ServiceLifecycle

A Producer is a simple object used to send messages on behalf of a MessagingAccessPoint. An instance of Producer is created by calling the MessagingAccessPoint.createProducer() method.

It provides various send methods to send a message to a specified destination, which is a Queue in OMS.

send(Message) means send a message to the destination synchronously, the calling thread will block until the send request complete.

sendAsync(Message) means send a message to the destination asynchronously, the calling thread won't block and will return immediately. Since the send call is asynchronous it returns a Future for the send result.

Since:

OMS 1.0.0

Version:

OMS 1.0.0

Method Summary

Modifier and Type	Method and Description
void	addInterceptor(ProducerInterceptor interceptor) Adds a ProducerInterceptor to intercept send operations of producer.
KeyValue	attributes() Returns the attributes of this Producer instance.
BatchMessageSender	createBatchMessageSender() Creates a BatchMessageSender to send message in batch manner.
void	removeInterceptor(ProducerInterceptor interceptor) Removes a ProducerInterceptor
SendResult	send(Message message) Sends a message to the specified destination synchronously, the destination should be preset to Message.sysHeaders(), other header fields as well.
SendResult	send(Message message, KeyValue attributes) Sends a message to the specified destination synchronously, using the specified attributes, the destination should be preset to Message.sysHeaders(), other header fields as well.
SendResult	send(Message message, LocalTransactionExecutor branchExecutor, KeyValue attributes) Sends a transactional message to the specified destination synchronously, using the specified attributes, the destination should be preset to Message.sysHeaders(), other header fields as well.
Future<SendResult>	sendAsync(Message message) Sends a message to the specified destination asynchronously, the destination should be preset to Message.sysHeaders(), other header fields as well.
Future<SendResult>	sendAsync(Message message, KeyValue attributes) Sends a message to the specified destination asynchronously, using the specified attributes, the destination should be preset to Message.sysHeaders(), other header fields as well.
void	sendOneway(Message message) Sends a message to the specified destination in one way, the destination should be preset to Message.BuiltinKeys, other header fields as well.
void	sendOneway(Message message, KeyValue properties) Sends a message to the specified destination in one way, using the specified attributes, the destination should be preset to Message.BuiltinKeys, other header fields as well.

Methods inherited from interface io.openmessaging.MessageFactory

createBytesMessage

Methods inherited from interface io.openmessaging.ServiceLifecycle

shutdown, startup

Method Detail

attributes

KeyValue attributes()

Returns the attributes of this Producer instance. Changes to the return KeyValue are not reflected in physical Producer.

There are some standard attributes defined by OMS for Producer:

• OMSBuiltinKeys.PRODUCER_ID, the unique producer id for a producer instance.
• OMSBuiltinKeys.OPERATION_TIMEOUT, the default timeout period for operations of Producer.

Returns:

the attributes

send

SendResult send(Message message)

Sends a message to the specified destination synchronously, the destination should be preset to Message.sysHeaders(), other header fields as well.

Parameters:

message - a message will be sent

Returns:

the successful SendResult

Throws:

OMSMessageFormatException - if an invalid message is specified.

OMSTimeOutException - if the given timeout elapses before the send operation completes

OMSRuntimeException - if the Producer fails to send the message due to some internal error.

send

SendResult send(Message message,
                KeyValue attributes)

Sends a message to the specified destination synchronously, using the specified attributes, the destination should be preset to Message.sysHeaders(), other header fields as well.

Parameters:

message - a message will be sent

attributes - the specified attributes

Returns:

the successful SendResult

Throws:

OMSMessageFormatException - if an invalid message is specified.

OMSTimeOutException - if the given timeout elapses before the send operation completes

OMSRuntimeException - if the Producer fails to send the message due to some internal error.

send

SendResult send(Message message,
                LocalTransactionExecutor branchExecutor,
                KeyValue attributes)

Sends a transactional message to the specified destination synchronously, using the specified attributes, the destination should be preset to Message.sysHeaders(), other header fields as well.

A transactional message will be exposed to consumer if and only if the local transaction branch has been committed, or be discarded if local transaction has been rolled back.

Parameters:

message - a transactional message will be sent

branchExecutor - local transaction executor associated with the message

attributes - the specified attributes

Returns:

the successful SendResult

Throws:

OMSMessageFormatException - if an invalid message is specified.

OMSTimeOutException - if the given timeout elapses before the send operation completes

OMSRuntimeException - if the Producer fails to send the message due to some internal error.

sendAsync

Future<SendResult> sendAsync(Message message)

Sends a message to the specified destination asynchronously, the destination should be preset to Message.sysHeaders(), other header fields as well.

The returned Promise will have the result once the operation completes, and the registered FutureListener will be notified, either because the operation was successful or because of an error.

Parameters:

message - a message will be sent

Returns:

the Promise of an asynchronous message send operation.

See Also:

Future, FutureListener

sendAsync

Future<SendResult> sendAsync(Message message,
                             KeyValue attributes)

Sends a message to the specified destination asynchronously, using the specified attributes, the destination should be preset to Message.sysHeaders(), other header fields as well.

The returned Promise will have the result once the operation completes, and the registered FutureListener will be notified, either because the operation was successful or because of an error.

Parameters:

message - a message will be sent

attributes - the specified attributes

Returns:

the Promise of an asynchronous message send operation.

See Also:

Future, FutureListener

sendOneway

void sendOneway(Message message)

Sends a message to the specified destination in one way, the destination should be preset to Message.BuiltinKeys, other header fields as well.

There is no Promise related or RuntimeException thrown. The calling thread doesn't care about the send result and also have no context to get the result.

Parameters:

message - a message will be sent

sendOneway

void sendOneway(Message message,
                KeyValue properties)

Sends a message to the specified destination in one way, using the specified attributes, the destination should be preset to Message.BuiltinKeys, other header fields as well.

There is no Promise related or RuntimeException thrown. The calling thread doesn't care about the send result and also have no context to get the result.

Parameters:

message - a message will be sent

properties - the specified userHeaders

createBatchMessageSender

BatchMessageSender createBatchMessageSender()

Creates a BatchMessageSender to send message in batch manner.

Returns:

a BatchMessageSender instance

addInterceptor

void addInterceptor(ProducerInterceptor interceptor)

Adds a ProducerInterceptor to intercept send operations of producer.

Parameters:

interceptor - a producer interceptor

removeInterceptor

void removeInterceptor(ProducerInterceptor interceptor)

Removes a ProducerInterceptor

Parameters:

interceptor - a producer interceptor will be removed