Package org.apache.curator.framework.imps

Class CreateBuilderImpl

java.lang.Object

org.apache.curator.framework.imps.CreateBuilderImpl

All Implemented Interfaces:

ACLable<BackgroundPathAndBytesable<String>>, ACLBackgroundPathAndBytesable<String>, ACLCreateModeBackgroundPathAndBytesable<String>, Backgroundable<ErrorListenerPathAndBytesable<String>>, BackgroundPathAndBytesable<String>, Compressible<CreateBackgroundModeStatACLable>, CreateBuilder, CreateBuilder2, CreateBuilderMain, CreateModable<ACLBackgroundPathAndBytesable<String>>, ErrorListenerPathAndBytesable<String>, Idempotentable<CreateBuilder2>, ParentACLable<BackgroundPathAndBytesable<String>>, PathAndBytesable<String>, Statable<CreateProtectACLCreateModePathAndBytesable<String>>

public class CreateBuilderImpl
extends Object
implements CreateBuilder, CreateBuilder2, ErrorListenerPathAndBytesable<String>

Constructor Summary

Constructors

Constructor	Description
CreateBuilderImpl(CuratorFrameworkBase client, org.apache.zookeeper.CreateMode createMode, Backgrounding backgrounding, boolean createParentsIfNeeded, boolean createParentsAsContainers, boolean doProtected, boolean compress, boolean setDataIfExists, List<org.apache.zookeeper.data.ACL> aclList, org.apache.zookeeper.data.Stat storingStat, long ttl)

Method Summary

Modifier and Type	Method	Description
CreateBackgroundModeStatACLable	compressed()	Cause the data to be compressed using the configured compression provider
ProtectACLCreateModeStatPathAndBytesable<String>	creatingParentContainersIfNeeded()	Causes any parent nodes to get created using CreateMode.CONTAINER if they haven't already been.
ProtectACLCreateModeStatPathAndBytesable<String>	creatingParentsIfNeeded()	Causes any parent nodes to get created if they haven't already been
String	forPath(String path)	Commit the currently building operation using the given path and the default data for the client (usually a byte[0] unless changed via CuratorFrameworkFactory.Builder.defaultData(byte[])).
String	forPath(String givenPath, byte[] data)	Commit the currently building operation using the given path and data
CuratorEventType	getBackgroundEventType()
CreateBuilder2	idempotent()	If the first try of this operation gets a transient error, curator will retry the operation, and treat it as successful so long as the end state of the znode is the same as if the operation had completed without error on the first try.
ErrorListenerPathAndBytesable<String>	inBackground()	Perform the action in the background
ErrorListenerPathAndBytesable<String>	inBackground(Object context)	Perform the action in the background
ErrorListenerPathAndBytesable<String>	inBackground(BackgroundCallback callback)	Perform the action in the background
ErrorListenerPathAndBytesable<String>	inBackground(BackgroundCallback callback, Object context)	Perform the action in the background
ErrorListenerPathAndBytesable<String>	inBackground(BackgroundCallback callback, Object context, Executor executor)	Perform the action in the background
ErrorListenerPathAndBytesable<String>	inBackground(BackgroundCallback callback, Executor executor)	Perform the action in the background
CreateBuilder2	orSetData()	If the ZNode already exists, Curator will instead call setData()
CreateBuilder2	orSetData(int version)	If the ZNode already exists, Curator will instead call setData()
void	performBackgroundOperation(org.apache.curator.framework.imps.OperationAndData<org.apache.curator.framework.imps.PathAndBytes> operationAndData)
void	setSetDataIfExistsVersion(int version)
CreateProtectACLCreateModePathAndBytesable<String>	storingStatIn(org.apache.zookeeper.data.Stat stat)	Have the operation fill the provided stat object
CreateBackgroundModeStatACLable	uncompressed()	Cause the data to be uncompressed, even if the CuratorFramework has compressionEnabled
ACLBackgroundPathAndBytesable<String>	withACL(List<org.apache.zookeeper.data.ACL> aclList)	Set an ACL list (default is ZooDefs.Ids.OPEN_ACL_UNSAFE)
ACLBackgroundPathAndBytesable<String>	withACL(List<org.apache.zookeeper.data.ACL> aclList, boolean applyToParents)	Set an ACL list (default is ZooDefs.Ids.OPEN_ACL_UNSAFE).
ACLBackgroundPathAndBytesable<String>	withMode(org.apache.zookeeper.CreateMode mode)	Set a create mode - the default is CreateMode.PERSISTENT
ACLPathAndBytesable<String>	withProtectedEphemeralSequential()
ACLCreateModeStatBackgroundPathAndBytesable<String>	withProtection()	Hat-tip to https://github.com/sbridges for pointing this out
CreateBuilderMain	withTtl(long ttl)	Specify a TTL when mode is CreateMode.PERSISTENT_WITH_TTL or CreateMode.PERSISTENT_SEQUENTIAL_WITH_TTL.
PathAndBytesable<String>	withUnhandledErrorListener(UnhandledErrorListener listener)	Set an error listener for this background operation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CreateBuilderImpl

public CreateBuilderImpl(CuratorFrameworkBase client,
 org.apache.zookeeper.CreateMode createMode,
 Backgrounding backgrounding,
 boolean createParentsIfNeeded,
 boolean createParentsAsContainers,
 boolean doProtected,
 boolean compress,
 boolean setDataIfExists,
 List<org.apache.zookeeper.data.ACL> aclList,
 org.apache.zookeeper.data.Stat storingStat,
 long ttl)

Method Details

setSetDataIfExistsVersion

public void setSetDataIfExistsVersion(int version)

orSetData

public CreateBuilder2 orSetData()

Description copied from interface: CreateBuilder

If the ZNode already exists, Curator will instead call setData()

Specified by:

orSetData in interface CreateBuilder

orSetData

public CreateBuilder2 orSetData(int version)

Description copied from interface: CreateBuilder

If the ZNode already exists, Curator will instead call setData()

Specified by:

orSetData in interface CreateBuilder

Parameters:

version - the version to use for CuratorFramework.setData()

idempotent

public CreateBuilder2 idempotent()

Description copied from interface: Idempotentable

If the first try of this operation gets a transient error, curator will retry the operation, and treat it as successful so long as the end state of the znode is the same as if the operation had completed without error on the first try.

Specified by:

idempotent in interface Idempotentable<CreateBuilder2>

Returns:

this:

withTtl

public CreateBuilderMain withTtl(long ttl)

Description copied from interface: CreateBuilder

Specify a TTL when mode is CreateMode.PERSISTENT_WITH_TTL or CreateMode.PERSISTENT_SEQUENTIAL_WITH_TTL. If the znode has not been modified within the given TTL, it will be deleted once it has no children. The TTL unit is milliseconds and must be greater than 0 and less than or equal to EphemeralType.MAX_TTL.

Specified by:

withTtl in interface CreateBuilder

Specified by:

withTtl in interface CreateBuilder2

Parameters:

ttl - the ttl

Returns:

this for chaining

compressed

public CreateBackgroundModeStatACLable compressed()

Description copied from interface: Compressible

Cause the data to be compressed using the configured compression provider

Specified by:

compressed in interface Compressible<CreateBackgroundModeStatACLable>

Returns:

this

uncompressed

public CreateBackgroundModeStatACLable uncompressed()

Description copied from interface: Compressible

Cause the data to be uncompressed, even if the CuratorFramework has compressionEnabled

Specified by:

uncompressed in interface Compressible<CreateBackgroundModeStatACLable>

Returns:

this

withACL

public ACLBackgroundPathAndBytesable<String> withACL(List<org.apache.zookeeper.data.ACL> aclList)

Description copied from interface: ACLable

Set an ACL list (default is ZooDefs.Ids.OPEN_ACL_UNSAFE)

Specified by:

withACL in interface ACLable<BackgroundPathAndBytesable<String>>

Parameters:

aclList - the ACL list to use

Returns:

this

withACL

public ACLBackgroundPathAndBytesable<String> withACL(List<org.apache.zookeeper.data.ACL> aclList,
 boolean applyToParents)

Description copied from interface: ParentACLable

Set an ACL list (default is ZooDefs.Ids.OPEN_ACL_UNSAFE). If applyToParents is true, then the aclList is applied to the created parents. Existing parent nodes are not affected.

Specified by:

withACL in interface ParentACLable<BackgroundPathAndBytesable<String>>

Parameters:

aclList - the ACL list to use

applyToParents - if true, then the aclList is applied to the created parents.

Returns:

this

creatingParentContainersIfNeeded

public ProtectACLCreateModeStatPathAndBytesable<String> creatingParentContainersIfNeeded()

Description copied from interface: CreateBuilderMain

Causes any parent nodes to get created using CreateMode.CONTAINER if they haven't already been. IMPORTANT NOTE: container creation is a new feature in recent versions of ZooKeeper. If the ZooKeeper version you're using does not support containers, the parent nodes are created as ordinary PERSISTENT nodes.

Specified by:

creatingParentContainersIfNeeded in interface CreateBuilderMain

Returns:

this

creatingParentsIfNeeded

public ProtectACLCreateModeStatPathAndBytesable<String> creatingParentsIfNeeded()

Description copied from interface: CreateBuilderMain

Causes any parent nodes to get created if they haven't already been

Specified by:

creatingParentsIfNeeded in interface CreateBuilderMain

Returns:

this

withProtection

public ACLCreateModeStatBackgroundPathAndBytesable<String> withProtection()

Description copied from interface: CreateBuilderMain

Hat-tip to https://github.com/sbridges for pointing this out

It turns out there is an edge case that exists when creating sequential-ephemeral nodes. The creation can succeed on the server, but the server can crash before the created node name is returned to the client. However, the ZK session is still valid so the ephemeral node is not deleted. Thus, there is no way for the client to determine what node was created for them.

Even without sequential-ephemeral, however, the create can succeed on the sever but the client (for various reasons) will not know it.

Putting the create builder into protection mode works around this. The name of the node that is created is prefixed with a 40 characters string that is the concatenation of

• "_c_"
• Canonical text representation of a random generated UUID as produced by UUID.toString()
• '-'

If node creation fails the normal retry mechanism will occur. On the retry, the parent path is first searched for a node that has previous described prefix in it. If that node is found, it is assumed to be the lost node that was successfully created on the first try and is returned to the caller.

Specified by:

withProtection in interface CreateBuilderMain

Returns:

this

withProtectedEphemeralSequential

public ACLPathAndBytesable<String> withProtectedEphemeralSequential()

Specified by:

withProtectedEphemeralSequential in interface CreateBuilderMain

Returns:

this

withMode

public ACLBackgroundPathAndBytesable<String> withMode(org.apache.zookeeper.CreateMode mode)

Description copied from interface: CreateModable

Set a create mode - the default is CreateMode.PERSISTENT

Specified by:

withMode in interface CreateModable<ACLBackgroundPathAndBytesable<String>>

Parameters:

mode - new create mode

Returns:

this

inBackground

public ErrorListenerPathAndBytesable<String> inBackground(BackgroundCallback callback,
 Object context)

Description copied from interface: Backgroundable

Perform the action in the background

Specified by:

inBackground in interface Backgroundable<ErrorListenerPathAndBytesable<String>>

Parameters:

callback - a functor that will get called when the operation has completed

context - context object - will be available from the event sent to the listener

Returns:

this

inBackground

public ErrorListenerPathAndBytesable<String> inBackground(BackgroundCallback callback,
 Object context,
 Executor executor)

Description copied from interface: Backgroundable

Perform the action in the background

Specified by:

inBackground in interface Backgroundable<ErrorListenerPathAndBytesable<String>>

Parameters:

callback - a functor that will get called when the operation has completed

context - context object - will be available from the event sent to the listener

executor - executor to use for the background call

Returns:

this

inBackground

public ErrorListenerPathAndBytesable<String> inBackground(BackgroundCallback callback)

Description copied from interface: Backgroundable

Perform the action in the background

Specified by:

inBackground in interface Backgroundable<ErrorListenerPathAndBytesable<String>>

Parameters:

callback - a functor that will get called when the operation has completed

Returns:

this

inBackground

public ErrorListenerPathAndBytesable<String> inBackground(BackgroundCallback callback,
 Executor executor)

Description copied from interface: Backgroundable

Perform the action in the background

Specified by:

inBackground in interface Backgroundable<ErrorListenerPathAndBytesable<String>>

Parameters:

callback - a functor that will get called when the operation has completed

executor - executor to use for the background call

Returns:

this

inBackground

public ErrorListenerPathAndBytesable<String> inBackground()

Description copied from interface: Backgroundable

Perform the action in the background

Specified by:

inBackground in interface Backgroundable<ErrorListenerPathAndBytesable<String>>

Returns:

this

inBackground

public ErrorListenerPathAndBytesable<String> inBackground(Object context)

Description copied from interface: Backgroundable

Perform the action in the background

Specified by:

inBackground in interface Backgroundable<ErrorListenerPathAndBytesable<String>>

Parameters:

context - context object - will be available from the event sent to the listener

Returns:

this

withUnhandledErrorListener

public PathAndBytesable<String> withUnhandledErrorListener(UnhandledErrorListener listener)

Description copied from interface: ErrorListenerPathAndBytesable

Set an error listener for this background operation. If an exception occurs while processing the call in the background, this listener will be called.

Specified by:

withUnhandledErrorListener in interface ErrorListenerPathAndBytesable<String>

Parameters:

listener - the listener

Returns:

this for chaining

forPath

public String forPath(String path)
               throws Exception

Description copied from interface: PathAndBytesable

Commit the currently building operation using the given path and the default data for the client (usually a byte[0] unless changed via CuratorFrameworkFactory.Builder.defaultData(byte[])).

Specified by:

forPath in interface PathAndBytesable<String>

Parameters:

path - the path

Returns:

operation result if any

Throws:

Exception - errors

forPath

public String forPath(String givenPath,
 byte[] data)
               throws Exception

Description copied from interface: PathAndBytesable

Commit the currently building operation using the given path and data

Specified by:

forPath in interface PathAndBytesable<String>

Parameters:

givenPath - the path

data - the data

Returns:

operation result if any

Throws:

Exception - errors

getBackgroundEventType

public CuratorEventType getBackgroundEventType()

performBackgroundOperation

public void performBackgroundOperation(org.apache.curator.framework.imps.OperationAndData<org.apache.curator.framework.imps.PathAndBytes> operationAndData)
                                throws Exception

Throws:

Exception

storingStatIn

public CreateProtectACLCreateModePathAndBytesable<String> storingStatIn(org.apache.zookeeper.data.Stat stat)

Description copied from interface: Statable

Have the operation fill the provided stat object

Specified by:

storingStatIn in interface Statable<CreateProtectACLCreateModePathAndBytesable<String>>

Parameters:

stat - the stat to have filled in

Returns:

this