[[Curator RPC Proxy|index.html]] / Usage

h1. Usage

h2. Thrift File

The first step in using the RPC Proxy is to process the Curator RPC Thrift file into your desired language/environment.
The current Curator RPC Thrift File can be found here: [[https://raw.githubusercontent.com/apache/curator/master/curator-x-rpc/src/main/thrift/curator.thrift]].
Details on using Apache Thrift can be found here: [[http://thrift.apache.org]].

h2. Prerequisites

It's assumed you are already familiar with ZooKeeper and Curator. Also, familiarity with writing Thrift applications is helpful.

h2. Services

Three Thrift Services are included with the Curator RPC:

||Service||Description||
|CuratorService|The main service for accessing the Curator APIs and recipes|
|EventService|Used to receive out\-of\-band messages for callbacks, watchers, etc. See [Events|events.html] for details.|
|DiscoveryService|Curator's ServiceDiscovery recipe|

h2. Concepts

h4. Projections

Many of the Curator RPC APIs refer to "projections" (e.g. CuratorProjection). A projection is an id that refers
to a real object instance inside of the RPC server. The projection is a "handle" or "cookie" that directly refers to that instance.

h4. Thrift Client Equals a Thread

It's important to remember that each thrift client is the equivalent of a system thread. i.e. you cannot have multiple outstanding
calls in multiple threads with a given client. For each thread, you should allocate a separate client. A Thrift Client maps directly
to a single TCP/IP socket.

h4. Event Loop

You must dedicate a separate thread for getting events via the Curator RPC [EventService|events.html]. Curator will report async results,
connection state changes, watcher triggers, etc. via this event loop.

h4. CuratorProjection Expiration

If you don't make an API call using a CuratorProjection within the [configured timeout|configuration.html] the projection instance
will be closed and any open recipes, etc. associated with it will be closed. NOTE: calls to the EventService will cause the
CuratorProjection to be "touched". So, as long as your event loop is running your CuratorProjection instance will be kept open.

h2. Initialization

After setting up Thrift, create a connection to the CuratorService and the EventService. If you plan on using Curator Discovery, create a connection
to DiscoveryService. Allocate a CuratorProjection instance and then start a thread watching events for that instance. Here is pseudo code:

{code}
CuratorService.Client curatorService = new CuratorService.Client()
EventService.Client eventService = new EventService.Client()

curatorProjection = curatorService.newCuratorProjection(name)

inThread => {
    while isOpen {
        event = eventService.getNextEvent(curatorProjection)
        ... process event ...
    }
}

... in your application shutdown
client.closeCuratorProjection(curatorProjection)
{code}

h2. Usage

Once initialized, use recipes/APIs as needed. Here is an example of using the lock recipe:

{code}
optionalLock = client.acquireLock(curatorProjection, "/mylock", 10000)
if optionalLock.lockProjection == null {
    // lock attempt failed. Throw exception, etc.
}
lockProjection = optionalLock.lockProjection

try
    // you now own the lock
finally
    client.closeGenericProjection(curatorProjection, lockProjection.id)
{code}

Here is an example of using the path cache:

{code}
cacheProjection = client.startPathChildrenCache(curatorProjection, "/path", true, false, BUILD_INITIAL_CACHE)

...

data = client.getPathChildrenCacheDataForPath(curatorProjection, cacheProjection, "/path/child")

...

// in your event loop, you will get events for the cache. e.g.
event = eventService.getNextEvent(curatorProjection)
if event.type == PATH_CHILDREN_CACHE {
    if event.childrenCacheEvent.type == CHILD_UPDATED {
        // node described by event.childrenCacheEvent.data has changed
        // event.childrenCacheEvent.cachedPath is the path that was passed to startPathChildrenCache()
    }
}

...

// when done with the cache, close it
client.closeGenericProjection(curatorProjection, cacheProjection.id)
{code}

h2. Reference

See [[API Reference Page|reference.html]] for the API reference.
