Net::LDAP::Class - object-relational mapper for Net::LDAP
# 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 => 'email@example.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;
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.
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.
Override this in a subclass. Be sure to call SUPER::init in your subclass.
Returns 'Net::LDAP::Class::Metadata' by default.
Returns an instance of the metadata_class() containing all the metadata for the NLC class. May be called as a class or object method.
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.
Sets the default debug flag to whatever the PERL_DEBUG or LDAP_DEBUG env variable is set to.
Returns undef by default.
Stringify the error message for the ldap_msg object.
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.
Returns array (or array ref if called in scalar context) of objects matching opts.
opts may include:
If not present, the ldap() method is called instead.
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.
Write a new object to the database. Calls the action_for_create() method -- see SUBCLASSING.
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.
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().
Remove the object from the database. You must call read() first.
Returns the value of do_batch().
Convenience method. If read() returns undef, create() is called. Returns the object in any case.
Convenience method. If ldap_entry() is set, update() is called. Otherwise, read_or_create() is called. The NLC object is returned in any case.
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).
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.
Initializes (if necessary) and adds array_of_actions to the Net::LDAP::Batch object in batch().
Will call the rollback() method on the Net::LDAP::Batch object returned by batch(). If there is not batch() set, will croak.
Returns true (1) if any unique attribute is set with a defined value.
Returns false (0) if no unique attributes are set.
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.
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
Convenience method. Returns true if the object has had any values set since the last time it was written to the server.
Get/set the Net::LDAP::Batch object for the current transaction. Typically you don't want to mess with this but documented for completeness.
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.
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:
Default: 500. Sets the Net::LDAP::Control::Paged size.
Default: unique_atttributes-> = '*'
Set the filter for the search.
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.
Convenience method. Just returns shift->isa('Net::LDAP::Class::User').
Just like isa_user() but checks the Net::LDAP::Class::Group.
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.
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.
<karman at cpan.org>
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.
You can find documentation for this module with the perldoc command.
You can also look for information at:
The Minnesota Supercomputing Institute
http://www.msi.umn.edu/ sponsored the development of this software.
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.