Persistent::LDAP - A Persistent Class implemented using a LDAP Directory
use Persistent::LDAP; use English; # import readable variable names like $EVAL_ERROR
eval { ### in case an exception is thrown ###
### allocate a persistent object ###
my $person =
new Persistent::LDAP('localhost', 389,
'cn=Directory Manager', 'test1234',
'ou=Engineering,o=Big Snow Org,c=US');
### declare attributes of the object ###
$person->add_attribute('uid', 'ID', 'String');
$person->add_attribute('userpassword', 'Persistent', 'String');
$person->add_attribute('objectclass', 'Persistent', 'String');
$person->add_attribute('givenname', 'Persistent', 'String');
$person->add_attribute('sn', 'Persistent', 'String');
$person->add_attribute('cn', 'Persistent', 'String');
$person->add_attribute('mail', 'Persistent', 'String');
$person->add_attribute('telephonenumber', 'Persistent', 'String');
### query the datastore for some objects ###
$person->restore_where('& (objectclass=person)(mail=*bigsnow.org)',
'sn, givenname');
while ($person->restore_next()) {
printf("name = %s, email = %s\n",
$person->givenname . ' ' . $person->sn,
$person->mail);
}
};
if ($EVAL_ERROR) { ### catch those exceptions! ###
print "An error occurred: $EVAL_ERROR\n";
}
This is a Persistent class that uses a LDAP directory to store and retrieve objects. This class can be instantiated directly or subclassed. The methods described below are unique to this class, and all other methods that are provided by this class are documented in the Persistent documentation. The Persistent documentation has a very thorough introduction to using the Persistent framework of classes.
This class is part of the Persistent LDAP package which is available from:
http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent
Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the Persistent documentation for more information on exception handling in Perl.
use Persistent::LDAP;
eval {
my $obj = new Persistent::LDAP($host, $port,
$bind_dn, $password,
$base_dn);
};
croak "Exception caught: $@" if $@;
Allocates an object. This method throws Perl execeptions so use it with an eval block.
Parameters:
eval {
### set the data store ###
$ldap = $obj->datastore($host, $port, $bind_dn, $password,
$base_dn);
### or set it like this ###
$ldap = $obj->datastore($ldap, $base_dn);
### get the data store ###
$ldap = $obj->datastore();
};
croak "Exception caught: $@" if $@;
Returns (and optionally sets) the data store of the object. This method throws Perl execeptions so use it with an eval block.
Parameters:
Hostname or IP address of the remote (LDAP Directory) server
Port to connect to on the remote server
Bind to the LDAP directory with the given DN
Password for the bind DN
The base DN to start all searches/updates
Connection to the LDAP directory
eval {
$obj->insert();
};
croak "Exception caught: $@" if $@;
Inserts an object into the data store. This method throws Perl execeptions so use it with an eval block.
Parameters:
Returns:
See the Persistent documentation for more information.
eval {
$obj->update();
};
croak "Exception caught: $@" if $@;
Updates an object in the data store. This method throws Perl execeptions so use it with an eval block.
Parameters:
Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default.
This argument is useful if you are updating the Identity attributes of the object and you already have all of the attribute values so you do not need to restore the object (like a CGI request with hidden fields, maybe). So you can just set the Identity attributes of the object to the new values and then pass the old Identity values as arguments to the update method. For example, if Pebbles Flintstone married Bam Bam Rubble, then you could update her last name like this:
### Pebbles already exists in the data store, but we don't ### ### want to do an extra restore because we already have ### ### all of the attribute values ###
$person->uid('pflintstone'); ### new value of ID attribute ###
$person->sn('Rubble'); ### new lastname ###
$person->commonname('Pebbles'); ### old firstname ###
### set the rest of the attributes ... ###
$person->update('prubble'); ### old value of ID attribute ###
Or, if don't want to set all of the object's attributes, you can just restore it and then update it like this:
### restore object from data store ###
if ($person->restore('pflintstone')) {
$person->uid('prubble');
$person->sn('Rubble');
$person->update();
}
Returns:
A true value if the object previously existed in the data store (it was updated), and a false value if not (it was inserted).
See the Persistent documentation for more information.
eval {
$person->save();
};
croak "Exception caught: $@" if $@;
Saves an object to the data store. The object is inserted if it does not already exist in the data store, otherwise, it is updated. This method throws Perl execeptions so use it with an eval block.
Parameters:
Returns:
A true value if the object previously existed in the data store (it was updated), and a false value if not (it was inserted).
See the Persistent documentation for more information.
eval {
$obj->delete();
### or ###
$obj->delete(@id);
};
croak "Exception caught: $@" if $@;
Deletes an object from the data store. This method throws Perl execeptions so use it with an eval block.
Parameters:
Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default.
Returns:
A true value if the object previously existed in the data store (it was deleted), and a false value if not (nothing to delete).
See the Persistent documentation for more information.
eval {
$obj->restore(@id);
};
croak "Exception caught: $@" if $@;
Restores an object from the data store. This method throws Perl execeptions so use it with an eval block.
Parameters:
Values of the Identity attributes of the object. This method throws Perl execeptions so use it with an eval block.
Returns:
A true value if the object previously existed in the data store (it was restored), and a false value if not (nothing to restore).
See the Persistent documentation for more information.
use Persistent::LDAP;
eval {
### allocate a persistent object ###
my $person =
new Persistent::LDAP('localhost', 389,
'cn=Directory Manager', 'test1234',
'ou=Engineering,o=Big Snow Org,c=US');
### query the datastore for some objects ###
$person->restore_where('& (objectclass=person)(mail=*bigsnow.org)',
'sn, givenname');
while ($person->restore_next()) {
printf("name = %s, email = %s\n",
$person->givenname . ' ' . $person->sn,
$person->mail);
}
};
croak "Exception caught: $@" if $@;
Restores objects from the data store that meet the specified conditions. The objects are returned one at a time by using the restore_next method and in a sorted order if specified. This method throws Perl execeptions so use it with an eval block.
Since this is a LDAP implemented Persistent class, the
restore_where method expects a RFC-2254 compliant LDAP search filter as the first
argument, $where. Please see the
Net::LDAP::Filter documentation or RFC-2254 for more information. A good starting point for
finding RFCs on the web is the following:
http://www.yahoo.com/Computers_and_Internet/Standards/RFCs/
The second argument, $order_by, should be a valid SQL ORDER BY clause. Which is just a comma separated list of attribute values to sort by with an optional ASC or DESC token to sort in ascending or descending order. Please refer to a SQL reference for a more detailed explanation of ORDER BY clauses.
Since LDAP directories allow multiple values for an attribute, when an attribute with multiple values is used to sort by (used in an ORDER BY clause), only the first value of the attribute is used for sorting. For more information on attributes with multiple values, please see the following section in this document on using accessor methods.
Parameters:
Conditional expression for the requested objects. This is a RFC-2254 compliant LDAP search filter. This argument is optional.
Sort expression for the requested objects. The format of this expression is similar to a SQL ORDER BY clause. This argument is optional.
Returns:
The number of objects that match the conditions.
See the Persistent documentation for more information.
eval {
### getting attribute values ###
my $mail = $person->mail(); ### a single value ###
my @classes = $person->objectclass(); ### multiple values ###
### setting attribute values ###
$person->mail($newmail); ### a single value ###
my @new_classes = ('top', 'person', 'organizationalPerson');
$person->objectclass(@new_classes); ### multiple values ###
$person->objectclass(\@new_classes); ### multiple values by ref ###
};
croak "Exception caught: $@" if $@;
Sets/gets the value(s) of the attributes of the object. Since
this method is implemented using a LDAP directory, multiple values for an
attribute are allowed. So in order to handle this, the accessor methods can
be used in an array context or a scalar context. If the attribute has only
a single value then access it in a scalar context. And if the attribute
allows multiple values then access it in an array context. If the attribute
has multiple values and it is accessed in a scalar context only the first
value will be returned but if a single value is passed to it then the
attribute will be set to the single scalar value.
Example:
$person->objectclass('top', 'person', 'inetOrgPerson');
$class = $person->objectclass();
### $class == 'top' ###
@classes = $person->objectclass();
### @classes == ('top', 'person', 'inetOrgPerson') ###
This method throws Perl execeptions so use it with an eval block.
Parameters:
Value(s) of the attribute of the object. The
value(s) can be either a single scalar value, an array of
multiple values, or a reference to an array of multiple values.
Returns:
Returns a scalar value if used in a scalar context and returns an array when used in an array context.
See the Persistent documentation for more information.
eval {
### set the attributes ###
$person->data({givenname => 'Marge', sn => 'Simpson'});
### get and print the attributes ###
my $href = $person->data();
print "name = ", $href->{'givenname'} . ' ' . $href->{'sn'};
print "email = ", $href->{'mail'};
};
croak "Exception caught: $@" if $@;
Returns or sets all of the values of the attributes. If an attribute has multiple values then a reference to an array of values is returned for that attribute. And to set multiple values to an attribute, a reference to an array of values should be passed.
Example:
### get the multiple values for the attribute ###
my $href = $person->data();
my @classes = @{$href->{'objectclass'}}; ### superfluous copy ###
print "objectclasses = ", join(', ', @classes), "\n";
### set the multiple values for the attribute ###
my @new_classes = ('top', 'person');
$person->data({objectclass => \@new_classes});
This method throws Perl execeptions so use it with an eval block.
Parameters:
A hash with keys that are the names of the attributes and values that are
the values of the attributes. This argument is optional and is used for
setting the value(s) of the attributes.
Returns:
Same as the argument above except that it is the returned
value(s) of the attributes.
See the Persistent documentation for more information.
This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at:
winters@bigsnow.org
And you know, include the regular stuff, OS, Perl version, snippet of code, etc.
David Winters <winters@bigsnow.org>
Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.