Debian Codegraph @

curator-examples/src/main/java/framework/CrudExamples.java

raw
1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20 package framework;
21
22 import java.util.List;
23 import org.apache.curator.framework.CuratorFramework;
24 import org.apache.curator.framework.api.BackgroundCallback;
25 import org.apache.curator.framework.api.CuratorEvent;
26 import org.apache.curator.framework.api.CuratorListener;
27 import org.apache.zookeeper.CreateMode;
28 import org.apache.zookeeper.Watcher;
29
30 public class CrudExamples {
31 public static void create(CuratorFramework client, String path, byte[] payload) throws Exception {
32 // this will create the given ZNode with the given data
33 client.create().forPath(path, payload);
34 }
35
36 public static void createEphemeral(CuratorFramework client, String path, byte[] payload) throws Exception {
37 // this will create the given EPHEMERAL ZNode with the given data
38 client.create().withMode(CreateMode.EPHEMERAL).forPath(path, payload);
39 }
40
41 public static String createEphemeralSequential(CuratorFramework client, String path, byte[] payload)
42 throws Exception {
43 // this will create the given EPHEMERAL-SEQUENTIAL ZNode with the given data using Curator protection.
44
45 /*
46 Protection Mode:
47
48 It turns out there is an edge case that exists when creating sequential-ephemeral nodes. The creation
49 can succeed on the server, but the server can crash before the created node name is returned to the
50 client. However, the ZK session is still valid so the ephemeral node is not deleted. Thus, there is no
51 way for the client to determine what node was created for them.
52
53 Even without sequential-ephemeral, however, the create can succeed on the sever but the client (for various
54 reasons) will not know it. Putting the create builder into protection mode works around this. The name of
55 the node that is created is prefixed with a GUID. If node creation fails the normal retry mechanism will
56 occur. On the retry, the parent path is first searched for a node that has the GUID in it. If that node is
57 found, it is assumed to be the lost node that was successfully created on the first try and is returned to
58 the caller.
59 */
60 return client.create()
61 .withProtection()
62 .withMode(CreateMode.EPHEMERAL_SEQUENTIAL)
63 .forPath(path, payload);
64 }
65
66 public static void createIdempotent(CuratorFramework client, String path, byte[] payload) throws Exception {
67 /*
68 * This will create the given ZNode with the given data idempotently, meaning that if the initial create
69 * failed transiently, it will be retried and behave as if the first create never happened, even if the
70 * first create actually succeeded on the server but the client didn't know it.
71 */
72 client.create().idempotent().forPath(path, payload);
73 }
74
75 public static void setData(CuratorFramework client, String path, byte[] payload) throws Exception {
76 // set data for the given node
77 client.setData().forPath(path, payload);
78 }
79
80 public static void setDataAsync(CuratorFramework client, String path, byte[] payload) throws Exception {
81 // this is one method of getting event/async notifications
82 CuratorListener listener = new CuratorListener() {
83 @Override
84 public void eventReceived(CuratorFramework client, CuratorEvent event) throws Exception {
85 // examine event for details
86 }
87 };
88 client.getCuratorListenable().addListener(listener);
89
90 // set data for the given node asynchronously. The completion notification
91 // is done via the CuratorListener.
92 client.setData().inBackground().forPath(path, payload);
93 }
94
95 public static void setDataAsyncWithCallback(
96 CuratorFramework client, BackgroundCallback callback, String path, byte[] payload) throws Exception {
97 // this is another method of getting notification of an async completion
98 client.setData().inBackground(callback).forPath(path, payload);
99 }
100
101 public static void setDataIdempotent(CuratorFramework client, String path, byte[] payload, int currentVersion)
102 throws Exception {
103 /*
104 * This will set the given ZNode with the given data idempotently, meaning that if the initial setData
105 * failed transiently, it will be retried and behave as if the first setData never happened, even if the
106 * first setData actually succeeded on the server but the client didn't know it.
107 * In other words, if currentVersion == X and payload = P, this will return success if the znode ends
108 * up in the state (version == X+1 && data == P).
109 * If withVersion is not specified, it will end up with success so long as the data == P, no matter the znode version.
110 */
111 client.setData().idempotent().withVersion(currentVersion).forPath(path, payload);
112 client.setData().idempotent().forPath(path, payload);
113 }
114
115 public static void delete(CuratorFramework client, String path) throws Exception {
116 // delete the given node
117 client.delete().forPath(path);
118 }
119
120 public static void guaranteedDelete(CuratorFramework client, String path) throws Exception {
121 // delete the given node and guarantee that it completes
122
123 /*
124 Guaranteed Delete
125
126 Solves this edge case: deleting a node can fail due to connection issues. Further, if the node was
127 ephemeral, the node will not get auto-deleted as the session is still valid. This can wreak havoc
128 with lock implementations.
129
130
131 When guaranteed is set, Curator will record failed node deletions and attempt to delete them in the
132 background until successful. NOTE: you will still get an exception when the deletion fails. But, you
133 can be assured that as long as the CuratorFramework instance is open attempts will be made to delete
134 the node.
135 */
136
137 client.delete().guaranteed().forPath(path);
138 }
139
140 public static void deleteIdempotent(CuratorFramework client, String path, int currentVersion) throws Exception {
141 /*
142 * This will delete the given ZNode with the given data idempotently, meaning that if the initial delete
143 * failed transiently, it will be retried and behave as if the first delete never happened, even if the
144 * first delete actually succeeded on the server but the client didn't know it.
145 * In other words, if currentVersion == X, this will return success if the znode ends up deleted, and will retry after
146 * connection loss if the version the znode's version is still X.
147 * If withVersion is not specified, it will end up successful so long as the node is deleted eventually.
148 * Kind of like guaranteed but not in the background.
149 * For deletes this is equivalent to the older quietly() behavior, but it is also provided under idempotent() for compatibility with Create/SetData.
150 */
151 client.delete().idempotent().withVersion(currentVersion).forPath(path);
152 client.delete().idempotent().forPath(path);
153 client.delete().quietly().withVersion(currentVersion).forPath(path);
154 client.delete().quietly().forPath(path);
155 }
156
157 public static List<String> watchedGetChildren(CuratorFramework client, String path) throws Exception {
158 /**
159 * Get children and set a watcher on the node. The watcher notification will come through the
160 * CuratorListener (see setDataAsync() above).
161 */
162 return client.getChildren().watched().forPath(path);
163 }
164
165 public static List<String> watchedGetChildren(CuratorFramework client, String path, Watcher watcher)
166 throws Exception {
167 /**
168 * Get children and set the given watcher on the node.
169 */
170 return client.getChildren().usingWatcher(watcher).forPath(path);
171 }
172 }