/ 
Net-LDAP-Class-0.27
River stage zero No dependents
/ Net::LDAP::Class

NAME

Net::LDAP::Class - object-relational mapper for Net::LDAP

SYNOPSIS

# define your class

package MyLDAPClass;
use base qw( Net::LDAP::Class );

__PACKAGE__->metadata->setup(
   attributes          => [qw( name address phone email )],
   unique_attributes   => [qw( email )],
   base_dn             => 'dc=mycompany,dc=com',
);

1;

# then use your class

use MyLDAPClass;
use Net::LDAP;

my $ldap = create_Net_LDAP_object_and_bind();  # you write this

# create an instance of your class
my $person = MyLDAPClass->new( ldap => $ldap, email => 'foo@bar.com' );

# load from LDAP or write if not yet existing
$person->read or $person->create;

# set the 'name' attribute
$person->name( 'Joe Foo' );

# write your changes 
$person->update;

# change your mind?
$person->delete;

DESCRIPTION

Net::LDAP::Class (NLC) is an object-relational mapping for LDAP.

I know, it's all wrong to confuse the ORM model with LDAP since LDAP is not relational in the same way that a RDBMS is. But the ORM APIs of projects like DBIx::Class and Rose::DB::Object are so fun and easy to use, it seemed like LDAP management should be just as fun and easy.

The architecture of this package is based on Rose::DB::Object, which the author uses to great effect for RDBMS management.

METHODS

NLC uses the Rose::Object package to create methods and handle the mundane get/set features. In addition, Net::LDAP::Class::MethodMaker implements a new method type called related_objects which handles the get/set/fetch of NLC objects related to a given NLC object. Typically these are Users and Groups. A User is typically related to one or more Groups, and a Group is typically related to one or more Users. See Net::LDAP::Class::User and Net::LDAP::Class::Group for examples.

There are some methods which every NLC subclass must implement. See SUBCLASSING for details.

init

Override this in a subclass. Be sure to call SUPER::init in your subclass.

metadata_class

Returns 'Net::LDAP::Class::Metadata' by default.

metadata

Returns an instance of the metadata_class() containing all the metadata for the NLC class. May be called as a class or object method.

init_ldap

If you do not pass a Net::LDAP object to new(), you may instead set the ldap_uri() class method to a URI string and init_ldap() will create a Net::LDAP object and bind() it for you.

Returns a Net::LDAP object.

init_debug

Sets the default debug flag to whatever the PERL_DEBUG or LDAP_DEBUG env variable is set to.

init_ldap_entry

Returns undef by default.

get_ldap_error( ldap_msg )

Stringify the error message for the ldap_msg object.

stringify

Returns the first unique attribute value that is not undef. If no such value is found, returns the object.

By default all NLC-derived objects are overloaded with this method.

find( opts )

Returns array (or array ref if called in scalar context) of objects matching opts.

opts may include:

ldap

If not present, the ldap() method is called instead.

base_dn

If not present, the base_dn() method is called instead.

Any other opts are passed directly to the Net::LDAP search() method.

Returns undef if no results matching opts are found.

create

Write a new object to the database. Calls the action_for_create() method -- see SUBCLASSING.

read

Read an object's attribute values from the database. You must have previously set at least one unique attribute in the object in order for the read() to work.

Returns the object on success, undef if the object was not found.

update

Write changes to the database. Calls action_for_update() -- see SUBCLASSING.

If no changes are detected, aborts and returns undef.

On successful write, returns the value of read().

delete

Remove the object from the database. You must call read() first.

Returns the value of do_batch().

read_or_create

Convenience method. If read() returns undef, create() is called. Returns the object in any case.

save

Convenience method. If ldap_entry() is set, update() is called. Otherwise, read_or_create() is called. The NLC object is returned in any case.

validate( attr_name, attr_value )

Called by MethodMaker every time an attribute is set with a MethodMaker-created method.

If validate() returns true, attr_value is set. If validate() returns false, a fatal error is thrown and error() set.

This method should be overriden in your subclass to provide schema-specific validation. The default behaviour is a no-op (always returns true).

do_batch( array_of_actions )

Creates (if batch() is not already set) and runs a Net::LDAP::Batch object, passing it the array_of_actions to run. Will croak on any error.

Returns the Net::LDAP::Batch object on success.

add_to_batch( array_of_actions )

Initializes (if necessary) and adds array_of_actions to the Net::LDAP::Batch object in batch().

rollback

Will call the rollback() method on the Net::LDAP::Batch object returned by batch(). If there is not batch() set, will croak.

action_for_create

See SUBCLASSING.

action_for_update

See SUBCLASSING.

action_for_delete

See SUBCLASSING.

check_unique_attributes_set

Returns true (1) if any unique attribute is set with a defined value.

Returns false (0) if no unique attributes are set.

AUTOLOAD

Will croak() with a helpful message if you call a method that does not exist. Mostly useful for catching cases where you forget to predefine an attribute.

dump

Returns Data::Dump::dump output for the NLC object. Useful for debugging. See also the Net::LDAP::Entry dump() method which can be called on the ldap_entry value.

$nlc->dump;                # same as Data::Dump::dump( $nlc )
$nlc->ldap_entry->dump;    # see Net::LDAP::Entry dump() method

has_local_changes

Convenience method. Returns true if the object has had any values set since the last time it was written to the server.

batch

Get/set the Net::LDAP::Batch object for the current transaction. Typically you don't want to mess with this but documented for completeness.

prev_batch

Get/set the Net::LDAP::Batch object for the just-completed transaction. Typically you don't want to mess with this but documented for completeness.

act_on_all( code_ref [, opts] )

Performs coderef sub reference on all records in LDAP. The coderef should expect one argument: a Net::LDAP::Class-derived object.

act_on_all() operates using Net::LDAP::Control::Paged, performing a search() using a filter based on unique_attributes() and iterating over all matches in groups of (by default) 500. You may set the pager size in opts. opts should be a hash ref. The following key/value pairs are supported:

page_size

Default: 500. Sets the Net::LDAP::Control::Paged size.

filter

Default: unique_atttributes->[0] = '*'

Set the filter for the search.

ldap

A Net::LDAP object. Required if you call act_on_all() as a class method.

Returns the number of Net::LDAP::Class results acted upon.

isa_user

Convenience method. Just returns shift->isa('Net::LDAP::Class::User').

isa_group

Just like isa_user() but checks the Net::LDAP::Class::Group.

SUBCLASSING

NLC is designed as a base class with basic default behaviours for most common usage. However, every subclass must implement some methods, usually because such methods are specific to the particular LDAP schema you are using with the subclass.

The following methods are required by every NLC subclass. These action_for_* methods should return either a Net::LDAP::Batch::Action-based object or an array of values that can be passed to the add_actions() method of the Net::LDAP::Batch class.

See Net::LDAP::Class::User::POSIX and Net::LDAP::Class::Group::POSIX for examples.

  • action_for_create

  • action_for_update

  • action_for_delete

In addition, if you use the related_objects MethodMaker feature, then your subclass must implement a fetch_method_name method for each related_objects method name. Again, see Net::LDAP::Class::User::POSIX and Net::LDAP::Class::Group::POSIX for examples.

AUTHOR

Peter Karman, <karman at cpan.org>

BUGS

Please report any bugs or feature requests to bug-net-ldap-class at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-LDAP-Class. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::LDAP::Class

You can also look for information at:

ACKNOWLEDGEMENTS

The Minnesota Supercomputing Institute http://www.msi.umn.edu/ sponsored the development of this software.

COPYRIGHT

Copyright 2008 by the Regents of the University of Minnesota. All rights reserved.

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

SEE ALSO

Net::LDAP, Net::LDAP::Batch