zookeeper-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From an...@apache.org
Subject [33/45] zookeeper git commit: ZOOKEEPER-3030: MAVEN MIGRATION - Step 1.3 - move contrib directories
Date Mon, 06 Aug 2018 12:14:42 GMT
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<DESTROY()> 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<create()> calls the ZooKeeper
-C function C<zoo_create()>, C<delete()> calls C<zoo_delete()>,
-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<CLONE_SKIP()> 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<fork()> 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<fork()>.
-
-=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<exists()> 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<get_error()> method
-may be called to examine the specific error code, if any.
-
-If C<get_error()> returns C<ZOK>, no error has occurred.  If the
-error code is less than C<ZAPIERROR>, it indicates a normal error
-condition reported by the ZooKeeper server, such as C<ZNONODE>
-(node does not exist) or C<ZNODEEXISTS> (node already exists).
-
-If the error code is greater than C<ZAPIERROR>, 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<skipACL=yes> 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<perms>, C<scheme>, and C<id>.  The C<perms> 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<get_acl()> 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<create()> method,
-and may be updated by passing an ACL array to the C<set_acl()> 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<add_auth()> 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<add_auth()> 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<scheme> attribute of
-C<'digest'> and an C<id> 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<b64digest()> 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</Internal POSIX Threads> above).
-
-Net::ZooKeeper therefore does not provide per-connection handle
-attributes related to logging.  The global function
-C<Net::ZooKeeper::set_log_level()> 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<ZOO_LOG_LEVEL_OFF>.
-
-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<new()> 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<Net::ZooKeeper::set_deterministic_conn_order(1)>.  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<new()> method.  Note that by default the
-ZooKeeper C client code will reorder this list before attempting
-to connect for the first time; see L</Connection Order> for details.
-
-This attribute is B<read-only> 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<new()> method; the server will adjust the
-requested timeout value so that it is within a certain range
-of the server's C<tickTime> setting.  See the ZooKeeper
-documentation for details.
-
-Because the actual connection to the ZooKeeper server is
-not made during the C<new()> 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<exists()>) has succeeded.
-
-This attribute is B<read-only> 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<new()> 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<new()> 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<exists()>) has succeeded.
-
-This attribute is B<read-only> 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<get()> 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<get()> is 1023 bytes.  This may be changed by setting
-the C<data_read_len> attribute to a different value.
-
-Passing a value for the C<'data_read_len'> option when calling
-the C<get()> 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<create()> 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<create()> is 1023 bytes.  This may be changed by setting
-the C<path_read_len> attribute to a different value.
-
-Passing a value for the C<'path_read_len'> option when calling
-the C<create()> method will temporarily override the current
-value of this attribute.
-
-=item watch_timeout
-
-The C<timeout> attribute value, in milliseconds, inherited by
-all watch objects (of class Net::ZooKeeper::Watch) created by
-calls to the C<watch()> method.  When a watch object's
-C<wait()> 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<timeout> attribute.
-
-The default C<timeout> attribute value for all watch objects
-created by the C<watch()> 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<watch()> method.  Previously
-created watch objects will not be affected.
-
-Passing a value for the C<'timeout'> option when calling
-the C<watch()> 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<watch()> method, and the C<timeout> attribute
-and C<wait()> 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<watch()>
-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<exists()>,
-C<get_children()>, or C<get()> methods.
-
-This attribute is B<read-only> 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<stat()> 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<exists()>.
-
-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<read-only>.
-
-=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<ZOO_EPHEMERAL> flag,
-this attribute holds the session ID of the ZooKeeper client
-which created the node.  If the node was not created with
-the C<ZOO_EPHEMERAL> 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<czxid> attribute by the
-C<create()> 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<czxid>
-attribute by the C<create()> 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<watch()> 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<exists()>.
-
-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<wait()> method made on the watch object.
-When the C<wait()> 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<wait()> method will temporarily override the current
-value of this attribute and cause the C<wait()> method to
-use a different timeout period.
-
-When a Net::ZooKeeper handle object's C<watch()> method is
-invoked without a C<'timeout'> option, it returns a newly
-created watch object whose C<timeout> attribute value
-is initialized to the current value of the handle object's
-C<watch_timeout> attribute.  When the C<watch()> method is invoked
-with a C<'timeout'> option, the new watch object's C<timeout>
-attribute value is initialized to the value specified by
-the C<'timeout'> option.
-
-See also the C<wait()> method, and the C<watch_timeout> attribute
-and C<watch()> method of the Net::ZooKeeper class.
-
-=item event
-
-The type of event which triggered the notification, such
-as C<ZOO_CHANGED_EVENT> 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<exists()> and C<get()> methods will report events relating
-to the node's data, while watches set through the
-C<get_children()> method will report events relating to the
-creation or deletion of child nodes of the watched node.
-
-This attribute is B<read-only> 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<read-only> 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</Internal POSIX Threads> and
-L</Connection Order> 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<DESTROY()> method.  (After calling C<DESTROY()>
-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<tickTime> setting;
-the actual session timeout value will be available as the
-value of the handle's C<session_timeout> attribute after at
-least one method call has succeeded.  See the C<session_timeout>
-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<session_timeout> attribute.
-
-Upon successful connection (i.e., after the success of a method
-which requires communication with the server), the C<session_id>
-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<ephemeral_owner> 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<session_id>
-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<new()> 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<session_id> 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<ZOK>) 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</Error Handling> for more details.
-
-=item add_auth()
-
-  $zkh->add_auth('digest', "$username:$password");
-
-The C<add_auth()> 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</Access Control> 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<create()> 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<path_read_len>
-attribute.  If the length of the actual path exceeds the
-current value of the C<path_read_len> attribute, the path
-returned by the C<create()> 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<path_read_len>
-attribute for the duration of the C<create()> method.
-
-The flag values available for use with the C<'flags'> option
-are C<ZOO_EPHEMERAL> and C<ZOO_SEQUENCE>; 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<ZOO_EPHEMERAL> 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<ZOO_SEQUENCE> 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</Access Control>) 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<version> 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<exists()> method is successful
-but the node does not exist, it returns false, and C<get_error()>
-will return C<ZNONODE> 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<exists()> method
-succeeds.  The stat object must first have been created
-using the C<stat()> 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<watch()> method.  If the watch object was previously
-assigned to receive notifications for another node, it
-will be reassigned even if the C<exists()> 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<get_children()> method is successful
-but there are no child nodes, it returns an empty list, and
-C<get_error()> will return C<ZOK> until another method is called
-on the handle object.
-
-In a scalar context, C<get_children()> 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<watch()> method.  If the watch object was
-previously assigned to receive notifications for another node,
-it will be reassigned even if the C<get_children()> 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<data_read_len> attribute, the
-string returned by the C<get()> 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<data_read_len>
-attribute for the duration of the C<get()> 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<get()> method succeeds.  The stat object
-must first have been created using the C<stat()> 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<watch()> method.  If the watch object was previously
-assigned to receive notifications for another node, it
-will be reassigned even if the C<get()> 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<version> 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<set()> method succeeds.  The stat object
-must first have been created using the C<stat()> 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<get_acl()> method is successful
-but there are no ACL entries, it returns an empty list, and
-C<get_error()> will return C<ZOK> 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<perms>,
-C<scheme>, and C<id> elements.  See the L</Access Control>
-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<get_acl()> 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<get_acl()> method succeeds.  The stat object
-must first have been created using the C<stat()> 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<perms>, C<scheme>, and C<id> elements
-as described in the L</Access Control> 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<version> 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<exists()>, C<get()>,
-C<set()>, and C<get_acl()> 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<exists()>, C<get_children()>, or C<get()> 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<exists()> and C<get()> 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<get_children()> 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<exists()>,
-C<get_children()>, or C<get()> 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<ZOO_SESSION_EVENT>.  See C<wait()> for more information
-regarding the watch object's attribute values after a
-connection error.
-
-A watch object may be reused with another C<exists()>,
-C<get_children()>, or C<get()> 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<watch()> method is invoked without a C<'timeout'>
-option, it returns a newly created watch object whose C<timeout>
-attribute value is initialized to the current value of the
-Net::ZooKeeper handle object's C<watch_timeout> attribute.
-Otherwise, when the C<watch()> method is invoked with a
-C<'timeout'> option, the new watch object's C<timeout> attribute
-value is initialized to the value specified by the
-C<'timeout'> option.
-
-See also the C<watch_timeout> attribute, and the C<timeout>
-attribute and C<wait()> 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<exists()>, C<get_children()>, and C<get()>.
-
-When the C<wait()> 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<wait()> 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<timeout>
-attribute.
-
-The C<wait()> method returns true if an event notification
-was received, otherwise false.  When C<wait()> returns true,
-the C<event> and C<state> 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<ZOO_SESSION_EVENT>.
-In this case, the C<state> attribute will report the current
-state of the connection to the ZooKeeper cluster.
-
-See also the C<timeout> attribute, and the C<watch()> method
-and C<watch_timeout> 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<Net::ZooKeeper::set_log_level()> 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<ZOO_LOG_LEVEL_OFF>
-which disables all logging.
-
-See the L</Logging> 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<Net::ZooKeeper::set_deterministic_conn_order()> function
-may be called to indicate whether or not the list of ZooKeeper
-servers passed to the C<new()> 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</Connection Order> 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<get_error()> method.
-
-=item :node_flags
-
-The ZooKeeper node flags C<ZOO_EPHEMERAL> and C<ZOO_SEQUENCE>,
-which may be passed in the C<'flags'> option to the C<create()>
-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<perms> 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<ZOO_PERM_READ>,
-C<ZOO_PERM_WRITE>, C<ZOO_PERM_CREATE>, C<ZOO_PERM_DELETE>,
-and C<ZOO_PERM_ADMIN>.  For convenience, C<ZOO_PERM_ALL> is
-defined as the bitwise OR of all of these flags.
-
-=item :acls
-
-Common ZooKeeper ACLs which may be useful.  C<ZOO_OPEN_ACL_UNSAFE>
-specifies a node which is entirely open to all users with no
-restrictions at all.  C<ZOO_READ_ACL_UNSAFE> specifies
-a node which is readable by all users; permissions for other actions
-are not defined in this ACL.  C<ZOO_CREATOR_ALL_ACL> 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<event> 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<state> 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<Net::ZooKeeper::set_log_level()> function.  The available
-log levels are, from least to most verbose, C<ZOO_LOG_LEVEL_OFF>
-(the default), C<ZOO_LOG_LEVEL_ERROR>, C<ZOO_LOG_LEVEL_WARN>,
-C<ZOO_LOG_LEVEL_INFO>, and C<ZOO_LOG_LEVEL_DEBUG>.
-
-=item :all
-
-Everything from all of the above tagsets.
-
-=back
-
-=head1 SEE ALSO
-
-The Apache ZooKeeper project's home page at
-L<http://zookeeper.apache.org/> provides a wealth of detail
-on how to develop applications using ZooKeeper.
-
-=head1 AUTHOR
-
-Chris Darroch, E<lt>chrisd@apache.orgE<gt>
-
-=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
-


Mime
View raw message