Package io.hekate.messaging.operation

Interface Broadcast<T>

Type Parameters:

T - Message type.

public interface Broadcast<T>

Broadcast operation.

This interface represents a one-way message broadcast operation of a MessagingChannel. This operation submits the same message to multiple remote nodes.

Acknowledgements

Messages can be broadcast with or without acknowledgements:

• If acknowledgements are enabled then this operation will be completed only when acknowledgements are received from all receiver
• If acknowledgements are disabled then this operation will be completed immediately once it is flushed to the network buffer

Usage Example

Typical use of this interface is:

1. Obtain an instance of this interface via the MessagingChannel.newBroadcast(Object) method call
2. Set options (if needed):
   • Acknowledgememt Mode
   • Operation Timeout
   • Affinity Key
   • Retry Policy
3. Execute this operation via the submit() method
4. Await for the execution result, if needed

MessagingChannel<String> channel = hekate.messaging().channel("example.channel", String.class);

BroadcastFuture<String> future = channel.newBroadcast("some-message") // Some dummy message.
    .withAckMode(AckMode.REQUIRED) // Set acknowledgement mode.
    .withTimeout(3, TimeUnit.SECONDS) // Timeout.
    .withAffinity("100500") // Some dummy affinity key.
    .withRetry(retry -> retry
        .whileError(err -> err.isCausedBy(IOException.class)) // Only if I/O error.
        .withFixedDelay(100) // Delay between retries.
        .maxAttempts(3) // Retry up to 3 times.
    )
    .submit(); // Asynchronously execute the operation.

future.join(); // Await for confirmations.

Shortcut Methods

MessagingChannel interface provides a set of synchronous and asynchronous shortcut methods for common use cases:

• MessagingChannel.broadcast(Object)
• MessagingChannel.broadcast(Object, AckMode)
• MessagingChannel.broadcast(Object, Object)
• MessagingChannel.broadcast(Object, Object, AckMode)
• MessagingChannel.broadcastAsync(Object)
• MessagingChannel.broadcastAsync(Object, AckMode)
• MessagingChannel.broadcastAsync(Object, Object)
• MessagingChannel.broadcastAsync(Object, Object, AckMode)

Method Summary

Modifier and Type	Method	Description
BroadcastFuture<T>	submit()	Asynchronously executes this operation.
default void	submit(BroadcastCallback<T> callback)	Asynchronously executes this operation and notifies the specified callback upon completion.
default BroadcastResult<T>	sync()	Synchronously executes this operation and returns the result.
default Broadcast<T>	withAck()	Sets acknowledgement mode to AckMode.REQUIRED.
Broadcast<T>	withAckMode(AckMode ackMode)	Acknowledgement mode.
Broadcast<T>	withAffinity(Object affinity)	Affinity key.
default Broadcast<T>	withNoAck()	Sets acknowledgement mode to AckMode.NOT_NEEDED.
Broadcast<T>	withRepeat(BroadcastRepeatCondition<T> condition)	Condition to repeat for the whole Broadcast operation.
Broadcast<T>	withRetry(BroadcastRetryConfigurer retry)	Retry policy.
Broadcast<T>	withTimeout(long timeout, TimeUnit unit)	Overrides the channel's default timeout value for this operation.

Method Detail

withAffinity

Broadcast<T> withAffinity(Object affinity)

Affinity key.

Specifying an affinity key ensures that all operation with the same key will always be transmitted over the same network connection and will always be processed by the same thread (if the cluster topology doesn't change).

Parameters:

affinity - Affinity key.

Returns:

This instance.

withTimeout

Broadcast<T> withTimeout(long timeout,
                         TimeUnit unit)

Overrides the channel's default timeout value for this operation.

If this operation can not complete at the specified timeout then this operation will end up in a MessageTimeoutException.

Specifying a negative or zero value disables the timeout check.

Parameters:

timeout - Timeout.

unit - Unit.

Returns:

This instance.

See Also:

MessagingChannelConfig.setMessagingTimeout(long)

withAckMode

Broadcast<T> withAckMode(AckMode ackMode)

Acknowledgement mode.

If this option is set to AckMode.REQUIRED then the receiver of this operation will send back an acknowledgement to indicate that this operation was successfully received. In such case the operation's callback/future will be notified only when such acknowledgement is received from all nodes (or if operation fails).

If this option is set to AckMode.NOT_NEEDED then operation will be assumed to be successful once the message gets flushed to the network buffer without any additional acknowledgements from receivers.

Default value of this option is AckMode.NOT_NEEDED.

Parameters:

ackMode - Acknowledgement mode.

Returns:

This instance.

withRetry

Broadcast<T> withRetry(BroadcastRetryConfigurer retry)

Retry policy.

This policy gets applied to each individual (per-node) message. For example, if message should be broadcasted to 3 nodes and an error happens while sending the message to the second node then this retry policy will be applied only to that particular failed message.

If retry logic should be implemented at the broadcast level (i.e. decide on whether to retry or not by looking at the whole BroadcastResult) please see the withRepeat(BroadcastRepeatCondition) method.

Parameters:

retry - Retry policy.

Returns:

This instance.

See Also:

MessagingChannelConfig.setRetryPolicy(GenericRetryConfigurer)

withRepeat

Broadcast<T> withRepeat(BroadcastRepeatCondition<T> condition)

Condition to repeat for the whole Broadcast operation.

If the specified condition evaluates to true then the whole Broadcast operation will be repeated from scratch, except for the following cases:

• Broadcast operation timed out (see withTimeout(long, TimeUnit))
• MessagingChannel's cluster topology is empty (i.e. no nodes to broadcast to)
• Hekate node is stopped

If one of the above is true then Broadcast will complete with whatever BroadcastResult it has.

Parameters:

condition - Condition.

Returns:

This instance.

See Also:

withRetry(BroadcastRetryConfigurer)

submit

BroadcastFuture<T> submit()

Asynchronously executes this operation.

Returns:

Future result of this operation.

submit

default void submit(BroadcastCallback<T> callback)

Asynchronously executes this operation and notifies the specified callback upon completion.

Parameters:

callback - Callback.

sync

default BroadcastResult<T> sync()
                         throws HekateException

Synchronously executes this operation and returns the result.

Returns:

Result.

Throws:

HekateException - If operations fails.

withAck

default Broadcast<T> withAck()

Sets acknowledgement mode to AckMode.REQUIRED.

Returns:

This instance.

See Also:

withAckMode(AckMode)

withNoAck

default Broadcast<T> withNoAck()

Sets acknowledgement mode to AckMode.NOT_NEEDED.

Returns:

This instance.

See Also:

withAckMode(AckMode)