curator-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From randg...@apache.org
Subject [1/2] git commit: wip
Date Sun, 23 Feb 2014 07:15:38 GMT
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 <randgalt@apache.org>
Authored: Sun Feb 23 12:28:28 2014 +0530
Committer: randgalt <randgalt@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


Mime
View raw message