[[leadership-event-handling]]
= Leadership Event Handling

Groups of endpoints can be started and stopped based on leadership being granted or revoked, respectively.
This is useful in clustered scenarios where shared resources must be consumed by only a single instance.
An example of this is a file inbound channel adapter that is polling a shared directory.
(See xref:file/reading.adoc[Reading Files]).

To participate in a leader election and be notified when elected leader, when leadership is revoked, or on failure to acquire the resources to become leader, an application creates a component in the application context called a "`leader initiator`".
Normally, a leader initiator is a `SmartLifecycle`, so it starts (optionally) when the context starts and then publishes notifications when leadership changes.
You can also receive failure notifications by setting the `publishFailedEvents` to `true` (starting with version 5.0), for cases when you want to take a specific action if a failure occurs.
By convention, you should provide a `Candidate` that receives the callbacks.
You can also revoke the leadership through a `Context` object provided by the framework.
Your code can also listen for `o.s.i.leader.event.AbstractLeaderEvent` instances (the super class of `OnGrantedEvent` and `OnRevokedEvent`) and respond accordingly (for instance, by using a `SmartLifecycleRoleController`).
The events contain a reference to the `Context` object.
The following listing shows the definition of the `Context` interface:

[source, java]
----
public interface Context {

	boolean isLeader();

	void yield();

	String getRole();

}
----

Starting with version 5.0.6, the context provides a reference to the candidate's role.

Spring Integration provides a basic implementation of a leader initiator that is based on the `LockRegistry` abstraction.
To use it, you need to create an instance as a bean, as the following example shows:

[source, java]
----
@Bean
public LockRegistryLeaderInitiator leaderInitiator(LockRegistry locks) {
    return new LockRegistryLeaderInitiator(locks);
}
----

If the lock registry is implemented correctly, there is only ever at most one leader.
If the lock registry also provides locks that throw exceptions (ideally, `InterruptedException`) when they expire or are broken, the duration of the leaderless periods can be as short as is allowed by the inherent latency in the lock implementation.
By default, the `busyWaitMillis` property adds some additional latency to prevent CPU starvation in the (more usual) case that the locks are imperfect, and you only know they expired when you try to obtain one again.

See xref:zookeeper.adoc#zk-leadership[Zookeeper Leadership Event Handling] for more information about leadership election and events that use Zookeeper.
See xref:hazelcast.adoc#hazelcast-leader-election[Hazelcast Leadership Event Handling] for more information about leadership election and events that use Hazelcast.