Return-Path: Delivered-To: apmail-hadoop-zookeeper-commits-archive@minotaur.apache.org Received: (qmail 77810 invoked from network); 27 Apr 2009 18:08:27 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 27 Apr 2009 18:08:27 -0000 Received: (qmail 99086 invoked by uid 500); 27 Apr 2009 18:08:27 -0000 Delivered-To: apmail-hadoop-zookeeper-commits-archive@hadoop.apache.org Received: (qmail 99029 invoked by uid 500); 27 Apr 2009 18:08:27 -0000 Mailing-List: contact zookeeper-commits-help@hadoop.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: zookeeper-dev@ Delivered-To: mailing list zookeeper-commits@hadoop.apache.org Received: (qmail 99018 invoked by uid 99); 27 Apr 2009 18:08:27 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 27 Apr 2009 18:08:27 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 27 Apr 2009 18:08:19 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id AB4C523889DD; Mon, 27 Apr 2009 18:07:58 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r769079 [1/4] - in /hadoop/zookeeper/trunk: ./ src/contrib/zkperl/ src/contrib/zkperl/build/ src/contrib/zkperl/t/ Date: Mon, 27 Apr 2009 18:07:57 -0000 To: zookeeper-commits@hadoop.apache.org From: mahadev@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090427180758.AB4C523889DD@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: mahadev Date: Mon Apr 27 18:07:56 2009 New Revision: 769079 URL: http://svn.apache.org/viewvc?rev=769079&view=rev Log: ZOOKEEPER-378. perl binding for zookeeper (chris darroch via mahadev) Added: hadoop/zookeeper/trunk/src/contrib/zkperl/ hadoop/zookeeper/trunk/src/contrib/zkperl/Changes hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE hadoop/zookeeper/trunk/src/contrib/zkperl/README hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.xs hadoop/zookeeper/trunk/src/contrib/zkperl/build/ hadoop/zookeeper/trunk/src/contrib/zkperl/build.xml hadoop/zookeeper/trunk/src/contrib/zkperl/build/check_zk_version.c hadoop/zookeeper/trunk/src/contrib/zkperl/build/check_zk_version.h hadoop/zookeeper/trunk/src/contrib/zkperl/t/ hadoop/zookeeper/trunk/src/contrib/zkperl/t/10_invalid.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/15_thread.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/20_tie.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/22_stat_tie.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/24_watch_tie.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/30_connect.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/35_log.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/40_basic.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/45_class.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/50_access.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/60_watch.t hadoop/zookeeper/trunk/src/contrib/zkperl/t/util.pl hadoop/zookeeper/trunk/src/contrib/zkperl/typemap Modified: hadoop/zookeeper/trunk/CHANGES.txt Modified: hadoop/zookeeper/trunk/CHANGES.txt URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/CHANGES.txt?rev=769079&r1=769078&r2=769079&view=diff ============================================================================== --- hadoop/zookeeper/trunk/CHANGES.txt (original) +++ hadoop/zookeeper/trunk/CHANGES.txt Mon Apr 27 18:07:56 2009 @@ -114,6 +114,8 @@ ZOOKEEPER-29. Flexible quorums (flavio via mahadev) + ZOOKEEPER-378. perl binding for zookeeper (chris darroch via mahadev) + Release 3.1.0 - 2009-02-06 Non-backward compatible changes: Added: hadoop/zookeeper/trunk/src/contrib/zkperl/Changes URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/Changes?rev=769079&view=auto ============================================================================== --- hadoop/zookeeper/trunk/src/contrib/zkperl/Changes (added) +++ hadoop/zookeeper/trunk/src/contrib/zkperl/Changes Mon Apr 27 18:07:56 2009 @@ -0,0 +1,55 @@ +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 + Added: hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE?rev=769079&view=auto ============================================================================== --- hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE (added) +++ hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE Mon Apr 27 18:07:56 2009 @@ -0,0 +1,202 @@ + + 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. Added: hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST?rev=769079&view=auto ============================================================================== --- hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST (added) +++ hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST Mon Apr 27 18:07:56 2009 @@ -0,0 +1,22 @@ +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 Added: hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL?rev=769079&view=auto ============================================================================== --- hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL (added) +++ hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL Mon Apr 27 18:07:56 2009 @@ -0,0 +1,59 @@ +# 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 $zk_inc_path; +my $zk_lib_path; + +GetOptions( + 'zookeeper-include=s' => \$zk_inc_path, + 'zookeeper-lib=s' => \$zk_lib_path +); + +$zk_inc_path = defined($zk_inc_path) ? "-I$zk_inc_path " : ''; +$zk_lib_path = defined($zk_lib_path) ? "-L$zk_lib_path " : ''; + +my $cc = $Config{'cc'}; +my $check_file = 'build/check_zk_version'; + +my $check_out = + qx($cc -c $zk_inc_path -I. -c $check_file.c -o $check_file.o 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"); + } +} + +WriteMakefile( + 'INC' => "$zk_inc_path-I.", + 'LIBS' => [ "$zk_lib_path-lzookeeper_mt" ], + 'NAME' => 'Net::ZooKeeper', + 'VERSION_FROM' => 'ZooKeeper.pm', + 'clean' => { 'FILES' => 'build/check_zk_version.o' } +); + Added: hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE?rev=769079&view=auto ============================================================================== --- hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE (added) +++ hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE Mon Apr 27 18:07:56 2009 @@ -0,0 +1,6 @@ +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/). + Added: hadoop/zookeeper/trunk/src/contrib/zkperl/README URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/README?rev=769079&view=auto ============================================================================== --- hadoop/zookeeper/trunk/src/contrib/zkperl/README (added) +++ hadoop/zookeeper/trunk/src/contrib/zkperl/README Mon Apr 27 18:07:56 2009 @@ -0,0 +1,74 @@ +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 and is a sub-project of the Apache Hadoop +project. For details see the ZooKeeper home page at: + +http://hadoop.apache.org/zookeeper/ + +INSTALLATION + +To install this module type the following: + + perl Makefile.PL \ + --zookeeper-include=/path/to/zookeeper/client/include \ + --zookeeper-lib=/path/to/zookeeper/client/lib + make + ZK_TEST_HOSTS=host:port,... make test + make install + +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. + +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 + +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. + Added: hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm?rev=769079&view=auto ============================================================================== --- hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm (added) +++ hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm Mon Apr 27 18:07:56 2009 @@ -0,0 +1,1258 @@ +# 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.33'; + +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 and is a sub-project of the Apache Hadoop +project. + +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 and +hostname. 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 +