From commits-return-6807-archive-asf-public=cust-asf.ponee.io@zookeeper.apache.org Mon Aug 6 14:14:22 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id D645118078F for ; Mon, 6 Aug 2018 14:14:20 +0200 (CEST) Received: (qmail 56773 invoked by uid 500); 6 Aug 2018 12:14:13 -0000 Mailing-List: contact commits-help@zookeeper.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@zookeeper.apache.org Delivered-To: mailing list commits@zookeeper.apache.org Received: (qmail 53339 invoked by uid 99); 6 Aug 2018 12:14:11 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 06 Aug 2018 12:14:11 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 26B3BE1182; Mon, 6 Aug 2018 12:14:11 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: andor@apache.org To: commits@zookeeper.apache.org Date: Mon, 06 Aug 2018 12:14:42 -0000 Message-Id: <1df0ef7ccaa24bc6afd2fca0fcba6cba@git.apache.org> In-Reply-To: <23d59816fc864cdcaa333309761a6f23@git.apache.org> References: <23d59816fc864cdcaa333309761a6f23@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [33/45] zookeeper git commit: ZOOKEEPER-3030: MAVEN MIGRATION - Step 1.3 - move contrib directories http://git-wip-us.apache.org/repos/asf/zookeeper/blob/eab8c1eb/src/contrib/zkperl/Changes ---------------------------------------------------------------------- diff --git a/src/contrib/zkperl/Changes b/src/contrib/zkperl/Changes deleted file mode 100644 index c31420e..0000000 --- a/src/contrib/zkperl/Changes +++ /dev/null @@ -1,65 +0,0 @@ -Net::ZooKeeper - Perl extension for Apache ZooKeeper - -Revision history -================ - -0.01 Dec 5, 2008 - - initial version - -0.02 Dec 16, 2008 - - support connection to ZooKeeper and get() method - -0.03 Jan 9, 2009 - - implemented watch mechanism for get() - -0.04 Jan 15, 2009 - - all basic ZooKeeper methods supported - -0.05 Jan 21, 2009 - - converted from T_PTROBJ to T_ZK_HASH with PERL_MAGIC_ext, - allows DESTROY() to be called repeatedly - -0.06 Jan 27, 2009 - - converted from attribute accessor methods to inner and outer hashes - with PERL_MAGIC_tied - -0.07 Jan 29, 2009 - - all tied hash methods completed - -0.08 Jan 30, 2009 - - simple thread safety enforced with CLONE_SKIP - -0.09 Feb 12, 2009 - - ACL constants - -0.10 Feb 18, 2009 - - ACL support - -0.11 Feb 21, 2009 - - ZooKeeper version check - -0.20 Feb 25, 2009 - - refactored watches as subclass - -0.30 Feb 27, 2009 - - refactored stats as subclass - -0.31 Mar 6, 2009 - - test suite completed - -0.32 Mar 25, 2009 - - initial documentation completed, first public release - -0.33 Apr 20, 2009 - - copyright donated to ASF - -0.34 Jul 14, 2009 - - support ZooKeeper 3.2.0 release - -0.35 Jul 15, 2009 - - support multiple include and library locations - -0.36 Mar 27, 2011 - - Fix zookeeper version check, but only warn since we haven't been enforcing it in a while - - Look for zookeeper includes in some sane places by default - http://git-wip-us.apache.org/repos/asf/zookeeper/blob/eab8c1eb/src/contrib/zkperl/LICENSE ---------------------------------------------------------------------- diff --git a/src/contrib/zkperl/LICENSE b/src/contrib/zkperl/LICENSE deleted file mode 100644 index d645695..0000000 --- a/src/contrib/zkperl/LICENSE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. http://git-wip-us.apache.org/repos/asf/zookeeper/blob/eab8c1eb/src/contrib/zkperl/MANIFEST ---------------------------------------------------------------------- diff --git a/src/contrib/zkperl/MANIFEST b/src/contrib/zkperl/MANIFEST deleted file mode 100644 index 1b57436..0000000 --- a/src/contrib/zkperl/MANIFEST +++ /dev/null @@ -1,23 +0,0 @@ -Changes -LICENSE -Makefile.PL -MANIFEST -NOTICE -README -typemap -ZooKeeper.pm -ZooKeeper.xs -build/check_zk_version.c -build/check_zk_version.h -t/10_invalid.t -t/15_thread.t -t/20_tie.t -t/22_stat_tie.t -t/24_watch_tie.t -t/30_connect.t -t/35_log.t -t/40_basic.t -t/45_class.t -t/50_access.t -t/60_watch.t -t/util.pl http://git-wip-us.apache.org/repos/asf/zookeeper/blob/eab8c1eb/src/contrib/zkperl/Makefile.PL ---------------------------------------------------------------------- diff --git a/src/contrib/zkperl/Makefile.PL b/src/contrib/zkperl/Makefile.PL deleted file mode 100644 index 9a0996d..0000000 --- a/src/contrib/zkperl/Makefile.PL +++ /dev/null @@ -1,73 +0,0 @@ -# Net::ZooKeeper - Perl extension for Apache ZooKeeper -# -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -use 5.008_008; - -use Config; -use ExtUtils::MakeMaker; -use Getopt::Long; - -my $ZOO_MAJOR_VERSION = 3; -my $ZOO_REQUIRED_VERSION = qr{^$ZOO_MAJOR_VERSION\.\d+.\d+$}ismx; - -my @zk_inc_paths; -my @zk_lib_paths; - -GetOptions( - 'zookeeper-include=s' => \@zk_inc_paths, - 'zookeeper-lib=s' => \@zk_lib_paths -); - -my $zk_inc_paths = join(' ', map("-I$_", @zk_inc_paths)); -my $zk_lib_paths = join(' ', map("-L$_", @zk_lib_paths)); - -$zk_inc_paths .= ' ' unless ($zk_inc_paths eq ''); -$zk_lib_paths .= ' ' unless ($zk_lib_paths eq ''); - -my $cc = $Config{'cc'}; -my $check_file = 'build/check_zk_version'; - -my $check_out = qx($cc $zk_inc_paths $zk_lib_paths -I. -o $check_file $check_file.c 2>&1); - -if ($?) { - if ($check_out =~ /zookeeper_version\.h/) { - die("Could not determine ZooKeeper version:\n\n$check_out"); - } - else { - ## keep in sync with build/check_zk_version.h - die("Net::ZooKeeper requires at least ZooKeeper version 3.1.1\n"); - } -} - -chomp(my $zk_ver = qx($check_file)); - -if ($? >> 8 != 0) { - die "Couldn't check zookeeper version: $zk_ver: $r"; -} -elsif ($zk_ver !~ $ZOO_REQUIRED_VERSION) { - warn "Net::ZooKeeper requires ZooKeeper 3.x, found $zk_ver!"; -} - -WriteMakefile( - 'INC' => "$zk_inc_paths-I.", - 'LIBS' => [ "$zk_lib_paths-lzookeeper_mt" ], - 'NAME' => 'Net::ZooKeeper', - 'VERSION_FROM' => 'ZooKeeper.pm', - 'clean' => { 'FILES' => 'build/check_zk_version.o' } -); - http://git-wip-us.apache.org/repos/asf/zookeeper/blob/eab8c1eb/src/contrib/zkperl/NOTICE ---------------------------------------------------------------------- diff --git a/src/contrib/zkperl/NOTICE b/src/contrib/zkperl/NOTICE deleted file mode 100644 index b68fdac..0000000 --- a/src/contrib/zkperl/NOTICE +++ /dev/null @@ -1,6 +0,0 @@ -Net::ZooKeeper - Perl extension for Apache ZooKeeper -Copyright 2009 The Apache Software Foundation - -This product includes software developed at -The Apache Software Foundation (http://www.apache.org/). - http://git-wip-us.apache.org/repos/asf/zookeeper/blob/eab8c1eb/src/contrib/zkperl/README ---------------------------------------------------------------------- diff --git a/src/contrib/zkperl/README b/src/contrib/zkperl/README deleted file mode 100644 index bbe2a0d..0000000 --- a/src/contrib/zkperl/README +++ /dev/null @@ -1,86 +0,0 @@ -Net::ZooKeeper - Perl extension for Apache ZooKeeper -==================================================== - -Net::ZooKeeper provides a Perl interface to the synchronous C API -of Apache ZooKeeper. ZooKeeper is coordination service for -distributed applications. -For details see the ZooKeeper home page at: - -http://zookeeper.apache.org/ - -INSTALLATION - -To install this module type the following, first install the -zookeeper C client, then: - - perl Makefile.PL - make - ZK_TEST_HOSTS=host:port,... make test - make install - -If the C headers and library are installed in non-standard -locations, specify them as arguments to Makefile.PL: - - perl Makefile.PL \ - --zookeeper-include=/path/to/zookeeper/client/include \ - --zookeeper-lib=/path/to/zookeeper/client/lib - -The path supplied to the --zookeeper-include option should -identify the directory that contains the zookeeper.h and other -ZooKeeper C include files. - -The path supplied to the --zookeeper-lib option should identify -the directory that contains the libzookeeper_mt library. - -When running "make test", if no ZK_TEST_HOSTS environment -variable is set, many tests will be skipped because no connection -to a ZooKeeper server is available. To execute these tests, -the ZK_TEST_HOSTS variable may be assigned a list of one or more -ZooKeeper host:port pairs, e.g., "localhost:7100,otherhost:7200". - -The ZK_TEST_PATH environment variable, if defined, specifies -the ZooKeeper path under which all test nodes should be created. -The tests expect to have full read/write/create/delete/admin -ZooKeeper permissions under this path. If no ZK_TEST_PATH -variable is defined, the root ZooKeeper path ("/") is used. - -DEPENDENCIES - -Version 3.1.1 of ZooKeeper is required at a minimum. - -For version 3.1.1, you may also want to apply some of these -additional patches to the ZooKeeper C API code: - -https://issues.apache.org/jira/browse/ZOOKEEPER-262 -https://issues.apache.org/jira/browse/ZOOKEEPER-318 - -For version 3.1.1, you may also want to apply some of these -additional patches to the ZooKeeper C API code: - -https://issues.apache.org/jira/browse/ZOOKEEPER-262 -https://issues.apache.org/jira/browse/ZOOKEEPER-466 - -This module requires that the multi-threaded version of the -ZooKeeper C API client library be available on your system. - -This in turn implies that the POSIX pthread library is available -as well. - -COPYRIGHT AND LICENCE - -Licensed to the Apache Software Foundation (ASF) under one -or more contributor license agreements. See the NOTICE file -distributed with this work for additional information -regarding copyright ownership. The ASF licenses this file -to you under the Apache License, Version 2.0 (the -"License"); you may not use this file except in compliance -with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - http://git-wip-us.apache.org/repos/asf/zookeeper/blob/eab8c1eb/src/contrib/zkperl/ZooKeeper.pm ---------------------------------------------------------------------- diff --git a/src/contrib/zkperl/ZooKeeper.pm b/src/contrib/zkperl/ZooKeeper.pm deleted file mode 100644 index 507f029..0000000 --- a/src/contrib/zkperl/ZooKeeper.pm +++ /dev/null @@ -1,1257 +0,0 @@ -# Net::ZooKeeper - Perl extension for Apache ZooKeeper -# -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -use 5.008_008; - -use strict; -use warnings; - -package Net::ZooKeeper; - -require Exporter; -require XSLoader; - -our $VERSION = '0.36'; - -our @ISA = qw(Exporter); - -our %EXPORT_TAGS = ( - 'errors' => [qw( - ZOK - ZSYSTEMERROR - ZRUNTIMEINCONSISTENCY - ZDATAINCONSISTENCY - ZCONNECTIONLOSS - ZMARSHALLINGERROR - ZUNIMPLEMENTED - ZOPERATIONTIMEOUT - ZBADARGUMENTS - ZINVALIDSTATE - ZAPIERROR - ZNONODE - ZNOAUTH - ZBADVERSION - ZNOCHILDRENFOREPHEMERALS - ZNODEEXISTS - ZNOTEMPTY - ZSESSIONEXPIRED - ZINVALIDCALLBACK - ZINVALIDACL - ZAUTHFAILED - ZCLOSING - ZNOTHING - )], - 'node_flags' => [qw( - ZOO_EPHEMERAL - ZOO_SEQUENCE - )], - 'acl_perms' => [qw( - ZOO_PERM_READ - ZOO_PERM_WRITE - ZOO_PERM_CREATE - ZOO_PERM_DELETE - ZOO_PERM_ADMIN - ZOO_PERM_ALL - )], - 'acls' => [qw( - ZOO_OPEN_ACL_UNSAFE - ZOO_READ_ACL_UNSAFE - ZOO_CREATOR_ALL_ACL - )], - 'events' => [qw( - ZOO_CREATED_EVENT - ZOO_DELETED_EVENT - ZOO_CHANGED_EVENT - ZOO_CHILD_EVENT - ZOO_SESSION_EVENT - ZOO_NOTWATCHING_EVENT - )], - 'states' => [qw( - ZOO_EXPIRED_SESSION_STATE - ZOO_AUTH_FAILED_STATE - ZOO_CONNECTING_STATE - ZOO_ASSOCIATING_STATE - ZOO_CONNECTED_STATE - )], - 'log_levels' => [qw( - ZOO_LOG_LEVEL_OFF - ZOO_LOG_LEVEL_ERROR - ZOO_LOG_LEVEL_WARN - ZOO_LOG_LEVEL_INFO - ZOO_LOG_LEVEL_DEBUG - )] -); - -{ - my %tags; - - push @{$EXPORT_TAGS{'all'}}, - grep {!$tags{$_}++} @{$EXPORT_TAGS{$_}} foreach (keys(%EXPORT_TAGS)); -} - -our @EXPORT_OK = ( @{$EXPORT_TAGS{'all'}} ); - -XSLoader::load('Net::ZooKeeper', $VERSION); - -1; - -__END__ - -=head1 NAME - -Net::ZooKeeper - Perl extension for Apache ZooKeeper - -=head1 SYNOPSIS - - use Net::ZooKeeper qw(:node_flags :acls); - - my $zkh = Net::ZooKeeper->new('localhost:7000'); - - $zkh->create('/foo', 'bar', - 'flags' => ZOO_EPHEMERAL, - 'acl' => ZOO_OPEN_ACL_UNSAFE) or - die("unable to create node /foo: " . $zkh->get_error() . "\n"); - - print "node /foo has value: " . $zkh->get('/foo') . "\n"; - - $zkh->set('/foo', 'baz'); - - print "node / has child nodes:\n"; - foreach my $path ($zkh->get_children('/')) { - print " /$path\n"; - } - - my $stat = $zkh->stat(); - if ($zkh->exists('/foo', 'stat' => $stat)) { - print "node /foo has stat info:\n"; - while (my($key,$value) = each(%{$stat})) { - print " $key: $value\n"; - } - } - - foreach my $acl_entry ($zkh->get_acl('/foo')) { - print "node /foo has ACL entry:\n"; - print " perms: $acl_entry->{perms}\n"; - print " scheme: $acl_entry->{scheme}\n"; - print " id: $acl_entry->{id}\n"; - } - - my $watch = $zkh->watch('timeout' => 10000); - $zkh->exists('/foo', 'watch' => $watch); - - if ($watch->wait()) { - print "watch triggered on node /foo:\n"; - print " event: $watch->{event}\n"; - print " state: $watch->{state}\n"; - } - else { - print "watch timed out after 10 seconds\n"; - } - - $zkh->delete('/foo'); - -=head1 DESCRIPTION - -Net::ZooKeeper provides a Perl interface to the synchronous C API -of Apache ZooKeeper. ZooKeeper is coordination service for -distributed applications. - -Each connection to ZooKeeper is represented as a handle object -of the class Net::ZooKeeper, similar to the manner in which database -connections are represented in the DBI module. - -To disconnect from ZooKeeper, simply destroy the Net::ZooKeeper -handle object by undefining it or by explicitly calling the -C method. - -The methods which may be invoked on Net::ZooKeeper handles -correspond to the functions of the synchronous ZooKeeper C API; -e.g., the Net::ZooKeeper method C calls the ZooKeeper -C function C, C calls C, -and so forth. - -The synchronous API functions wait for a response from the ZooKeeper -cluster before returning a result to the caller. Using these -functions permits Net::ZooKeeper to provide an interface similar -to that of a DBI driver module. - -=head2 Internal POSIX Threads - -The use of the synchronous ZooKeeper C API still requires that -the ZooKeeper C client code create several POSIX threads which run -concurrently with the main thread containing the Perl interpreter. - -The synchronous API functions are wrappers of the asynchronous -functions in the ZooKeeper C API. When a request is made by the -caller's thread (i.e., the one with the running Perl interpreter), -it is enqueued for delivery at a later time by the ZooKeeper C client -code's IO thread. The caller's thread then waits for notification -before returning from the synchronous API function. - -The IO thread dequeues the request and sends it to the ZooKeeper -cluster, while also ensuring that a regular "heartbeat" is maintained -with the cluster so that the current session does not time out. -When the IO thread receives a response from -the ZooKeeper cluster, it enqueues the response for delivery to the -client by the second thread of the ZooKeeper client code, the -completion thread. - -If the caller is using the asynchronous API, the completion thread -invokes the appropriate callback function provided by the caller -for the given request. In the case of Net::ZooKeeper, it is not -viable for the completion thread to invoke a Perl callback function -at arbitrary times; this could interfere with the state of the -Perl interpreter. - -For this reason Net::ZooKeeper uses the synchronous API only. After -enqueuing requests the synchronous API functions wait for notification -of the corresponding response. The completion thread delivers these -notifications, at which point the synchronous functions return to -their caller. - -Note that the IO and completion threads are POSIX threads, not -Perl ithreads. Net::ZooKeeper defined a C function so -that if Perl ithreads are spawned while a Net::ZooKeeper connection -is active, the Net::ZooKeeper handle objects inherited by the -spawned ithread contain undefined values so that they can not be used. -Thus each ithread will need to create its own private connections to a -ZooKeeper cluster. - -Note also that before invoking C to spawn a new process, -all Net::ZooKeeper handles should be destroyed so that all -connections to ZooKeeper are closed and all internal POSIX threads -have exited. If a child process needs to communicate with -ZooKeeper it should open its own private connections after it is -created by C. - -=head2 Signals - -The ZooKeeper C API uses TCP connections to communicate with -the ZooKeeper cluster. These connections may generate SIGPIPE -signals when they encounter errors, such as when a connection -is terminated by a ZooKeeper server. Therefore most applications -will want to trap or ignore SIGPIPE signals, e.g.: - - local $SIG{'PIPE'} = 'IGNORE'; - -Ignoring SIGPIPE signals (or providing a signal handler that returns -control to the interrupted program after receiving the signal) -will allow the ZooKeeper C client code to detect the connection error -and report it upon return from the next Net::ZooKeeper method. - -=head2 Error Handling - -Net::ZooKeeper methods return different values in the case of an -error depending on their purpose and context. For example, -C returns true if the node exists and false otherwise, -which may indicate either that the node does not exist or that -an error occurred. - -After any method returns a false, empty, or undefined value which -might indicate an error has occurred, the C method -may be called to examine the specific error code, if any. - -If C returns C, no error has occurred. If the -error code is less than C, it indicates a normal error -condition reported by the ZooKeeper server, such as C -(node does not exist) or C (node already exists). - -If the error code is greater than C, then a connection -error or server error has occurred and the client should probably -close the connection by undefining the Net::ZooKeeper handle object -and, if necessary, attempt to create a new connection to the -ZooKeeper cluster. - -=head2 Access Control - -If the ZooKeeper cluster is not configured with C then -it will respect the access controls set for each node in the -ZooKeeper hierarchy. These access controls are defined using ACLs -(Access Control Lists); see the ZooKeeper documentation for compete -details. - -In Net::ZooKeeper, ACLs are represented as arrays of hashes, where -each hash is an ACL entry that must contain three attributes, -C, C, and C. The C attribute's value -should be composed by combining ACL permission flags using the -bitwise OR operator. See C<:acl_perms> for a list of the -available ACL permission flags. - -The ACL for a node may be read using the C method. A -node's ACL may be set when the node is created by passing an ACL -array as the value of the C<'acl'> option to the C method, -and may be updated by passing an ACL array to the C method. - -When a client connects to a ZooKeeper cluster it is automatically -assigned authentication credentials based on its IP address. -Additional authentication credentials may be added using -the C method. Once a credential has been added for -the current session, there is no way to disable it. - -As an example, digest authentication may be enabled for a session -by calling C as follows: - - $zkh->add_auth('digest', "$username:$password"); - -Note that the username and password are transmitted in cleartext -to the ZooKeeper cluster. - -Such authentication credentials would enable access to a node -whose ACL contained an entry with a C attribute of -C<'digest'> and an C attribute containing a Base64-encoded -SHA1 digest of the string C<"$username:$password">. The -Perl modules Digest and MIME::Base64 may be used to create -such ACL ID values as follows: - - use Digest qw(); - use MIME::Base64 qw(); - - my $ctx = Digest->new('SHA-1')->add("$username:$password"); - my $digest = MIME::Base64::encode($ctx->digest()); - -Note that using the C method of the Digest module -will not result in digest strings with the "=" suffix characters -required by ZooKeeper. - -=head2 Logging - -As of ZooKeeper version 3.1.1, logging in the C client code is -implemented with a single, shared file handle to which all -of the internal POSIX threads write log messages; by default, -this file handle is attached to STDERR. - -Moreover, this file handle is shared by all active ZooKeeper -connections (each of which has its own private IO and completion -threads; see L above). - -Net::ZooKeeper therefore does not provide per-connection handle -attributes related to logging. The global function -C may be used to set the current -log level. See C<:log_levels> for a list of the available log -levels. The default log level is C. - -To capture ZooKeeper log messages to a file instead of STDERR, -redirect STDERR to a new file handle in the normal Perl manner: - - open(OLDERR, '>&', fileno(STDERR)) or - die("unable to dup STDERR: $!"); - open(STDERR, '>', $log_file) or - die("unable to redirect STDERR: $!"); - -=head2 Connection Order - -ZooKeeper clusters are typically made up of an odd number of -ZooKeeper servers. When connecting to such a cluster, the -C method should be passed a comma-separated list of -the hostnames and ports for each of the servers in the cluster, -e.g., C<'host1:7000,host2:7000,host2:7100'>. - -The default behaviour of the ZooKeeper client code is to -reorder this list randomly before making any connections. -A connection is then made to the first server in the reordered -list. If that connection fails, the IO thread will -automatically attempt to reconnect to the cluster, this time -to the next server in the list; when the last server in the list -is reached, the IO thread will continue again with the first -server. - -For certain purposes it may be necessary for ZooKeeper clients -to know the exact order in which the IO thread will attempt to -connect to the servers of a cluster. To do so, call -C. Note, -however, that this will affect all Net::ZooKeeper object -handles created by the current process. - -=head1 ATTRIBUTES - -=head2 Net::ZooKeeper - -The Net::ZooKeeper class provides the main interface to the -ZooKeeper client API. The following attributes are available -for each Net::ZooKeeper handle object and are specific to -that handle and the method calls invoked on it. As with DBI -handle objects, attributes may be read and written through -a hash interface, e.g.: - - print sprintf("Session timeout is %.2f seconds.\n", - $zkh->{session_timeout} / 1000); - - $zkh->{watch_timeout} = 10000; - -=over 4 - -=item hosts - -The comma-separated list of ZooKeeper server hostnames and ports -as passed to the C method. Note that by default the -ZooKeeper C client code will reorder this list before attempting -to connect for the first time; see L for details. - -This attribute is B and may not be modified. - -=item session_timeout - -The session timeout value, in milliseconds, as set by the -ZooKeeper server after connection. This value may not be -exactly the same as what was requested in the C<'session_timeout'> -option of the C method; the server will adjust the -requested timeout value so that it is within a certain range -of the server's C setting. See the ZooKeeper -documentation for details. - -Because the actual connection to the ZooKeeper server is -not made during the C method call but shortly -thereafter by the IO thread, note that this value may not -be initialized to its final value until at least one -other method which requires communication with the server -(such as C) has succeeded. - -This attribute is B and may not be modified. - -=item session_id - -The client's session ID value as set by the ZooKeeper server -after connection. This is a binary data string which may -be passed to subsequent C calls as the value of -the C<'session_id'> option, if the user wishes to attempt to -continue a session after a failure. Note that the server -may not honour such an attempt. - -Because the actual connection to the ZooKeeper server is -not made during the C method call but shortly -thereafter by the IO thread, note that this value may not -be initialized to its final value until at least one -other method which requires communication with the server -(such as C) has succeeded. - -This attribute is B and may not be modified. - -=item data_read_len - -The maximum length of node data that will be returned to -the caller by the C method. If a node's data exceeds -this length, the returned value will be shorter than the -actual node data as stored in the ZooKeeper cluster. - -The default maximum length of the node data returned by -C is 1023 bytes. This may be changed by setting -the C attribute to a different value. - -Passing a value for the C<'data_read_len'> option when calling -the C method will temporarily override the per-handle -maximum. - -=item path_read_len - -The maximum length of a newly created node's path that will -be returned to the caller by the C method. If the path -of the newly created node exceeds this length, the returned -value will be shorter than the actual path of the node as stored -in the ZooKeeper cluster. - -The default maximum length of the node path returned by -C is 1023 bytes. This may be changed by setting -the C attribute to a different value. - -Passing a value for the C<'path_read_len'> option when calling -the C method will temporarily override the current -value of this attribute. - -=item watch_timeout - -The C attribute value, in milliseconds, inherited by -all watch objects (of class Net::ZooKeeper::Watch) created by -calls to the C method. When a watch object's -C method is invoked without a C<'timeout'> option, -it waits for an event notification from the ZooKeeper cluster -for no longer than the timeout period specified by the value of -the watch object's C attribute. - -The default C attribute value for all watch objects -created by the C method is 1 minute (60000 -milliseconds). This may be changed for a particular handle -object by setting this attribute to a different value; afterwards, -the new value will be inherited by any watch objects created -by the handle object's C method. Previously -created watch objects will not be affected. - -Passing a value for the C<'timeout'> option when calling -the C method will temporarily override the current -value of this attribute and cause the newly created watch object -to inherit a different value. - -See also the C method, and the C attribute -and C method of the Net::ZooKeeper::Watch class. - -=item pending_watches - -The number of internal ZooKeeper watches created for this handle -object that are still awaiting an event notification from the -ZooKeeper cluster. - -Note that this number may be different than the number of -extant watch objects created by the handle object's C -method, not only because some event notifications may have -occurred, but also if any watch objects have been reassigned -by reusing them in more than one call to any of the C, -C, or C methods. - -This attribute is B and may not be modified. - -=back - -=head2 Net::ZooKeeper::Stat - -The Net::ZooKeeper::Stat class provides a hash interface to -the individual pieces of information which together compose the -state of a given ZooKeeper node. Net::ZooKeeper::Stat objects -are created by calling the C method on a Net::ZooKeeper -handle object, and may then be passed to any methods which accept -a C<'stat'> option value, such as C. - -Net::ZooKeeper::Stat objects may be reused multiple times. -If the Net::ZooKeeper method to which the stat object is -passed succeeds, then the stat object is updated with the newly -retrieved node state information, and any state information -previously stored in the stat object is overwritten. - -All of the attributes of stat objects are B. - -=over 4 - -=item ctime - -The creation time of the node in milliseconds since the epoch. - -=item mtime - -The time of the last modification of the node's data in -milliseconds since the epoch. - -=item data_len - -The length of the node's data in bytes. - -=item num_children - -The number of child nodes beneath of the current node. - -=item ephemeral_owner - -If the node was created with the C flag, -this attribute holds the session ID of the ZooKeeper client -which created the node. If the node was not created with -the C flag, this attribute is set to zero. - -=item version - -The number of revisions of the node's data. The ZooKeeper -cluster will increment this version number whenever the -node's data is changed. When the node is first created this -version number is initialized to zero. - -=item acl_version - -The number of revisions of the node's ACL. The ZooKeeper -cluster will increment this version number whenever the -node's ACL is changed. When the node is first created this -version number is initialized to zero. - -=item children_version - -The number of revisions of the node's list of child nodes. -The ZooKeeper cluster will increment this version number -whenever the list of child nodes is changed. When the node -is first created this version number is initialized to zero. - -=item czxid - -The ZooKeeper transaction ID (ZXID) of the transaction which -created the node. - -=item mzxid - -The ZooKeeper transaction ID (ZXID) of the transaction which -last modified the node's data. This is initially set to -the same transaction ID as the C attribute by the -C method. - -=item children_zxid - -The ZooKeeper transaction ID (ZXID) of the transaction which -last modified the node's list of child nodes. This is -initially set to the same transaction ID as the C -attribute by the C method. - -=back - -=head2 Net::ZooKeeper::Watch - -The Net::ZooKeeper::Watch class provides a hash interface -to the data returned by event notifications from the ZooKeeper -cluster. Net::ZooKeeper::Watch objects are created by calling -the C method on a Net::ZooKeeper handle object, and -may then be passed to any methods which accept a C<'watch'> -option value, such as C. - -Net::ZooKeeper::Watch objects may be reused multiple times. -Regardless of whether the Net::ZooKeeper method to which the -watch object is passed succeeds, the watch object will be -updated to receive an event notification exclusively for the -node referenced in that method call. In the case of an error, -however, the watch object may never receive any event -notification. - -=over 4 - -=item timeout - -The default timeout value, in milliseconds, for all -invocations of the C method made on the watch object. -When the C method is invoked without a -C<'timeout'> option value, it waits for an -event notification from the ZooKeeper cluster for no longer -than the timeout period specified by this attribute. -This default timeout period may be altered by setting this -attribute to a different value. - -Passing a value for the C<'timeout'> option when calling -the C method will temporarily override the current -value of this attribute and cause the C method to -use a different timeout period. - -When a Net::ZooKeeper handle object's C method is -invoked without a C<'timeout'> option, it returns a newly -created watch object whose C attribute value -is initialized to the current value of the handle object's -C attribute. When the C method is invoked -with a C<'timeout'> option, the new watch object's C -attribute value is initialized to the value specified by -the C<'timeout'> option. - -See also the C method, and the C attribute -and C method of the Net::ZooKeeper class. - -=item event - -The type of event which triggered the notification, such -as C if the node's data was changed. -See C<:events> for a list of the possible event types. -If zero, no event notification has occurred yet. - -Note that the events which will trigger a notification -will depend on the Net::ZooKeeper method to which -the watch object was passed. Watches set through the -C and C methods will report events relating -to the node's data, while watches set through the -C method will report events relating to the -creation or deletion of child nodes of the watched node. - -This attribute is B and may not be modified. - -=item state - -The state of the Net::ZooKeeper connection at the time of -the event notification. See C<:states> for a list of -the possible connection states. If zero, no event -notification has occurred yet. - -This attribute is B and may not be modified. - -=back - -=head1 METHODS - -=head2 Net::ZooKeeper - -The following methods are defined for the Net::ZooKeeper class. - -=over 4 - -=item new() - - $zkh = Net::ZooKeeper->new('host1:7000,host2:7000'); - $zkh = Net::ZooKeeper->new('host1:7000,host2:7000', - 'session_timeout' => $session_timeout, - 'session_id' => $session_id); - -Creates a new Net::ZooKeeper handle object and attempts to -connect to the one of the servers of the given ZooKeeper -cluster. As described in the L and -L sections, the ZooKeeper client code will -create an IO thread which maintains the connection with a -regular "heartbeat" request. In the event of a connection error -the IO thread will also attempt to reconnect to another one of -the servers using the same session ID. In general, these actions -should be invisible to the user, although Net::ZooKeeper methods -may return transient errors while the IO thread -reconnects with another server. - -To disconnect, undefine the Net::ZooKeeper handle object -or call the C method. (After calling C -the handle object can not be reused.) - -The ZooKeeper client code will send a "heartbeat" message -if a third of the session timeout period has elapsed without -any communication with the ZooKeeper server. A specific -session timeout period may be requested when creating a -Net::ZooKeeper handle object by supplying a value, in -milliseconds, for the C<'session_timeout'> option. The -ZooKeeper server adjust the requested timeout value so that -it is within a certain range of the server's C setting; -the actual session timeout value will be available as the -value of the handle's C attribute after at -least one method call has succeeded. See the C -attribute for more information. - -If no C<'session_timeout'> option is provided, the default -value of 10 seconds (10000 milliseconds) will be used in the -initial connection request; again, the actual timeout period to -which the server agrees will be available subsequently as the -value of the C attribute. - -Upon successful connection (i.e., after the success of a method -which requires communication with the server), the C -attribute will hold a short binary string which represents the -client's session ID as set by the server. All ephemeral nodes -created by the session are identified by this ID in the -C attribute of any Net::ZooKeeper::Stat objects -used to query their state. - -The ZooKeeper client code will use this session ID internally -whenever it tries to reconnect to another server in the ZooKeeper -cluster after detecting a failed connection. If it successfully -reconnects with the same session ID, the session will continue -and ephemeral nodes belonging to it will not be deleted. - -However, if the server determines that the session has timed -out (for example because no "heartbeat" requests have been -received within the agreed-upon session timeout period), the -session will be terminated by the cluster and all ephemeral nodes -owned by the current session automatically deleted. - -On occasion the ZooKeeper client code may not be able to quickly -reconnect to a live server and the caller may want to destroy -the existing Net::ZooKeeper handle object and attempt a -fresh connection using the same session ID as before with a -new Net::ZooKeeper object. To do so, save the C -attribute value before undefining the old handle object -and then pass that binary string as the value of the -C<'session_id'> option to the C method when creating the -next handle object. After the successful completion of a -method which requires communication with the server, if the -new handle object's C attribute value matches the -old session ID then the session has been successfully maintained; -otherwise, the old session was expired by the cluster. - -=item get_error() - - $code = $zkh->get_error(); - -Returns the ZooKeeper error code, if any, from the most -recent Net::ZooKeeper method invocation. The returned value -will be zero (equivalent to C) if no error occurred, -otherwise non-zero. Non-zero values may be compared to -the error code names exported by the C<:errors> tagset. - -See L for more details. - -=item add_auth() - - $zkh->add_auth('digest', "$username:$password"); - -The C method may be used to add authentication -credentials to a session. Once a credential has been added for -the current session, there is no way to disable it. - -When using the digest authentication scheme, note that the -username and password are transmitted in cleartext -to the ZooKeeper cluster. - -See L for additional details. - -=item create() - - $path = $zkh->create($req_path, $data); - $path = $zkh->create($req_path, $data, - 'flags' => (ZOO_EPHEMERAL | ZOO_SEQUENCE), - 'acl' => ZOO_OPEN_ACL_UNSAFE, - 'path_read_len' => 100); - -Requests that a node be created in the ZooKeeper cluster's -hierarchy with the given path and data. Upon success, -the returns the node's path, otherwise undef. - -The path returned by a successful C method call -may not be the new node's full path as it appears in the -ZooKeeper hierarchy, depending on the length of the actual -path and the value of the handle object's C -attribute. If the length of the actual path exceeds the -current value of the C attribute, the path -returned by the C method will be truncated; note -that the node's path in the ZooKeeper hierarchy is not -affected by this truncation. - -Specifying a value for the C<'path_read_len'> option will -temporarily override the value of the C -attribute for the duration of the C method. - -The flag values available for use with the C<'flags'> option -are C and C; both are -included in the C<:flags> tagset. The flags should be -combined with the bitwise OR operator if more than one -is required. - -The C flag causes the node to be marked as -ephemeral, meaning it will be automatically deleted if it -still exists when the client's session ends. The -C flag causes a unique integer to be appended -to the node's final path component. See the ZooKeeper -documentation for additional advice on how to use these flags. - -When creating a node it may be important to define an ACL -for it; to do this, pass a reference to an ACL array (as -described in L) using the C<'acl'> option. -See also the C<:acl_perms> and C<:acls> tagsets for lists -of the available ACL permission flags and pre-defined ACLs. - -=item delete() - - $ret = $zkh->delete($path); - $ret = $zkh->delete($path, 'version' => $version); - -Requests that a node be deleted from the ZooKeeper hierarchy. -Returns true upon success, false otherwise. - -If a value for the C<'version'> option is supplied, the node -will only be deleted if its version number matches the given -value. See the C attribute of the Net::ZooKeeper::Stat -class for details on node version numbering. - -=item exists() - - $ret = $zkh->exists($path); - $ret = $zkh->exists($path, 'stat' => $stat, 'watch' => $watch); - -Tests whether a given node exists. Returns true if the node -exists, otherwise false. When the C method is successful -but the node does not exist, it returns false, and C -will return C until another method is called on the -handle object. - -The C<'stat'> option may be used to request that a -Net::ZooKeeper::Stat object be updated with the node's -current state information. The stat object will only be -updated if the node exists and the C method -succeeds. The stat object must first have been created -using the C method. - -The C<'watch'> option may be used to request that a -Net::ZooKeeper::Watch object be assigned to receive -notification of an event which alters the node's data. -The watch object must first have been created using the -C method. If the watch object was previously -assigned to receive notifications for another node, it -will be reassigned even if the C method fails. - -=item get_children() - - @child_names = $zkh->get_children($path); - $num_children = $zkh->get_children($path, 'watch' => $watch); - -Queries the names or number of the child nodes stored beneath -a given node in the ZooKeeper hierarchy. In a list context, -returns a list of the child nodes' names upon success, otherwise -an empty list. When the C method is successful -but there are no child nodes, it returns an empty list, and -C will return C until another method is called -on the handle object. - -In a scalar context, C returns the number -of child nodes upon success, otherwise undef. - -The names of the child nodes are simply the final component -of the nodes' paths, i.e., the portion of their path which -follows the path of the given parent node, excluding the -"/" delimiter. - -The C<'watch'> option may be used to request that a -Net::ZooKeeper::Watch object be assigned to receive -notification of an event which alters the node's list of -child nodes. The watch object must first have been created -using the C method. If the watch object was -previously assigned to receive notifications for another node, -it will be reassigned even if the C method fails. - -=item get() - - $data = $zkh->get($path); - $data = $zkh->get($path, 'data_read_len' => 100, - 'stat' => $stat, 'watch' => $watch); - -Queries the data stored in a given node. Returns the -data as a string upon success, otherwise undef. Note -that the data may contain nulls if the node's data is -not a text string. - -If the length of the node's data exceeds the current value -of the handle object's C attribute, the -string returned by the C method will be truncated; -note that the node's data in the ZooKeeper cluster is not -affected by this truncation. - -Specifying a value for the C<'data_read_len'> option will -temporarily override the value of the C -attribute for the duration of the C method. - -The C<'stat'> option may be used to request that a -Net::ZooKeeper::Stat object be updated with the node's -current state information. The stat object will only be -updated if the C method succeeds. The stat object -must first have been created using the C method. - -The C<'watch'> option may be used to request that a -Net::ZooKeeper::Watch object be assigned to receive -notification of an event which alters the node's data. -The watch object must first have been created using the -C method. If the watch object was previously -assigned to receive notifications for another node, it -will be reassigned even if the C method fails. - -=item set() - - $ret = $zkh->set($path, $data); - $ret = $zkh->set($path, $data, 'version' => $version, - 'stat' => $stat); - -Requests that a node's data be updated in the ZooKeeper -hierarchy. Returns true upon success, false otherwise. - -If a value for the C<'version'> option is supplied, the node's -data will only be updated if its version number matches the -given value. See the C attribute of the -Net::ZooKeeper::Stat class for details on node version numbering. - -The C<'stat'> option may be used to request that a -Net::ZooKeeper::Stat object be updated with the node's -current state information. The stat object will only be -updated if the C method succeeds. The stat object -must first have been created using the C method. - -=item get_acl() - - @acl = $zkh->get_acl($path); - $num_acl_entries = $zkh->get_acl($path, 'stat' => $stat); - -Queries the ACL associated with a node in the ZooKeeper -hierarchy, if any. In a list context, returns an array with -the node's ACL entries upon success, otherwise -an empty list. When the C method is successful -but there are no ACL entries, it returns an empty list, and -C will return C until another method is called -on the handle object. - -The elements of the returned array are hashes, each of which -represents one ACL entry. Each hash contains C, -C, and C elements. See the L -section for additional details, and the -C<:acl_perms> and C<:acls> tagsets for lists of the -available ACL permission flags and pre-defined ACLs. - -In a scalar context, C returns the number -of ACL entries upon success, otherwise undef. - -The C<'stat'> option may be used to request that a -Net::ZooKeeper::Stat object be updated with the node's -current state information. The stat object will only be -updated if the C method succeeds. The stat object -must first have been created using the C method. - -=item set_acl() - - $acl = [{ - 'perms' => (ZOO_PERM_READ | ZOO_PERM_WRITE), - 'scheme' => 'digest', - 'id' => "$username:$digest" - }]; - $ret = $zkh->set_acl($path, $acl); - $ret = $zkh->set_acl($path, ZOO_OPEN_ACL_UNSAFE, - 'version' => $version); - -Requests that a node's ACL be updated in the ZooKeeper -hierarchy. Returns true upon success, false otherwise. - -The ACL should be passed as a reference to an array of -hashes, where each hash represents one ACL entry. Each -hash should contain C, C, and C elements -as described in the L section. -See also the C<:acl_perms> and C<:acls> tagsets for lists -of the available ACL permission flags and pre-defined ACLs. - -If a value for the C<'version'> option is supplied, the node's -ACL will only be updated if its version number matches the -given value. See the C attribute of the -Net::ZooKeeper::Stat class for details on node version numbering. - -=item stat() - - $stat = $zkh->stat(); - -Creates a new Net::ZooKeeper::Stat object which may be used -with the C<'stat'> option of the C, C, -C, and C methods. When the stat object -is passed to any of these methods, upon success its attribute -values are updated to reflect the current state of the -node specified in the method call. The stat object is not -updated if the method call does not succeed. - -=item watch() - - $watch = $zkh->watch(); - $watch = $zkh->watch('timeout' => $timeout); - -Creates a new Net::ZooKeeper::Watch object which may be -used to wait for event notifications from the ZooKeeper -cluster. Each time the watch object is passed to any -of the C, C, or C methods, -its attribute values are immediately reset to zero, and will -later be updated upon receipt of an appropriate event -notification for the node specified in the method call. - -The specific types of events which cause notifications to be -sent by the ZooKeeper cluster depend on the method call used. -After use with the C and C methods, the -watch object will be set to receive an event notification -caused by a modification of the node's data or the node itself -(e.g., deletion of the node). After use with the -C method, the watch object will be set to -receive an event notification caused by a modification -of the node's list of child nodes. - -Watch objects receive at most one event notification after -their assignment to a node by one of the C, -C, or C methods. Note that in the -case of an error, the watch object may never receive any -event notification. However, when the parent Net::ZooKeeper -handle object experiences a connection error, the ZooKeeper -client code will notify all pending watches with an event of -type C. See C for more information -regarding the watch object's attribute values after a -connection error. - -A watch object may be reused with another C, -C, or C method call at any time, -in which case the watch object's attribute values -are reset to zero and the watch object will no longer be updated -by any event notification relevant to the previous method call. - -When the C method is invoked without a C<'timeout'> -option, it returns a newly created watch object whose C -attribute value is initialized to the current value of the -Net::ZooKeeper handle object's C attribute. -Otherwise, when the C method is invoked with a -C<'timeout'> option, the new watch object's C attribute -value is initialized to the value specified by the -C<'timeout'> option. - -See also the C attribute, and the C -attribute and C method of the Net::ZooKeeper::Watch -class. - -=back - -=head2 Net::ZooKeeper::Stat - -No methods are defined for the Net::ZooKeeper::Stat class. - -=head2 Net::ZooKeeper::Watch - -Only one method is defined for the Net::ZooKeeper::Watch class. - -=over 4 - -=item wait() - - $ret = $watch->wait(); - $ret = $watch->wait('timeout' => $timeout); - -Waits for an event notification from the ZooKeeper cluster -for the node most recently associated with the watch object. -Nodes are associated with a watch object by passing the -watch object as the value of a C<'watch'> option to a -Net::ZooKeeper method; methods which accept a C<'watch'> option -are C, C, and C. - -When the C method is invoked with a C<'timeout'> -option, it waits for no more than the number of milliseconds -specified by the C<'timeout'> option. -Otherwise, when the C method is invoked without a -C<'timeout'> option, it waits for no more than the timeout -period specified by the value of the watch object's C -attribute. - -The C method returns true if an event notification -was received, otherwise false. When C returns true, -the C and C attributes of the watch object -will be updated with the event's type and the current -connection state. - -When the parent Net::ZooKeeper handle object experiences a -connection error, the ZooKeeper client code will notify all -pending watches with an event of type C. -In this case, the C attribute will report the current -state of the connection to the ZooKeeper cluster. - -See also the C attribute, and the C method -and C attribute of the Net::ZooKeeper class. - -=back - -=head1 FUNCTIONS - -The following functions have global scope and affect all -Net::ZooKeeper handle objects. - -=over 4 - -=item set_log_level() - - Net::ZooKeeper::set_log_level($level); - -The C function may be called to -alter the number and type of messages written to the current log -file handle (if any). The default value is C -which disables all logging. - -See the L section for more details and C<:log_levels> -for a list of the available log levels. - -=item set_deterministic_conn_order() - - Net::ZooKeeper::set_deterministic_conn_order(1); - -The C function -may be called to indicate whether or not the list of ZooKeeper -servers passed to the C method should be randomly permuted. -If set to a true value, the list of servers will not be altered. -The default false value indicates the list of servers will -be randomly reordered prior to connection. - -See the L section for more details. - -=back - -=head1 EXPORTS - -Nothing is exported by default. Various tagsets exist which -group the tags available for export into different categories: - -=over 4 - -=item :errors - -ZooKeeper error codes. These may be compared to the values -returned by the C method. - -=item :node_flags - -The ZooKeeper node flags C and C, -which may be passed in the C<'flags'> option to the C -method. When more than node flag is required they -should be combined using the bitwise OR operator. - -=item :acl_perms - -The ZooKeeper ACL permission flags which may be used in -the value of the C attribute of an ACL entry hash. -When more than one ACL permission flag is required they -should be combined using the bitwise OR operator. - -The available ACL permission flags are C, -C, C, C, -and C. For convenience, C is -defined as the bitwise OR of all of these flags. - -=item :acls - -Common ZooKeeper ACLs which may be useful. C -specifies a node which is entirely open to all users with no -restrictions at all. C specifies -a node which is readable by all users; permissions for other actions -are not defined in this ACL. C specifies a node -for which all actions require the same authentication credentials as -held by the session which created the node; this implies that a -session should authenticate with an appropriate scheme before -creating a node with this ACL. - -=item :events - -The ZooKeeper event types which are returned in value of -the C attribute a Net::ZooKeeper::Watch object after -an event occurs on a watched node. - -=item :states - -The ZooKeeper connection states which are returned in value of -the C attribute of a Net::ZooKeeper::Watch object after -an event occurs on a watched node. - -=item :log_levels - -The ZooKeeper log levels which may be passed to the -C function. The available -log levels are, from least to most verbose, C -(the default), C, C, -C, and C. - -=item :all - -Everything from all of the above tagsets. - -=back - -=head1 SEE ALSO - -The Apache ZooKeeper project's home page at -L provides a wealth of detail -on how to develop applications using ZooKeeper. - -=head1 AUTHOR - -Chris Darroch, Echrisd@apache.orgE - -=head1 COPYRIGHT AND LICENSE - -Licensed to the Apache Software Foundation (ASF) under one -or more contributor license agreements. See the NOTICE file -distributed with this work for additional information -regarding copyright ownership. The ASF licenses this file -to you under the Apache License, Version 2.0 (the -"License"); you may not use this file except in compliance -with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - -=cut -