| 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 |
} |