io.vertx.spi.cluster.zookeeper.package-info Maven / Gradle / Ivy

Go to download
/*
 *  Copyright (c) 2011-2016 The original author or authors
 *  ------------------------------------------------------
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *       The Eclipse Public License is available at
 *       http://www.eclipse.org/legal/epl-v10.html
 *
 *       The Apache License v2.0 is available at
 *       http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */

/**
 * = Zookeeper Cluster Manager
 *
 * This is a cluster manager implementation for Vert.x that uses http://zookeeper.apache.org/[Zookeeper].
 *
 * It implements interfaces of vert.x cluster totally. So you can using it to instead of vertx-hazelcast if you want.
 * This implementation is packaged inside:
 *
 * [source,xml,subs="+attributes"]
 * ----
 * 
 * io.vertx
 * vertx-zookeeper
 * ${maven.version}
 * 
 * ----
 *
 * In Vert.x a cluster manager is used for various functions including:
 *
 * * Discovery and group membership of Vert.x nodes in a cluster
 * * Maintaining cluster wide topic subscriber lists (so we know which nodes are interested in which event busaddresses)
 * * Distributed Map support
 * * Distributed Locks
 * * Distributed Counters
 *
 * Cluster managers *do not* handle the event bus inter-node transport, this is done directly by Vert.x with TCP connections.
 *
 * == How to work
 * We are using http://curator.apache.org/[Apache Curator] framework rather than zookeeper client directly, so
 * we have a dependency for libraries used in Curator such as `guava`, `slf4j` and of course `zookeeper`.
 *
 * Since ZK using tree dictionary to store data, we can take root path as namespace default root path is `io.vertx` which in default-zookeeper.json.
 * and there are another 5 sub path to record other information for functions in vert.x cluster manager, all you can change the path is `root path`.
 *
 * you can find all the vert.x node information in path of `/io.vertx/cluster/nodes/`,
 * `/io.vertx/asyncMap/$name/` record all the `AsyncMap` you created with `io.vertx.core.shareddata.AsyncMap` interface.
 * `/io.vertx/asyncMultiMap/$name/` record all the `AsyncMultiMap` you created with `io.vertx.core.spi.cluster.AsyncMultiMap` interface.
 * `/io.vertx/locks/` record distributed Locks information.
 * `/io.vertx/counters/` record distributed Count information.
 *
 * == Using this cluster manager
 *
 * If you are using Vert.x from the command line, the jar corresponding to this cluster manager (it will be named `vertx-zookeeper-${maven.version}`.jar`
 * should be in the `lib` directory of the Vert.x installation.
 *
 * If you want clustering with this cluster manager in your Vert.x Maven or Gradle project then just add a dependency to
 * the artifact: `io.vertx:vertx-zookeeper:${version}` in your project.
 *
 * If the jar is on your classpath as above then Vert.x will automatically detect this and use it as the cluster manager.
 * Please make sure you don't have any other cluster managers on your classpath or Vert.x might
 * choose the wrong one.
 *
 * You can also specify the cluster manager programmatically if you are embedding Vert.x by specifying it on the options
 * when you are creating your Vert.x instance, for example:
 *
 * [source, $lang]
 * ----
 * {@link example.Examples#example1()}
 * ----
 *
 * == Configuring this cluster manager
 *
 * Usually the cluster manager is configured by a file
 * https://github.com/vert-x3/vertx-zookeeper/blob/master/src/main/resources/default-zookeeper.json[`default-zookeeper.json`]
 * which is packaged inside the jar.
 *
 * If you want to override this configuration you can provide a file called `zookeeper.json` on your classpath and this
 * will be used instead. If you want to embed the `zookeeper.json` file in a fat jar, it must be located at the root of the
 * fat jar. If it's an external file, the **directory** containing the file must be added to the classpath. For
 * example, if you are using the _launcher_ class from Vert.x, the classpath enhancement can be done as follows:
 *
 * [source]
 * ----
 * # If the zookeeper.json is in the current directory:
 * java -jar ... -cp . -cluster
 * vertx run MyVerticle -cp . -cluster
 *
 * # If the zookeeper.json is in the conf directory
 * java -jar ... -cp conf -cluster
 * ----
 *
 * Another way to override the configuration is by providing the system property `vertx.zookeeper.conf` with a
 * location:
 *
 * [source]
 * ----
 * # Use a cluster configuration located in an external file
 * java -Dvertx.zookeeper.config=./config/my-zookeeper-conf.json -jar ... -cluster
 *
 * # Or use a custom configuration from the classpath
 * java -Dvertx.zookeeper.config=classpath:my/package/config/my-cluster-config.json -jar ... -cluster
 * ----
 *
 * The `vertx.zookeeper.config` system property, when present, overrides any `zookeeper.json` from the classpath, but if
 * loading
 * from this system property fails, then loading falls back to either `zookeeper.json` or the Zookeeper default configuration.
 *
 * The configuration file is described in detail in `default-zookeeper.json`'s comment.
 *
 * You can also specify configuration programmatically if embedding:
 *
 * [source,java]
 * ----
 * {@link example.Examples#example2()}
 * ----
 *
 * IMPORTANT: You can also configure the zookeeper hosts using the `vertx.zookeeper.hosts` system property.
 *
 * === Enabling logging
 *
 * When trouble-shooting clustering issues with Zookeeper it's often useful to get some logging output from Zookeeper
 * to see if it's forming a cluster properly. You can do this (when using the default JUL logging) by adding a file
 * called `vertx-default-jul-logging.properties` on your classpath. This is a standard java.util.logging (JUL)
 * configuration file. Inside it set:
 *
 * ----
 * org.apache.zookeeper.level=INFO
 * ----
 *
 * and also
 *
 * ----
 * java.util.logging.ConsoleHandler.level=INFO
 * java.util.logging.FileHandler.level=INFO
 * ----
 *
 * == About Zookeeper version
 * We use Curator ${curator.version}, as Zookeeper latest stable is 3.4.8 so we do not support any features of 3.5.x
 */


@Document(fileName = "index.adoc")
package io.vertx.spi.cluster.zookeeper;

import io.vertx.docgen.Document;