You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@curator.apache.org by ra...@apache.org on 2014/02/23 08:15:38 UTC
[1/2] git commit: wip
Repository: curator
Updated Branches:
refs/heads/CURATOR-88 a4ca2d5a9 -> 938f3748d
wip
Project: http://git-wip-us.apache.org/repos/asf/curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/037a4675
Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/037a4675
Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/037a4675
Branch: refs/heads/CURATOR-88
Commit: 037a46755fbe60a7b2da22d45524eac72c7e2535
Parents: a4ca2d5
Author: randgalt <ra...@apache.org>
Authored: Sun Feb 23 12:28:28 2014 +0530
Committer: randgalt <ra...@apache.org>
Committed: Sun Feb 23 12:28:28 2014 +0530
----------------------------------------------------------------------
.../src/site/confluence/index.confluence | 3 +-
.../org/apache/curator/x/rest/api/Session.java | 9 ++-
.../src/site/confluence/build.confluence | 43 ++++++++++++
.../src/site/confluence/client.confluence | 66 +++++++++++++++++++
.../src/site/confluence/deploy.confluence | 12 ++++
.../src/site/confluence/entities.confluence | 2 -
.../src/site/confluence/index.confluence | 28 ++------
.../src/site/confluence/status.confluence | 8 ++-
.../src/site/resources/images/client-all.png | Bin 0 -> 96004 bytes
.../site/resources/images/client-requests.png | Bin 0 -> 134807 bytes
.../src/site/resources/images/client.png | Bin 134807 -> 99026 bytes
11 files changed, 143 insertions(+), 28 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-discovery-server/src/site/confluence/index.confluence
----------------------------------------------------------------------
diff --git a/curator-x-discovery-server/src/site/confluence/index.confluence b/curator-x-discovery-server/src/site/confluence/index.confluence
index 2ff1b01..e0c7737 100644
--- a/curator-x-discovery-server/src/site/confluence/index.confluence
+++ b/curator-x-discovery-server/src/site/confluence/index.confluence
@@ -87,4 +87,5 @@ h2. getAny
*Description:* {name} is the service name. Return a random instance from the given service or 404.
h2. JSON specs
-The JSON specifications for the REST entities are documented here: https://git-wip-us.apache.org/repos/asf?p=curator.git;a=blob_plain;f=curator-x-discovery-server/README.txt;hb=HEAD
+The JSON specifications for the REST entities are documented here:
+[[https://git-wip-us.apache.org/repos/asf?p=curator.git;a=blob\_plain;f=curator-x-discovery-server/README.txt;hb=HEAD]]
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/Session.java
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/Session.java b/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/Session.java
index 1a487f8..f8bf80d 100644
--- a/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/Session.java
+++ b/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/Session.java
@@ -75,7 +75,7 @@ public class Session implements Closeable
if ( elapsedSinceLastUse > sessionLengthMs )
{
String id = mapEntry.getKey();
- pushMessage(new StatusMessage(Constants.EXPIRED, id, entry.thing.getClass().getSimpleName(), ""));
+ pushMessage(new StatusMessage(Constants.EXPIRED, id, getSimpleName(entry), ""));
log.warn(String.format("Expiring object. Elapsed time: %d, id: %s, Class: %s", elapsedSinceLastUse, id, entry.thing.getClass().getName()));
things.remove(id);
@@ -142,4 +142,11 @@ public class Session implements Closeable
}
return null;
}
+
+ private static String getSimpleName(Entry entry)
+ {
+ String simpleName = entry.thing.getClass().getSimpleName();
+ String[] value = simpleName.split("\\.");
+ return (value.length > 0) ? value[0] : simpleName;
+ }
}
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/confluence/build.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/build.confluence b/curator-x-rest/src/site/confluence/build.confluence
new file mode 100644
index 0000000..0e9bb23
--- /dev/null
+++ b/curator-x-rest/src/site/confluence/build.confluence
@@ -0,0 +1,43 @@
+[[Curator REST Proxy|index.html]] / Building and Packaging
+
+h1. Building and Packaging
+
+The Curator REST Proxy can be packaged as a standalone application or incorporated into your own custom application.
+
+h2. Standalone
+
+For the standalone version, the excellent [[Dropwizard|http://dropwizard.codahale.com/]] is used. The standalone version
+is built via Apache Maven. To build:
+
+# Download this [[Maven pom file|https://git-wip-us.apache.org/repos/asf?p=curator.git;a=blob\_plain;f=curator-x-rest/src/main/resources/maven/pom.xml;hb=CURATOR-88]] to
+a new empty directory
+# cd to that directory
+# execute: {{mvn clean package}}
+# run the application: {{java -jar target/curator-rest-application-N.N.N.jar}} (replace N.N.N with the version)
+
+By default, the proxy tries to connect to a local ZooKeeper instance on port 2181. You can customize the proxy's configuration by using Dropwizard's
+configuration mechanism. These are the configuration values for the Curator REST Proxy:
+
+||Name||Default||Description||
+|connection-string|localhost:2181|The ZooKeeper connection string to use|
+|session-length-ms|1 minute|The max time in milliseconds before ephemerals, locks, etc. are expired. Also used for session length when creating the CuratorFramework instance.|
+|connection-timeout-ms|15 seconds|Used for connection timeout when creating the CuratorFramework instance.|
+|retry-base-sleep-ms|100|An ExponentialBackoffRetry is used. This is baseSleepTimeMs for that retry.|
+|retry-qty|3|An ExponentialBackoffRetry is used. This is retryQty for that retry.|
+
+To change the defaults, create either a JSON or YML file with the new values that you want. E.g.
+
+{code}
+{
+ "connection-string":"foo:2181,bar:2181"
+}
+{code}
+
+Then, pass the file to the application:
+
+{{java -jar target/curator-rest-application-N.N.N.jar server path/to/my.json}}
+
+h2. Integration
+
+The proxy must be combined with a JAX-RS implementation (Jersey, etc.) and a container (Tomcat, Jetty, etc.). Look at
+CuratorRestBundle.java for an example of how to do this.
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/confluence/client.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/client.confluence b/curator-x-rest/src/site/confluence/client.confluence
new file mode 100644
index 0000000..9f9054e
--- /dev/null
+++ b/curator-x-rest/src/site/confluence/client.confluence
@@ -0,0 +1,66 @@
+[[Curator REST Proxy|index.html]] / Writing Your REST Client
+
+h1. Writing Your REST Client
+
+The Curator REST Proxy is a standard REST server and, thus, you can use any standard REST client library. Many of the proxy APIs are stateless
+and, thus, it's not important which Curator REST Proxy instance you send requests to. However, some of the Proxy's APIs _are stateful_. For the Client APIs, if you
+make a call that is either asynchronous, sets a watcher, or creates an ephemeral node, there is some state that is stored. In these cases,
+you must periodically send a status heartbeat and examine the resulting messages. This status heartbeat must be sent to the *same server*
+to which you originated the request. E.g. if you have 3 Curator REST Proxies A, B and C and execute a lock API to server B, you must
+periodically send a status with the lock's ID to server B (see graphic for an illustration). See the section below on Managing
+Status for more details. Also, see the [[APIs|apis.html]] page for additional details.
+
+!images/client-requests.png!
+
+h2. Handling Stateful APIs
+
+For the stateful APIs, you should keep an record for each active API. The record should contain the Curator REST Proxy instance
+that fulfilled the API call and the response ID that was returned. You must periodically send these IDs using the POST version
+of the status API (see below) to avoid the Proxy expiring the APIs product (watcher, lock, etc.). See the lock example below.
+
+h2. Managing Status
+
+For each Curator REST Proxy in your cluster, you must periodically call the status API to get pending messages and examine the current connection
+state. The status APIs are:
+
+||URL||Method||Request Entity||Response Entity||Description||
+|/curator/v1/client/status|GET|n/a|Status|Call to get the status of the Curator connection as well as any pending messages.|
+|/curator/v1/client/status|POST|List of string ids|Status|Call to get the status of the Curator connection as well as any pending messages. Additionally, stateful instances with the specified IDs are "touched" thus preventing timeout expiration.|
+
+The returned Status entity schema is:
+
+||Field||Type||Description||
+|state|string|This instance's Curator connection state. One of: "connected", "suspended", or "lost". If the state is other than "connected" you must assume that any open locks and/or watchers are no longer valid.|
+|messages|array of StatusMessages|Any pending messages from this instance.|
+
+See the [[Status Message Page|status.html]] for complete details of the status messages for each type.
+
+h2. Lock Example
+
+Here is pseudo-code for doing a distributed lock using the Curator REST Proxy:
+
+{code}
+Address address = ... # host and port of the Curator REST Proxy instance
+LockSpec lock = {path: "/lock/path", maxWaitMs=5000}
+IdSpec lockId = restClient.post(address, "/curator/v1/recipes/lock", lock)
+statusMaintainer.add(address, lockId)
+ ... do work here while in the acquired mutex ...
+restClient.delete(address, "/curator/v1/recipes/lock/" + lockId.id)
+statusMaintainer.remove(address, lockId)
+{code}
+
+The statusMaintainer mechanism should iterate over any records it has and call the status API peridocially:
+
+{code}
+do record in maintainedRecords
+ Status status = restClient.post(record.address, "/curator/v1/client/status", record.ids)
+ if status.state is not "connected"
+ ... assume you are not connected and handle accordingly ...
+ end
+ do message in status.messages
+ if message.type is "watch" ...
+ etc...
+ end
+end
+{code}
+
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/confluence/deploy.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/deploy.confluence b/curator-x-rest/src/site/confluence/deploy.confluence
new file mode 100644
index 0000000..f4bd29b
--- /dev/null
+++ b/curator-x-rest/src/site/confluence/deploy.confluence
@@ -0,0 +1,12 @@
+[[Curator REST Proxy|index.html]] / Deployment
+
+h1. Deployment
+
+Ideally, co-locate a Curator REST Proxy instance on each ZooKeeper instance. While this isn't a requirement, it is the simplest way to deploy.
+It has the benefit of: easy configuration, easier management and simpler reasoning.
+
+!images/client.png!
+
+Alternatively, you can deploy a separate Curator REST Proxy cluster and have it connect to your ZooKeeper cluster:
+
+!images/client-all.png!
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/confluence/entities.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/entities.confluence b/curator-x-rest/src/site/confluence/entities.confluence
index 63649ff..910cea8 100644
--- a/curator-x-rest/src/site/confluence/entities.confluence
+++ b/curator-x-rest/src/site/confluence/entities.confluence
@@ -82,5 +82,3 @@ Here are the entity descriptions for the entities used in the APIs:
| *ParticipantSpec* | | |
|participantId|string|The participant ID|
|isLeader|boolean|true if this is the leader|
-
-*TBD*
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/confluence/index.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/index.confluence b/curator-x-rest/src/site/confluence/index.confluence
index da36433..706a403 100644
--- a/curator-x-rest/src/site/confluence/index.confluence
+++ b/curator-x-rest/src/site/confluence/index.confluence
@@ -4,37 +4,19 @@ NOTE: Curator REST Proxy is in its own package in Maven Central: {{curator-x-res
The Curator REST module implements a proxy that bridges non-java environments with the Curator framework and recipes. Every major language
today has a REST library available. With the Curator REST Proxy, you can now take advantage of the Curator framework and its recipes in
-any language.
-
-*TBD*
-
-!images/client.png!
+any language or environment.
h2. Building and Packaging
-Dropwizard
-
-*TBD*
+See the [[Building and Packaging Page|build.html]] for details on building and packaging the REST proxy.
h2. Deployment
-Ideally, co-locate a Curator REST Proxy instance on each ZooKeeper instance. While this isn't a requirement, it is the simplest way to deploy.
-
-*TBD*
-
-h2. Stateful vs Stateless
-
-Some of the Proxy's APIs are stateful and some are stateless. For the Client APIs, if you make a call that is either asynchronous, sets a watcher,
-or creates an ephemeral node, there is some state that is stored. In these cases, you must periodically send a status heartbeat and examine the
-resulting messages. This status heartbeat must be sent to the *same server* to which you originated the request. E.g. if you have 3 Curator REST
-Proxies A, B and C and execute a lock API to server B, you must periodically send a status with the lock's ID to server B. See the section
-below on Managing Status for more details.
-
-h2. Managing Status
+See the [[Deployment Page|deploy.html]] for details on deploying the REST proxy.
-*TBD*
+h2. Your REST Client
-See the [[Status Message Page|status.html]] for details of the status messages for each type.
+See the [[REST Client|client.html]] for details on how to write a REST client that interacts with the proxy.
h2. APIs
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/confluence/status.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/status.confluence b/curator-x-rest/src/site/confluence/status.confluence
index 47e216a..f81b11e 100644
--- a/curator-x-rest/src/site/confluence/status.confluence
+++ b/curator-x-rest/src/site/confluence/status.confluence
@@ -2,6 +2,12 @@
h1. Status Messages
+The Status entity schema is:
+
+||Field||Type||Description||
+|state|string|This instance's Curator connection state. One of: "connected", "suspended", or "lost". If the state is other than "connected" you must assume that any open locks and/or watchers are no longer valid.|
+|messages|array of StatusMessages|Any pending messages from this instance.|
+
h2. Status Messages
|*Watchers*| |
@@ -13,7 +19,7 @@ h2. Status Messages
|*Expired Instances*| |
|Type|expired|
|Source Id|Generated Id of the instance that is expiring|
-|Message|Class name of the expiring instance. Either: "LeaderLatch.class", "InterProcessSemaphoreMutex.class", "NodeCache.class", "PathChildrenCache.class", "PersistentEphemeralNode.class", "InterProcessMutex.class", "LeasesHolder.class" (for semaphores)|
+|Message|Name of the expiring instance. Either: "LeaderLatch", "InterProcessSemaphoreMutex", "NodeCache", "PathChildrenCache", "PersistentEphemeralNode", "InterProcessMutex", "LeasesHolder" (for semaphores)|
|Details|n/a|
h2. Asynchronous Client APIs
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/resources/images/client-all.png
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/resources/images/client-all.png b/curator-x-rest/src/site/resources/images/client-all.png
new file mode 100644
index 0000000..007b60e
Binary files /dev/null and b/curator-x-rest/src/site/resources/images/client-all.png differ
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/resources/images/client-requests.png
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/resources/images/client-requests.png b/curator-x-rest/src/site/resources/images/client-requests.png
new file mode 100644
index 0000000..3da02e9
Binary files /dev/null and b/curator-x-rest/src/site/resources/images/client-requests.png differ
http://git-wip-us.apache.org/repos/asf/curator/blob/037a4675/curator-x-rest/src/site/resources/images/client.png
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/resources/images/client.png b/curator-x-rest/src/site/resources/images/client.png
index 3da02e9..7d5064a 100644
Binary files a/curator-x-rest/src/site/resources/images/client.png and b/curator-x-rest/src/site/resources/images/client.png differ
[2/2] git commit: initial version complete. Still needed testing and
validation
Posted by ra...@apache.org.
initial version complete. Still needed testing and validation
Project: http://git-wip-us.apache.org/repos/asf/curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/938f3748
Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/938f3748
Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/938f3748
Branch: refs/heads/CURATOR-88
Commit: 938f3748dae783b4f1762b63a6c3932b40655d13
Parents: 037a467
Author: randgalt <ra...@apache.org>
Authored: Sun Feb 23 12:45:25 2014 +0530
Committer: randgalt <ra...@apache.org>
Committed: Sun Feb 23 12:45:25 2014 +0530
----------------------------------------------------------------------
curator-x-rest/src/site/confluence/apis.confluence | 17 ++++++++---------
.../src/site/confluence/client.confluence | 2 +-
.../src/site/confluence/entities.confluence | 11 ++++++++++-
3 files changed, 19 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/curator/blob/938f3748/curator-x-rest/src/site/confluence/apis.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/apis.confluence b/curator-x-rest/src/site/confluence/apis.confluence
index abde4ca..920c516 100644
--- a/curator-x-rest/src/site/confluence/apis.confluence
+++ b/curator-x-rest/src/site/confluence/apis.confluence
@@ -12,8 +12,6 @@ h2. Status APIs
h2. Client APIs
-NOTE: Not all combinations are valid *TBD*
-
||URL||Method||Request Entity||Response Entity||Description||
|/get-children|POST|GetChildrenSpec|Array of strings|This is the equivalent of CuratorFramework.getChildren().|
|/create|POST|CreateSpec|PathAndId|This is the equivalent of CuratorFramework.create().|
@@ -24,17 +22,22 @@ NOTE: Not all combinations are valid *TBD*
h3. How Asynchronous APIs Are Handled
-*TBD*
+For async versions of the Client APIs, the result is returned via a Status Message. See the [[Managing Status|client.html]] section for details
+as well as the [[Status Messages|status.html]] page which details the Asynchronous Client APIs messages.
h3. How Watchers Are Handled
-*TBD*
+If you set "isWatched" to true in a Client API, a status message is generated when the watcher fires. See the [[Managing Status|client.html]]
+section for details as well as the [[Status Messages|status.html]] page which details the Watchers message.
h3. How Ephemeral Nodes Are Handled
-*TBD*
+If you create an ephemeral node using the Client APIs, you must periodically send a heartbeat with the ID of the ephemeral node (as
+returned by the API). See the [[Client Page|client.html]] for details. IMPORTANT: if you fail to send heartbeats within the configured
+session length, the Curator REST Proxy will delete the ephemeral node (sending an expiration status message).
h2. Recipe APIs
+
||URL||Method||Request Entity||Response Entity||Description||
|/curator/v1/recipes/lock|POST|LockSpec|IdSpec|An InterProcessSemaphoreMutex. On successful return, your client will be holding the specified lock until you delete the lock via the delete API.|
|/curator/v1/recipes/lock/{lock-id}|DELETE|n/a|n/a|Release and delete a lock.|
@@ -42,10 +45,6 @@ h2. Recipe APIs
|/curator/v1/recipes/leader/{leader-id}|DELETE|n/a|n/a|Release/delete leadership.|
|/curator/v1/recipes/leader/{leader-id}|GET|n/a|array of ParticipantSpecs|List of participants in the leader election.|
-h3. Handling Timeouts, Status and Releasing
-
-*TBD - releases must go to same server, etc.
-
h2. Entities
See the [[Entity Descriptions Page|entities.html]] for details on the Entities used in the APIs.
http://git-wip-us.apache.org/repos/asf/curator/blob/938f3748/curator-x-rest/src/site/confluence/client.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/client.confluence b/curator-x-rest/src/site/confluence/client.confluence
index 9f9054e..94683dd 100644
--- a/curator-x-rest/src/site/confluence/client.confluence
+++ b/curator-x-rest/src/site/confluence/client.confluence
@@ -41,7 +41,7 @@ Here is pseudo-code for doing a distributed lock using the Curator REST Proxy:
{code}
Address address = ... # host and port of the Curator REST Proxy instance
-LockSpec lock = {path: "/lock/path", maxWaitMs=5000}
+LockSpec lock = {path: "/lock/path", maxWaitMs: 5000}
IdSpec lockId = restClient.post(address, "/curator/v1/recipes/lock", lock)
statusMaintainer.add(address, lockId)
... do work here while in the acquired mutex ...
http://git-wip-us.apache.org/repos/asf/curator/blob/938f3748/curator-x-rest/src/site/confluence/entities.confluence
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/confluence/entities.confluence b/curator-x-rest/src/site/confluence/entities.confluence
index 910cea8..d1ce778 100644
--- a/curator-x-rest/src/site/confluence/entities.confluence
+++ b/curator-x-rest/src/site/confluence/entities.confluence
@@ -10,7 +10,7 @@ Here are the entity descriptions for the entities used in the APIs:
|messages|array of StatusMessages|Any pending messages from this instance.|
| | | |
|*StatusMessage*| | |
-|type|string|The status message type. See the Managing Status section for details.|
+|type|string|The status message type. See the [[Managing Status|client.html]] section for details.|
|message|string|Type-dependent message|
|details|string|Type-dependent details|
|sourceId|string|Type-dependent sourceId|
@@ -27,6 +27,11 @@ Here are the entity descriptions for the entities used in the APIs:
|path|string|The ZK path|
|data|string|The data to store in the node|
|mode|string|The create mode. One of: "persistent", "persistent\_sequential", "ephemeral", or "ephemeral\_sequential"|
+|async|boolean|If true, perform asynchronously|
+|asyncId|string|for async, a user-defined ID to return in the status message|
+|compressed|boolean|if true, compress the data using Curator's compression mechanism|
+|creatingParentsIfNeeded|boolean|if true, parent paths are created if needed|
+|withProtection|boolean|if true, the Curator protection mechanism is used|
| | | |
| *PathAndId* | | |
|path|string|The created ZK Path (possibly with a sequence suffix)|
@@ -82,3 +87,7 @@ Here are the entity descriptions for the entities used in the APIs:
| *ParticipantSpec* | | |
|participantId|string|The participant ID|
|isLeader|boolean|true if this is the leader|
+
+*NOTE* - for the entities above used in the Recipe APIs, not all combinations of values are valid. For example,
+in the CreateSpec, withProtection and creatingParentsIfNeeded cannot be used together. The rule is only combinations
+that Curator itself supports can be used.
\ No newline at end of file