View source for Gyrex/Development Space/ZooKeeper Interaction

{{Gyrex}}
<div style="margin-right:22em">
This article provides insights into how Gyrex interacts with ZooKeeper.


== Prerequisites ==
Please read about [http://zookeeper.apache.org/ Apache ZooKeeper]. This article may use terminology which is specific to ZooKeeper and also goes right into the details. You should also be familiar with:
* Equinox Extension Registry
* Gyrex Roles
* Equinox Applications (aka. Eclipse or OSGi Applications)

== Summary ==
ZooKeeper is used in Gyrex in order to implement the core functionality of clustering in Gyrex:
* Which node belongs to the cloud? (Membership)
* Which node offers which functionality in the cloud? (Coordination)

ZooKeeper also offers ''receipts'' which allow to implement additional functionality. Based on those receipts the following additional capabilities are also implemented in Gyrex:
* [[Gyrex/Development Space/Cloud Preferences|Cloud Preferences Scope]] which stores preferences in ZooKeeper
* [[Gyrex/Development Space/Queue Service|Queue Service]] (similar to Amazon SQS) which allows to post and receive messages with a visibility timout
* [[Gyrex/Development Space/Lock Service|Lock Service]] which allows to create distributed locks (based on ephemeral as well as persistent nodes)

In order to ease development, an embedded ZooKeeper is started automatically in development mode (which is the default operation mode).
</div>


== ZooKeeper Gate ==
The ZooKeeper gate is the central point in Gyrex which coordinates all communication to ZooKeeper. It is responsible for establishing and maintaining a ZooKeeper connection. Listeners can be registered with the gate in order to participate in the connection life cycle.

=== Gate Manager ===
The gate itself is maintained by a gate manager. This is an Equinox IApplication which must be started in order to enable participation of the Gyrex instance in the cloud. The application is contributed as an extension to the Equinox Extension Registry. Additionally a Gyrex Role extension is defined which ensures that the gate manager application is started when the role is activated.

As long as the gate manager application is running it will automatically re-connect the gate when the connection to ZooKeeper is lost. Strictly speaking, the old gate will be disposed and a new one will be created. But all active listeners will be retained and notified properly.

=== Gate Life-cycle ===
The gate life-cycle consists of the following three states:
* UP
* DOWN
* RECOVERING 

==== UP ====
This indicates a successful connection to ZooKeeper. A session has been establish (or recovered) and the system can interact with ZooKeeper.

==== DOWN ====
This indicates that the instance is not connected with ZooKeeper and has no valid session. No interaction with ZooKeeper is possible.

==== RECOVERING ====
This indicates that the instance is in the process of reestablishing a connection to ZooKeeper and recovering a session. No interaction with ZooKeeper is possible.

If '''and only if''' the session was recovered successfully, the gate will go right into the UP state. In all other cases, the gate will go into the DOWN state. The timeout for RECOVERING is closely related to the ZooKeeper session timeout.


== Cloud State ==
The Cloud State is responsible for capturing the state of the node in the cloud. It's life-cycle is bound to bundle start and stop of the cloud bundle. Once active it hooks with ZooKeeper gate and reacts on the connection events. 

The following cloud states exist:
* ONLINE
* OFFLINE
* INTERRUPTED

Changes to the cloud state of a node will be published as OSGi event to corresponding topics.

=== ONLINE ===
This state indicates that the node operates successfully in the cloud. When the state changed to ONLINE all configured cloud server roles will be activated (which might start additional bundles and/or Equinox applications).

In order for a node to become online '''''all''''' of the following conditions must be met:
* The ZooKeeper gate must have established a valid ZooKeeper connection (i.e., gate must be UP).
* The node must be approved.

=== OFFLINE ===
This state indicates that the node does not operate in the cloud. When the state changed to OFFLINE all previously activated cloud server roles will be de-activated (which might stop some bundles and/or Equinox applications).

In order for a node to become offline '''''any''''' of the following conditions must be met:
* The ZooKeeper gate must be DOWN.
* The node must not be approved, i.e. pending.

=== INTERRUPTED ===
This state indicates that the node was previously online but lost the connection to the cloud. When the state changed to INTERRUPTED some of the previously activated cloud server roles will be de-activated (which might stop some bundles and/or Equinox applications).

In order for a node to become interrupted '''''all''''' of the following conditions must be met:
* The ZooKeeper gate must be RECOVERING.
* The node must be be approved.
* The node state was ONLINE.

== ZooKeeper Based Services ==
ZooKeeper Based Services is a common implementation base for ZooKeeper based functionality. It offers things like active-state management, re-tries and shutdown/close handling on disconnect. However, ZooKeeper Based Services are not intended to follow the ZooKeeper gate life-cycle. Typically, they are services created upon application request *if* the ZooKeeper gate is available and they close/shutdown automatically when they are no longer needed or the ZooKeeper connection is lost.

Examples of those services are:
* [[Gyrex/Development Space/Cloud Preferences|Cloud Preferences Scope]]
* [[Gyrex/Development Space/Lock Service|Lock Service]]
* [[Gyrex/Development Space/Queue Service|Queue Service]]