Connector - a generic connection to a hierarchical-structured data set
The Connector is generic connection to a data set, typically configuration data in a hierarchical structure. Each connector object accepts the get(KEY) method, which, when given a key, returns the associated value from the connector's data source.
Typically, a connector acts as a proxy to a simple data source like YAML, Config::Std, Config::Versioned, or to a more complex data source like an LDAP server or Proc::SafeExec. The standard calling convention via get(KEY) makes the connectors interchangeable.
In addition, a set of meta-connectors may be used to combine multiple connectors into more complex chains. The Connector::Multi, for example, allows for redirection to delegate connectors via symbolic links. If you have a list of connectors and want to use them in a load-balancing, round-robin fashion or have the list iterated until a value is found, use Connector::List and choose the algorithm to perform.
use Connector::MODULENAME; my $conn = Connector::MODULENAME->new( { LOCATION => $path_to_config_for_module, }); my $val = $conn->get('full.name.of.key');
This is the base class for all Connector implementations. It provides common helper methods and performs common sanity checking.
Usually this class should not be instantiated directly.
Set to true if you want the connector to die when a query reaches a non-exisiting node. This will affect only calls to get/get_list/get_hash and will not affect values that are explicitly set to undef (if supported by the connector!).
Each accessor method is valid only special types of nodes. If you call them on a wrong type of node, the connector dies.
Basic method to obtain a scalar value at the leaf of the config tree.
my $value = $connector->get('smartcard.owners.tokenid.bob');
Each implementation must also accept an arrayref as path. The path is contructed from the elements. The default behaviour allows strings using the delimiter character inside an array element. If you want each array element to be parsed, you need to pass "RECURSEPATH => 1" to the constructor.
my $value = $connector->get( [ 'smartcard','owners','tokenid','bob.builder' ] );
Some implementations accept control parameters, which can be passed by params, which is a hash ref of key => value pairs.
my $value = $connector->get( 'smartcard.owners.tokenid.bob' , { version => 1 } );
This method is only valid if it is called on a "n-1" depth node representing an ordered list of items (array). The return value is an array with all values present below the node.
my @items = $connector->get_list( 'smartcard.owners.tokenid' );
This method is only valid if it is called on a "n-1" depth node representing an ordered list of items (array). The return value is the number of elements in this array (including undef elements if they are explicitly given).
my $count = $connector->get_size( 'smartcard.owners.tokens.bob' );
If the node does not exist, 0 is returned.
This method is only valid if it is called on a "n-1" depth node representing a key => value list (hash). The return value is a hash ref.
my %data = %{$connector->get_hash( 'smartcard.owners.tokens.bob' )};
This method is only valid if it is called on a "n-1" depth node representing a key => value list (hash). The return value is an array holding the values of all keys (including undef elements if they are explicitly given).
my @keys = $connector->get_keys( 'smartcard.owners.tokens.bob' );
If the node does not exist, an empty list is returned.
The set method is a "all in one" implementation, that is used for either type of value. If the value is not a scalar, it must be passed by reference.
$connector->set('smartcard.owners.tokenid.bob', $value, $params);
The value parameter holds a scalar or ref to an array/hash with the data to be written. params is a hash ref which holds additional parameters for the operation and can be undef if not needed.
This method returns some structural information about the current node as hash ref. At minimum it must return the type of node at the current path.
Valid values are scalar, list, hash, reference. Reference is a scalar reference which is used e.g. in Connector::Multi. The others correspond to the accessor methods given above.
my $meta = $connector->get_meta( 'smartcard.owners' ); my $type = $meta->{TYPE};
If the node does not exist, undef is returned. get_meta will NOT die even if die_on_undef is set, therefore you can use it to probe for a node.
get_meta
die_on_undef
You should always pass the first parameter to the private _build_path method. This method converts any valid path spec representation to a valid path. It takes care of the RECURSEPATH setting and returns the path elements as list.
_build_path
The methods get, get_list, get_size, get_hash, get_keys, set, meta are routed to the appropriate connector.
Scott Hardin <mrscotty@cpan.org>
Martin Bartosch
Oliver Welter
Copyright 2013 OpenXPKI Foundation
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
Unknown directive: =head
To install Connector, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Connector
CPAN shell
perl -MCPAN -e shell install Connector
For more information on module installation, please visit the detailed CPAN module installation guide.