MAN page from Fedora 7 perl-Mozilla-LDAP-1.5.2-1.fc7.x86_64.rpm

Entry

Section: User Contributed Perl Documentation (3)
Updated: 2007-06-14
Index 

NAME

  Mozilla::LDAP::Entry.pm - Object class to hold one LDAP entry.

 

SYNOPSIS

  use Mozilla::LDAP::Conn;  use Mozilla::LDAP::Entry;

 

ABSTRACT

The LDAP::Conn object is used to perform LDAP searches, updates, adds anddeletes. All such functions works on LDAP::Entry objects only. Allmodifications and additions you'll do to an LDAP entry, will be donethrough this object class. 

DESCRIPTION

The LDAP::Entry object class is built on top of the Tie::Hash standardobject class. This gives us several powerful features, the main one beingto keep track of what is changing in the LDAP entry. This makes it veryeasy to write LDAP clients that needs to update/modify entries, sinceyou'll just do the changes, and this object class will take care of therest.

We define local functions for STORE, FETCH, DELETE, EXISTS, FIRSTKEY andNEXTKEY in this object class, and inherit the rest from the superclass. Overloading these specific functions is how we can keep track ofwhat is changing in the entry, which turns out to be very convenient. Wecan also easily ``loop'' over the attribute types, ignoring internal data,or deleted attributes.

Most of the methods here either return the requested LDAP value, or astatus code. The status code (either 0 or 1) indicates the failure orsuccess of a certain operation. 0 (False) meaning the operation failed,and a return code of 1 (True) means complete success.

One thing to remember is that in LDAP, attribute names are caseinsensitive. All methods in this class are aware of this, and will convertall attribute name arguments to lower case before performing anyoperations. This does not mean that the values are case insensitive. Onthe contrary, all values are considered case sensitive by this module,even if the LDAP server itself treats it as a CIS attribute. 

OBJECT CLASS METHODS

The LDAP::Entry class implements many methods you can use to access andmodify LDAP entries. It is strongly recommended that you use this API asmuch as possible, and avoid using the internals of the classdirectly. Failing to do so may actually break the functionality. 

Creating a new entry

To create a completely new entry, use the new method, for instance

    $entry = Mozilla::LDAP::Entry->new()    $entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");    $entry->{objectclass} = [ "top", "person", "inetOrgPerson" ];    $entry->addValue("cn", "Leif Hedstrom");    $entry->addValue("sn", "Hedstrom");    $entry->addValue("givenName", "Leif");    $entry->addValue("mail", "leifAATTnetscape.com);

    $conn->add($entry);

This is the minimum requirements for an LDAP entry. It must have a DN, andit must have at least one objectclass. As it turns out, by adding theperson and inetOrgPerson classes, we also must provide some moreattributes, like CN and SN. This is because the object classes havethese attributes marked as ``required'', and we'd get a schema violationwithout those values.

In the example above we use both native API methods to add values, andsetting an attribute entire value set directly. Note that the value set isa pointer to an array, and not the array itself. In the example above, theobject classes are set using an anonymous array, which the API handlesproperly. It's important to be aware that the attribute value list isindeed a pointer.

Finally, as you can see there's only only one way to add new LDAP entries,and it's called add(). It normally takes an LDAP::Entry object instance asargument, but it can also be called with a regular hash array if sodesired. 

Adding and removing attributes and values

This is the main functionality of this module. Use these methods to do anymodifications and updates to your LDAP entries.

addValue

Add a value to an attribute. If the attribute value already exists, or wecouldn't add the value for any other reason, we'll return FALSE (0),otherwise we return TRUE (1). The first two arguments are the attributename, and the value to add.

The optional third argument is a flag, indicating that we want to add theattribute without checking for duplicates. This is useful if you know thevalues are unique already, or if you perhaps want to allow duplicates fora particular attribute. The fourth argument (again optional) is a flagindicating that we want to perform DN normalization on the attribute. Thefinal, fifth, optional argument indicates that the attribute values arecase insensitive (CIS).

To add a CN to an existing entry/attribute, do:

    $entry->addValue("cn", "Leif Hedstrom");

addDNValue

Just like addValue, except this method assume the value is a DNattribute, and will enforce DN normalization. For instance

   $dn = "uid=Leif, dc=Netscape, dc=COM";   $entry->addDNValue("uniqueMember", $dn);

will only add the DN for ``uid=leif'' if it does not exist as a DN in theuniqueMember attribute.

attrModified

This is an internal function, that can be used to force the API toconsider an attribute (value) to have been modified. The only argument isthe name of the attribute. In almost all situation, you never, ever,should call this. If you do, please contact the developers, and as us tofix the API. Example

    $entry->attrModified("cn");

copy

Copy the value of one attribute to another. Requires at least twoarguments. The first argument is the name of the attribute to copy, andthe second argument is the name of the new attribute to copy to. The newattribute can not currently exist in the entry, else the copy will fail.There is an optional third argument (a boolean flag), which, when set to1, will force anoverride and copy to the new attribute even if it already exists. Returns TRUE if the copywas successful.

    $entry->copy("cn", "description");

exists

Return TRUE if the specified attribute is defined in the LDAP entry. Thisis useful to know if an entry has a particular attribute, regardless ofthe value. For instance:

    if ($entry->exists("jpegphoto")) { # do something special }

getDN

Return the DN for the entry. For instance

    print "The DN is: ", $entry->getDN(), "\n";

Just like setDN, this method also has an optional argument, whichindicates we should normalize the DN before returning it to the caller.

getValues

Returns an entire array of values for the attribute specified. Note thatthis returns an array, and not a pointer to an array. In a scalarcontext, this returns the first value. This is different - this methodused to always return an array, which meant the array size in a scalarcontext. If you need to get the array size, use the size methoddescribed below.

    @someArray = $entry->getValues("description");    $scalval = $entry->getValues("cn");

hasValue

Return TRUE or FALSE if the attribute has the specified value. A typicalusage is to see if an entry is of a certain object class, e.g.

    if ($entry->hasValue("objectclass", "person", 1)) { # do something }

The (optional) third argument indicates if the string comparison should becase insensitive or not, and the (optional) fourth argument indicatswheter we should normalize the string as if it was a DN. The first twoarguments are the name and value of the attribute, respectively.

hasDNValue

Exactly like hasValue, except we assume the attribute values are DNattributes.

isAttr

This method can be used to decide if an attribute name really is a validLDAP attribute in the current entry. Use of this method is fairly limited,but could potentially be useful. Usage is like previous examples, like

    if ($entry->isAttr("cn")) { # do something }

The code section will only be executed if these criterias are true:

    1. The name of the attribute is a non-empty string.    2. The name of the attribute does not begin, and end, with an       underscore character (_).    2. The attribute has one or more values in the entry.

isDeleted

This is almost identical to isModified, except it tests if an attributehas been deleted. You use it the same way as above, like

    if (! $entry->isDeleted("cn")) { # do something }

isModified

This is a somewhat more useful method, which will return the internalmodification status of a particular attribute. The argument is the name ofthe attribute, and the return value is True or False. If the attribute hasbeen modified, in any way, we return True (1), otherwise we return False(0). For example:

    if ($entry->isModified("cn")) { # do something }

isEntryModified

This is a wrapper over isModified(), and it will check if any attributein the entry object has been modified or deleted.

matchValue

This is very similar to hasValue, except it does a regular expressionmatch instead of a full string match. It takes the same arguments,including the optional third argument to specify case insensitivematching. The usage is identical to the example for hasValue, e.g.

    if ($entry->matchValue("objectclass", "pers", 1)) { # do something }

matchDNValue

Like matchValue, except the attribute values are considered being DNs.

move

Identical to the copy method, except the original attribute isdeleted once the move to the new attribute is complete.

    $entry->move("cn", "sn");

printLDIF

Print the entry in a format called LDIF (LDAP Data InterchangeFormat, RFC xxxx). An example of an LDIF entry is:

    dn: uid=leif,ou=people,dc=netscape,dc=com    objectclass: top    objectclass: person    objectclass: inetOrgPerson    uid: leif    cn: Leif Hedstrom    mail: leifAATTnetscape.com

The above would be the result of

    $entry->printLDIF();

If you need to write to a file, open and then select() it.For more useful LDIF functionality, check out theMozilla::LDAP::LDIF.pm module.

remove

This will remove the entire attribute, including all it's values, from theentry. The only argument is the name of the attribute to remove. Let's sayyou want to nuke all mailAlternateAddress values (i.e. the entireattribute should be removed from the entry):

    $entry->remove("mailAlternateAddress");

removeValue

Remove a value from an attribute, if it exists. Of course, if theattribute has no such value, we won't try to remove it, and instead returna False (0) status code. The arguments are the name of the attribute, andthe particular value to remove. Note that values are considered casesensitive, so make sure you preserve case properly. An example is:

    $entry->removeValue("objectclass", "nscpPerson");

removeDNValue

This is almost identical to removeValue, except it will normalize theattribute values before trying to remove them. This is useful if you knowthat the attribute is a DN value, but perhaps the values are not cosistentin all LDAP entries. For example

   $dn = "uid=Leif, dc=Netscape, dc=COM";   $entry->removeDNValue("owner", $dn);

will remove the owner ``uid=leif,dc=netscape,dc=com'', no matter how it'scapitalized and formatted in the entry.

setDN

Set the DN to the specified value. Only do this on new entries, it willnot work well if you try to do this on an existing entry. If you wish torename an entry, use the Mozilla::Conn::modifyRDN method instead.Eventually we'll provide a complete ``rename'' method. To set the DN for anewly created entry, we can do

    $entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");

There is an optional third argument, a boolean flag, indicating that weshould normalize the DN before setting it. This will assure a consistentformat of your DNs.

setValues

Set the specified attribute to the new value (or values), overwritingwhatever old values it had before. This is a little dangerous, since youcan lose attribute values you didn't intend to remove. Therefore, it'susually recommended to use removeValue() and setValues(). If you knowexactly what the new values should be like, you can use this method like

    $entry->setValues("cn", "Leif Hedstrom", "The Swede");    $entry->setValues("mail", @mailAddresses);

or if it's a single value attribute,

    $entry->setValues("uidNumber", "12345");

size

Return the number of values for a particular attribute. For instance

    $entry->{cn} = [ "Leif Hedstrom", "The Swede" ];    $numVals = $entry->size("cn");

This will set $numVals to two (2). The only argument is the name of theattribute, and the return value is the size of the value array.

 

Deleting entries

To delete an LDAP entry from the LDAP server, you have to use thedelete method from the Mozilla::LDAP::Conn module. It will actuallydelete any entry, if you provide an legitimate DN. 

Renaming entries

Again, there's no functionality in this object class to rename the entry(i.e. changing it's DN). For now, there is a way to modify the RDNcomponent of a DN through the Mozilla::LDAP::Conn module, withmodifyRDN. Eventually we hope to have a complete rename method,which should be capable of renaming any entry, in any way, includingmoving it to a different part of the DIT (Directory Information Tree). 

EXAMPLES

There are plenty of examples to look at, in the examples directory. We areadding more examples every day (almost). 

INSTALLATION

Installing this package is part of the Makefile supplied in thepackage. See the installation procedures which are part of this package. 

AVAILABILITY

This package can be retrieved from a number of places, including:

    http://www.mozilla.org/directory/    Your local CPAN server

 

CREDITS

Most of this code was developed by Leif Hedstrom, Netscape CommunicationsCorporation.  

BUGS

None. :) 

SEE ALSO

Mozilla::LDAP::Conn, Mozilla::LDAP::API, and of course Perl.

---

 

Index

NAME

SYNOPSIS

ABSTRACT

DESCRIPTION

OBJECT CLASS METHODS

Creating a new entry

Adding and removing attributes and values

Deleting entries

Renaming entries

EXAMPLES

INSTALLATION

AVAILABILITY

CREDITS

BUGS

SEE ALSO

---

This document was created byman2html,using the manual pages.