NAME

SPOPS::LDAP - Implement object persistence in an LDAP datastore

SYNOPSIS

 use strict;
 use SPOPS::Initialize;

 # Normal SPOPS configuration

 my $config = {
    class      => 'My::LDAP',
    isa        => [ qw/ SPOPS::LDAP / ],
    field      => [ qw/ cn sn givenname displayname mail
                        telephonenumber objectclass uid ou / ],
    id_field   => 'uid',
    ldap_base_dn => 'ou=People,dc=MyCompany,dc=com',
    multivalue => [ qw/ objectclass / ],
    creation_security => {
                 u => undef,
                 g   => { 3 => 'WRITE' },
                 w   => 'READ',
    },
    track        => { create => 0, update => 1, remove => 1 },
    display      => { url => '/Person/show/' },
    name         => 'givenname',
    object_name  => 'Person',
 };

 # Minimal connection handling...

 sub My::LDAP::global_datasource_handle {
     my $ldap = Net::LDAP->new( 'localhost' );
     $ldap->bind;
     return $ldap;
 }

 # Create the class

 SPOPS::Initialize->process({ config => $config });

 # Search for a group of objects and display information

 my $ldap_filter = '&(objectclass=inetOrgPerson)(mail=*cwinters.com)';
 my $list = My::LDAP->fetch_group({ where => $ldap_filter });
 foreach my $object ( @{ $list } ) {
     print "Name: $object->{givenname} at $object->{mail}\n";
 }

 # The same thing, but with an iterator

 my $ldap_filter = '&(objectclass=inetOrgPerson)(mail=*cwinters.com)';
 my $iter = My::LDAP->fetch_iterator({ where => $ldap_filter });
 while ( my $object = $iter->get_next ) {
     print "Name: $object->{givenname} at $object->{mail}\n";
 }

DESCRIPTION

This class implements object persistence in an LDAP datastore. It is similar to SPOPS::DBI but with some important differences -- LDAP gurus can certainly find more:

LDAP supports multiple-valued properties.
Rather than tables, LDAP supports a hierarchy of data information, stored in a tree. An object can be at any level of a tree under a particular branch.
LDAP supports referrals, or punting a query off to another server. (SPOPS does not support referrals yet, but we fake it with SPOPS::LDAP::MultiDatasource.)

CONFIGURATION

See SPOPS::Manual::Configuration for the configuration fields used and LDAP-specific issues.

METHODS

Configuration Methods

See relevant discussion for each of these items under CONFIGURATION (configuration key name is the same as the method name).

base_dn (Returns: $)

ldap_objectclass (Returns: \@) (optional)

id_value_field (Returns: $) (optional)

Datasource Methdods

global_datasource_handle( [ $connect_key ] )

You need to create a method to return a datasource handle for use by the various methods of this class. You can also pass in a handle directory using the parameter 'ldap':

 # This object has a 'global_datasource_handle' method

 my $object = My::Object->fetch( 'blah' );

 # This object does not

 my $object = Your::Object->fetch( 'blah', { ldap => $ldap });

Should return: Net::LDAP (or compatible) connection object that optionally maps to $connect_key.

You can configure your objects to use multiple datasources when certain conditions are found. For instance, you can configure the "fetch()" operation to cycle through a list of datasources until an object is found -- see SPOPS::LDAP::MultiDatasource for an example.

Class Initialization

class_initialize()

Just create the 'field_list' configuration parameter.

Object Information

dn( [ $new_dn ] )

Retrieves and potentially sets the DN (distinguished name) for a particular object. This is done automatically when you call "fetch()" or "fetch_group()" to retrieve objects so you can always access the DN for an object. If the DN is empty the object has not yet been serialized to the LDAP datastore. (You can also call the SPOPS method "is_saved()" to check this.)

Returns: DN for this object

build_dn()

Builds a DN from an object -- you should never need to call this and it might disappear in future versions, only to be used internally.

Object Serialization

Note that you can pass in the following parameters for any of these methods:

ldap: A Net::LDAP connection object.
connect_key: A connection key to use for a particular LDAP connection.

fetch( $id, \%params )

Retrieve an object with ID $id or matching other specified parameters.

Parameters:

•

filter ($)

Use the given filter to find an object. Note that the method will die if you get more than one entry back as a result.

(Synonym: 'where')

fetch_by_dn( $dn, \%params )

Retrieve an object by a full DN ($dn).

fetch_group( \%params )

Retrieve a group of objects

fetch_iterator( \%params )

Instead of returning an arrayref of results, return an object of class SPOPS::Iterator::LDAP.

Parameters are the same as "fetch_group()".

save( \%params )

Save an LDAP object to the datastore. This is quite straightforward.

remove( \%params )

Remove an LDAP object to the datastore. This is quite straightforward.

BUGS

Renaming of DNs not supported

Moving an object from one DN to another is not currently supported.

TO DO

Documentation

("This is quite straightforward" does not cut it.)

More Usage

I have only tested this on an OpenLDAP (version 2.0.11) server. Since we are using Net::LDAP for the interface, we should (in theory) have no problems connecting to other LDAP servers such as iPlanet Directory Server, Novell NDS or Microsoft Active Directory.

It would also be good to test with a wider variety of schemas and objects.

Expand LDAP Interfaces

Currently we use Net::LDAP to interface with the LDAP directory, but Perl/C libraries may be faster and provide different features. Once this is needed, we will probably need to create implementation-specific subclasses. This should not be very difficult -- the actual calls to Net::LDAP are minimal and straightforward.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>