David Winters > Persistent-LDAP-0.50 > Persistent::LDAP

Download:
Persistent-LDAP-0.50.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.50   Source  

NAME ^

Persistent::LDAP - A Persistent Class implemented using a LDAP Directory

SYNOPSIS ^

  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";
  }

ABSTRACT ^

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

DESCRIPTION ^

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.

METHODS ^

new -- Object Constructor

  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:

These are the same as for the datastore method below.

datastore -- Sets/Returns the Data Store 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:

$host

Hostname or IP address of the remote (LDAP Directory) server

$port

Port to connect to on the remote server

$bind_dn

Bind to the LDAP directory with the given DN

$password

Password for the bind DN

$base_dn

The base DN to start all searches/updates

$ldap (also a return value)

Connection to the LDAP directory

insert -- Insert an Object into the Data Store

  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:

None.

Returns:

None.

See the Persistent documentation for more information.

update -- Update an Object in the Data Store

  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:

@id

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:

$flag

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.

save -- Save an Object to the Data Store

  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:

None.

Returns:

$flag

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.

delete -- Delete an Object from the Data Store

  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:

@id

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:

$flag

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.

restore -- Restore an Object from the Data Store

  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:

@id

Values of the Identity attributes of the object. This method throws Perl execeptions so use it with an eval block.

Returns:

$flag

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.

restore_where -- Conditionally Restoring Objects

  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:

$where

Conditional expression for the requested objects. This is a RFC-2254 compliant LDAP search filter. This argument is optional.

$order_by

Sort expression for the requested objects. The format of this expression is similar to a SQL ORDER BY clause. This argument is optional.

Returns:

$num_of_objs

The number of objects that match the conditions.

See the Persistent documentation for more information.

Accessor Methods -- Accessing the Attributes of an Object

  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 or @values or \@values

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:

$value or @values

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.

data -- Accessing the Attribute Data of an Object

  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:

\%hash

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:

\%hash

Same as the argument above except that it is the returned value(s) of the attributes.

See the Persistent documentation for more information.

SEE ALSO ^

Persistent, Persistent::Base

BUGS ^

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.

AUTHORS ^

  David Winters <winters@bigsnow.org>

COPYRIGHT ^

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.

syntax highlighting: