curator-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From randg...@apache.org
Subject [3/4] git commit: work on doc for rest
Date Tue, 18 Feb 2014 09:48:44 GMT
work on doc for rest


Project: http://git-wip-us.apache.org/repos/asf/curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/32672858
Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/32672858
Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/32672858

Branch: refs/heads/CURATOR-88
Commit: 32672858843c6514a62ba8b70de17a1948e15384
Parents: 6f21cf5
Author: randgalt <randgalt@apache.org>
Authored: Mon Feb 17 21:05:04 2014 -0500
Committer: randgalt <randgalt@apache.org>
Committed: Mon Feb 17 21:05:04 2014 -0500

----------------------------------------------------------------------
 .../curator/x/rest/api/ClientResource.java      |   5 +
 .../curator/x/rest/api/LeaderResource.java      |   4 +-
 .../apache/curator/x/rest/api/LockResource.java |   4 +-
 curator-x-rest/src/site/assets/client.png       | Bin 0 -> 100105 bytes
 .../src/site/confluence/index.confluence        | 138 ++++++++++++++++++-
 5 files changed, 146 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/curator/blob/32672858/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/ClientResource.java
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/ClientResource.java
b/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/ClientResource.java
index 2321fa0..d866a21 100644
--- a/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/ClientResource.java
+++ b/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/ClientResource.java
@@ -31,6 +31,7 @@ import org.apache.curator.x.rest.entities.GetDataSpec;
 import org.apache.curator.x.rest.entities.PathAndId;
 import org.apache.curator.x.rest.entities.SetDataSpec;
 import org.apache.zookeeper.CreateMode;
+import org.apache.zookeeper.data.Stat;
 import org.codehaus.jackson.node.ObjectNode;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -266,6 +267,9 @@ public class ClientResource
             castBuilder(builder, Backgroundable.class).inBackground(backgroundCallback);
         }
 
+        Stat stat = new Stat();
+        builder = castBuilder(builder, Statable.class).storingStatIn(stat);
+
         String result = "";
         Object bytes = castBuilder(builder, Pathable.class).forPath(getDataSpec.getPath());
         if ( bytes != null )
@@ -275,6 +279,7 @@ public class ClientResource
 
         ObjectNode node = context.getMapper().createObjectNode();
         node.put("data", result);
+        node.putPOJO("stat", stat);
         return Response.ok(context.getWriter().writeValueAsString(node)).build();
     }
 

http://git-wip-us.apache.org/repos/asf/curator/blob/32672858/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LeaderResource.java
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LeaderResource.java
b/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LeaderResource.java
index e9c7ec4..2590597 100644
--- a/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LeaderResource.java
+++ b/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LeaderResource.java
@@ -28,7 +28,7 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import javax.ws.rs.Consumes;
 import javax.ws.rs.DELETE;
-import javax.ws.rs.PUT;
+import javax.ws.rs.POST;
 import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 import javax.ws.rs.Produces;
@@ -48,7 +48,7 @@ public class LeaderResource
         this.context = context;
     }
 
-    @PUT
+    @POST
     @Consumes(MediaType.APPLICATION_JSON)
     @Produces(MediaType.APPLICATION_JSON)
     public Response startLeaderSelection(final LeaderSpec leaderSpec) throws Exception

http://git-wip-us.apache.org/repos/asf/curator/blob/32672858/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LockResource.java
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LockResource.java
b/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LockResource.java
index a5eebda..8104858 100644
--- a/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LockResource.java
+++ b/curator-x-rest/src/main/java/org/apache/curator/x/rest/api/LockResource.java
@@ -26,7 +26,7 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import javax.ws.rs.Consumes;
 import javax.ws.rs.DELETE;
-import javax.ws.rs.PUT;
+import javax.ws.rs.POST;
 import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 import javax.ws.rs.Produces;
@@ -46,7 +46,7 @@ public class LockResource
         this.context = context;
     }
 
-    @PUT
+    @POST
     @Consumes(MediaType.APPLICATION_JSON)
     @Produces(MediaType.APPLICATION_JSON)
     public Response acquireLock(final LockSpec lockSpec) throws Exception

http://git-wip-us.apache.org/repos/asf/curator/blob/32672858/curator-x-rest/src/site/assets/client.png
----------------------------------------------------------------------
diff --git a/curator-x-rest/src/site/assets/client.png b/curator-x-rest/src/site/assets/client.png
new file mode 100644
index 0000000..27d10c2
Binary files /dev/null and b/curator-x-rest/src/site/assets/client.png differ

http://git-wip-us.apache.org/repos/asf/curator/blob/32672858/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 d81c9a8..22755d5 100644
--- a/curator-x-rest/src/site/confluence/index.confluence
+++ b/curator-x-rest/src/site/confluence/index.confluence
@@ -2,5 +2,141 @@ h1. Curator REST Proxy
 
 NOTE: Curator REST Proxy is in its own package in Maven Central: {{curator-x-rest}}
 
-The Curator REST module implements a proxy that bridges non-java environments with the Curator
framework and recipes. *TBD*
+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*
+
+h2. Building and Packaging
+
+Dropwizard
+
+*TBD*
+
+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
+
+*TBD*
+
+h2. Status APIs
+
+||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.|
+
+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().|
+|/delete|POST|DeleteSpec|n/a|This is the equivalent of CuratorFramework.delete().|
+|/set-data|POST|SetDataSpec|n/a|This is the equivalent of CuratorFramework.setData().|
+|/get-data|POST|GetDataSpec|DataAndStat|This is the equivalent of CuratorFramework.setData().|
+|/exists|POST|ExistsSpec|ZK Stat or empty|This is the equivalent of CuratorFramework.exists().|
+
+h3. How Asynchronous APIs Are Handled
+
+*TBD*
+
+h3. How Watchers Are Handled
+
+*TBD*
+
+h3. How Ephemeral Nodes Are Handled
+
+*TBD*
+
+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.|
+|/curator/v1/recipes/leader|POST|LeaderSpec|IdSpec|Start a LeaderLatch instance. When you
gain leadership, it will be notified via status.|
+|/curator/v1/recipes/leader/{leader-id}|DELETE|n/a|n/a|Release/delete leadership.|
+
+h3. Handling Timeouts, Status and Releasing
+
+*TBD - releases must go to same server, etc.
+
+h2. Entities
+
+||Field||Type||Description||
+|*Status*| | |
+|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.|
+| | | |
+|*StatusMessage*| | |
+|type|string|The status message type. See the Managing Status section for details.|
+|message|string|Type-dependent message|
+|details|string|Type-dependent details|
+|sourceId|string|Type-dependent sourceId|
+| | | |
+|*GetChildrenSpec*| | |
+|path|string|The ZK path|
+|async|boolean|If true, perform asynchronously|
+|asyncId|string|for async, a user-defined ID to return in the status message|
+|asyncListSeparator|string|for async, the separator to use for the child names. Usually you'd
set this to ",".|
+|watched|boolean|if true, set a watch|
+|watchId|string|if watched, a user-defined ID to return in the status when the watch triggers|
+| | | |
+|*CreateSpec*| | |
+|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"|
+| | | |
+| *PathAndId* | | |
+|path|string|The created ZK Path (possibly with a sequence suffix)|
+|id|string|The internally generated id for this node (used for ephemerals)|
+| | | |
+| *DeleteSpec* | | |
+|path|string|The ZK path|
+|async|boolean|If true, perform asynchronously|
+|asyncId|string|for async, a user-defined ID to return in the status message|
+|guaranteed|boolean|if true, use Curator's guaranteed delete mechanism|
+|version|int|the expected version to delete or -1|
+| | | |
+| *SetDataSpec* | | |
+|path|string|The ZK path|
+|data|string|The data to set|
+|async|boolean|If true, perform asynchronously|
+|asyncId|string|for async, a user-defined ID to return in the status message|
+|watched|boolean|if true, set a watch|
+|watchId|string|if watched, a user-defined ID to return in the status when the watch triggers|
+|compressed|boolean|if true, compress the data using Curator's compression mechanism|
+|version|int|the expected version or -1|
+| | | |
+| *GetDataSpec* | | |
+|path|string|The ZK path|
+|async|boolean|If true, perform asynchronously|
+|asyncId|string|for async, a user-defined ID to return in the status message|
+|watched|boolean|if true, set a watch|
+|watchId|string|if watched, a user-defined ID to return in the status when the watch triggers|
+|decompressed|boolean|if true, decompress the data using Curator's compression mechanism|
+| | | |
+| *DataAndStat* | | |
+|data|string|the data from the node|
+|stat|ZK Stat|the ZooKeeper stat for the node|
+| | | |
+| *ExistsSpec* | | |
+|path|string|The ZK path|
+|async|boolean|If true, perform asynchronously|
+|asyncId|string|for async, a user-defined ID to return in the status message|
+|watched|boolean|if true, set a watch|
+|watchId|string|if watched, a user-defined ID to return in the status when the watch triggers|
+
+*TBD*


Mime
View raw message