plucky (3) Mozilla::LDAP::Entry.3pm.gz

Provided by: libmozilla-ldap-perl_1.5.3-3.1_amd64 bug

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 and deletes. All such functions
       works on LDAP::Entry objects only. All modifications and additions you'll do to an LDAP entry, will be
       done through this object class.

DESCRIPTION

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

       We define local functions for STORE, FETCH, DELETE, EXISTS, FIRSTKEY and NEXTKEY in this object class,
       and inherit the rest from the super class. Overloading these specific functions is how we can keep track
       of what is changing in the entry, which turns out to be very convenient. We can 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 a status code. The status code
       (either 0 or 1) indicates the failure or success 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 case insensitive. All methods in this class
       are aware of this, and will convert all attribute name arguments to lower case before performing any
       operations. This does not mean that the values are case insensitive. On the 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 and modify LDAP entries. It is
       strongly recommended that you use this API as much as possible, and avoid using the internals of the
       class directly. 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", "leif@netscape.com);

           $conn->add($entry);

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

       In the example above we use both native API methods to add values, and setting an attribute entire value
       set directly. Note that the value set is a pointer to an array, and not the array itself. In the example
       above, the object classes are set using an anonymous array, which the API handles properly. It's
       important to be aware that the attribute value list is indeed 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 as argument, but it can also be called with a regular hash
       array if so desired.

   Adding and removing attributes and values
       This is the main functionality of this module. Use these methods to do any modifications and updates to
       your LDAP entries.

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

                    The optional third argument is a flag, indicating that we want to add the attribute without
                    checking for duplicates. This is useful if you know the values are unique already, or if you
                    perhaps want to allow duplicates for a particular attribute. The fourth argument (again
                    optional) is a flag indicating that we want to perform DN normalization on the attribute.
                    The final, fifth, optional argument indicates that the attribute values are case 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 DN attribute, 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 the uniqueMember
                    attribute.

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

                        $entry->attrModified("cn");

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

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

       exists       Return TRUE if the specified attribute is defined in the LDAP entry. This is useful to know
                    if an entry has a particular attribute, regardless of the 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, which indicates we should
                    normalize the DN before returning it to the caller.

       getValues    Returns an entire array of values for the attribute specified.  Note that this returns an
                    array, and not a pointer to an array.  In a scalar context, this returns the first value.
                    This is different - this method used to always return an array, which meant the array size
                    in a scalar context.  If you need to get the array size, use the size method described
                    below.

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

       hasValue     Return TRUE or FALSE if the attribute has the specified value. A typical usage 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 be case insensitive
                    or not, and the (optional) fourth argument indicats whether we should normalize the string
                    as if it was a DN. The first two arguments are the name and value of the attribute,
                    respectively.

       hasDNValue   Exactly like hasValue, except we assume the attribute values are DN attributes.

       isAttr       This method can be used to decide if an attribute name really is a valid LDAP 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 attribute has 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 internal modification status of
                    a particular attribute. The argument is the name of the attribute, and the return value is
                    True or False. If the attribute has been 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 attribute in the entry object
                    has been modified or deleted.

       matchValue   This is very similar to hasValue, except it does a regular expression match instead of a
                    full string match. It takes the same arguments, including the optional third argument to
                    specify case insensitive matching. 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 is deleted once the move to the
                    new attribute is complete.

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

       printLDIF    Print the entry in a format called LDIF (LDAP Data Interchange Format, 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: leif@netscape.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 the Mozilla::LDAP::LDIF.pm module.

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

                        $entry->remove("mailAlternateAddress");

       removeValue  Remove a value from an attribute, if it exists. Of course, if the attribute has no such
                    value, we won't try to remove it, and instead return a False (0) status code. The arguments
                    are the name of the attribute, and the particular value to remove. Note that values are
                    considered case sensitive, 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 the attribute values
                    before trying to remove them. This is useful if you know that the attribute is a DN value,
                    but perhaps the values are not cosistent in 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's capitalized and
                    formatted in the entry.

       setDN        Set the DN to the specified value. Only do this on new entries, it will not work well if you
                    try to do this on an existing entry. If you wish to rename an entry, use the
                    Mozilla::Conn::modifyRDN method instead.  Eventually we'll provide a complete "rename"
                    method. To set the DN for a newly 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 we should normalize the
                    DN before setting it. This will assure a consistent format of your DNs.

       setValues    Set the specified attribute to the new value (or values), overwriting whatever old values it
                    had before. This is a little dangerous, since you can lose attribute values you didn't
                    intend to remove. Therefore, it's usually recommended to use removeValue() and setValues().
                    If you know exactly 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 the attribute, 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 the delete method from the
       Mozilla::LDAP::Conn module. It will actually delete 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 RDN component of a DN through the Mozilla::LDAP::Conn module, with
       modifyRDN. Eventually we hope to have a complete rename method, which should be capable of renaming any
       entry, in any way, including moving 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 are adding more examples every day
       (almost).

INSTALLATION

       Installing this package is part of the Makefile supplied in the package. 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 Communications Corporation.

BUGS

       None. :)

SEE ALSO

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