zookeeper.hpp

Go to the documentation of this file.

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef __MESOS_ZOOKEEPER_HPP__
#define __MESOS_ZOOKEEPER_HPP__

#include <stdint.h>

#include <zookeeper.h>

#ifdef __WINDOWS__
// NOTE: We need to undefine this macro to prevent it from bleeding
// into our code and thereby break compilation of our namespaced ACLs.
// This macro is defined in zookeeper/src/c/include/winconfig.h.
#undef ACL
#endif // __WINDOWS__

#include <string>
#include <vector>

#include <stout/duration.hpp>


/* Forward declarations of classes we are using. */
class ZooKeeper;
class ZooKeeperProcess;

class Watcher
{
public:
  virtual void process(
      int type,
      int state,
      int64_t sessionId,
      const std::string& path) = 0;

  virtual ~Watcher() {}
};


/*
 * TODO(benh): Clean up this documentation.
 *
 * This is the main class of ZooKeeper client library. To use a
 * ZooKeeper service, an application must first instantiate an object
 * of ZooKeeper class. All the iterations will be done by calling the
 * methods of ZooKeeper class.
 *
 * Once a connection to a server is established, a session ID is
 * assigned to the client. The client will send heart beats to the
 * server periodically to keep the session valid.
 *
 * The application can call ZooKeeper APIs through a client as long as
 * the session ID of the client remains valid.
 *
 * If for some reason, the client fails to send heart beats to the
 * server for a prolonged period of time (exceeding the sessionTimeout
 * value, for instance), the server will expire the session, and the
 * session ID will become invalid. The client object will no longer be
 * usable. To make ZooKeeper API calls, the application must create a
 * new client object.
 *
 * If the ZooKeeper server the client currently connects to fails or
 * otherwise does not respond, the client will automatically try to
 * connect to another server before its session ID expires. If
 * successful, the application can continue to use the client.
 *
 * Some successful ZooKeeper API calls can leave watches on the "data
 * nodes" in the ZooKeeper server. Other successful ZooKeeper API
 * calls can trigger those watches. Once a watch is triggered, an
 * event will be delivered to the client which left the watch at the
 * first place. Each watch can be triggered only once. Thus, up to one
 * event will be delivered to a client for every watch it leaves.
 *
 * A client needs an object of a class implementing Watcher interface
 * for processing the events delivered to the client. When a client
 * drops current connection and re-connects to a server, all the
 * existing watches are considered as being triggered but the
 * undelivered events are lost. To emulate this, the client will
 * generate a special event to tell the event handler a connection has
 * been dropped. This special event has type EventNone and state
 * sKeeperStateDisconnected.
 */
class ZooKeeper
{
public:
  ZooKeeper(const std::string& servers,
            const Duration& sessionTimeout,
            Watcher* watcher);

  ~ZooKeeper();

  int getState();

  int64_t getSessionId();

  Duration getSessionTimeout() const;

  int authenticate(const std::string& scheme, const std::string& credentials);

  int create(
      const std::string& path,
      const std::string& data,
      const ACL_vector& acl,
      int flags,
      std::string* result,
      bool recursive = false);

  int remove(const std::string& path, int version);

  int exists(const std::string& path, bool watch, Stat* stat);

  int get(
      const std::string& path,
      bool watch,
      std::string* result,
      Stat* stat);

  int getChildren(
      const std::string& path,
      bool watch,
      std::vector<std::string>* results);

  int set(const std::string& path, const std::string& data, int version);

  std::string message(int code) const;

  bool retryable(int code);


protected:
  /* Underlying implementation (pimpl idiom). */
  ZooKeeperProcess* process;

private:
  /* ZooKeeper instances are not copyable. */
  ZooKeeper(const ZooKeeper& that);
  ZooKeeper& operator=(const ZooKeeper& that);
};


#endif /* __MESOS_ZOOKEEPER_HPP__ */