org.apache.ignite.internal.managers.discovery

## Interface DiscoveryCustomMessage

All Superinterfaces:
  Serializable

All Known Subinterfaces:
  DiscoveryServerOnlyCustomMessage, SnapshotDiscoveryMessage

All Known Implementing Classes:
  AbstractContinuousMessage, CacheAffinityChangeMessage, CacheStatisticsModeChangeMessage, ChangeGlobalStateFinishMessage, ChangeGlobalStateMessage, ClientCacheChangeDiscoveryMessage, ClientCacheChangeDummyDiscoveryMessage, DynamicCacheChangeBatch, MappingAcceptedMessage, MappingProposedMessage, MetadataUpdateAcceptedMessage, MetadataUpdateProposedMessage, SchemaAbstractDiscoveryMessage, SchemaFinishDiscoveryMessage, SchemaProposeDiscoveryMessage, StartRoutineAckDiscoveryMessage, StartRoutineDiscoveryMessage, StartRoutineDiscoveryMessageV2, StopRoutineAckDiscoveryMessage, StopRoutineDiscoveryMessage, TxTimeoutOnPartitionMapExchangeChangeMessage, UserAcceptedMessage, UserProposedMessage, WalStateAbstractMessage, WalStateFinishMessage, WalStateProposeMessage

    public interface DiscoveryCustomMessage
    extends Serializable

DiscoveryCustomMessage messages are handled by discovery protocol which provides some guarantees around them. When some node sends DiscoveryCustomMessage with `GridDiscoveryManager.sendCustomEvent(DiscoveryCustomMessage)` call, message firstly goes to current coordinator, is verified there and after that gets sent to the cluster. Only after verification it is delivered to listeners on all nodes starting from coordinator. To register a listener `GridDiscoveryManager.setCustomEventListener(Class, CustomEventListener)` method is used. Discovery protocol guarantees include:

1. All discovery messages are observed by all nodes in exactly the same order, it is guaranteed by handling them in single-threaded mode.
2. New server node joining process in default implementation involves two passes of different messages across the cluster: `TcpDiscoveryNodeAddedMessage` and `TcpDiscoveryNodeAddFinishedMessage` messages. It is guaranteed that all discovery messages observed by coordinator in between these two messages are reordered and guaranteed to be delivered to newly joined node.

Yet there are some features and limitations one should be aware of when using custom discovery messaging mechanism:

1. Guarantee #2 doesn't encompass DiscoveryCustomMessages created automatically on `ackMessage()` method call. If there were messages of this type in between TcpDiscoveryNodeAddedMessage and TcpDiscoveryNodeAddFinishedMessage messages, they won't be delivered to new joiner node.
2. There is no guarantee for a given DiscoveryCustomMessage to be delivered only once. It is possible that because of node failure antecedent node will resend messages it thinks were not sent by failed node. Duplicate messages are not filtered out on receiver side.
3. DiscoveryCustomMessages are delivered to client nodes in asynchronous fashion as clients don't participate in the cluster ring.
4. Any blocking operations like obtaining locks or doing I/O must be avoided in message handlers as they may lead to deadlocks and cluster failures.

### Method Summary

All Methods Instance Methods Abstract Methods
`DiscoveryCustomMessage` `ackMessage()` Called when custom message has been handled by all nodes.
`DiscoCache` `createDiscoCache(GridDiscoveryManager mgr, AffinityTopologyVersion topVer, DiscoCache discoCache)` Creates new discovery cache if message caused topology version change.
`IgniteUuid` `id()`
`boolean` `isMutable()`
`boolean` `stopProcess()` See `DiscoverySpiCustomMessage.stopProcess()`.

### Method Detail

#### id

    IgniteUuid id()

Returns:
  Unique custom message ID.

#### ackMessage

    @Nullable
    DiscoveryCustomMessage ackMessage()

Called when custom message has been handled by all nodes.

Returns:
  Ack message or `null` if ack is not required.

#### isMutable

    boolean isMutable()

Returns:
  `True` if message can be modified during listener notification. Changes will be sent to next nodes.

#### stopProcess

    boolean stopProcess()

See `DiscoverySpiCustomMessage.stopProcess()`.

Returns:
  `True` if message should not be sent to others nodes after it was processed on coordinator.

#### createDiscoCache

    DiscoCache createDiscoCache(GridDiscoveryManager mgr,
                                AffinityTopologyVersion topVer,
                                DiscoCache discoCache)

Creates new discovery cache if message caused topology version change.

Parameters:
  `mgr` - Discovery manager.
  `topVer` - New topology version.
  `discoCache` - Current discovery cache.
Returns:
  Reused discovery cache.

2018 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 2.5.0
Release Date | : May 23 2018