1Entry(3)              User Contributed Perl Documentation             Entry(3)
2
3
4

NAME

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

SYNOPSIS

9         use Mozilla::LDAP::Conn;
10         use Mozilla::LDAP::Entry;
11

ABSTRACT

13       The LDAP::Conn object is used to perform LDAP searches, updates, adds
14       and deletes. All such functions works on LDAP::Entry objects only. All
15       modifications and additions you'll do to an LDAP entry, will be done
16       through this object class.
17

DESCRIPTION

19       The LDAP::Entry object class is built on top of the Tie::Hash standard
20       object class. This gives us several powerful features, the main one
21       being to keep track of what is changing in the LDAP entry. This makes
22       it very easy to write LDAP clients that needs to update/modify entries,
23       since you'll just do the changes, and this object class will take care
24       of the rest.
25
26       We define local functions for STORE, FETCH, DELETE, EXISTS, FIRSTKEY
27       and NEXTKEY in this object class, and inherit the rest from the super
28       class. Overloading these specific functions is how we can keep track of
29       what is changing in the entry, which turns out to be very convenient.
30       We can also easily "loop" over the attribute types, ignoring internal
31       data, or deleted attributes.
32
33       Most of the methods here either return the requested LDAP value, or a
34       status code. The status code (either 0 or 1) indicates the failure or
35       success of a certain operation. 0 (False) meaning the operation failed,
36       and a return code of 1 (True) means complete success.
37
38       One thing to remember is that in LDAP, attribute names are case
39       insensitive. All methods in this class are aware of this, and will
40       convert all attribute name arguments to lower case before performing
41       any operations. This does not mean that the values are case
42       insensitive. On the contrary, all values are considered case sensitive
43       by this module, even if the LDAP server itself treats it as a CIS
44       attribute.
45

OBJECT CLASS METHODS

47       The LDAP::Entry class implements many methods you can use to access and
48       modify LDAP entries. It is strongly recommended that you use this API
49       as much as possible, and avoid using the internals of the class
50       directly. Failing to do so may actually break the functionality.
51
52   Creating a new entry
53       To create a completely new entry, use the new method, for instance
54
55           $entry = Mozilla::LDAP::Entry->new()
56           $entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");
57           $entry->{objectclass} = [ "top", "person", "inetOrgPerson" ];
58           $entry->addValue("cn", "Leif Hedstrom");
59           $entry->addValue("sn", "Hedstrom");
60           $entry->addValue("givenName", "Leif");
61           $entry->addValue("mail", "leif@netscape.com);
62
63           $conn->add($entry);
64
65       This is the minimum requirements for an LDAP entry. It must have a DN,
66       and it must have at least one objectclass. As it turns out, by adding
67       the person and inetOrgPerson classes, we also must provide some more
68       attributes, like CN and SN. This is because the object classes have
69       these attributes marked as "required", and we'd get a schema violation
70       without those values.
71
72       In the example above we use both native API methods to add values, and
73       setting an attribute entire value set directly. Note that the value set
74       is a pointer to an array, and not the array itself. In the example
75       above, the object classes are set using an anonymous array, which the
76       API handles properly. It's important to be aware that the attribute
77       value list is indeed a pointer.
78
79       Finally, as you can see there's only only one way to add new LDAP
80       entries, and it's called add(). It normally takes an LDAP::Entry object
81       instance as argument, but it can also be called with a regular hash
82       array if so desired.
83
84   Adding and removing attributes and values
85       This is the main functionality of this module. Use these methods to do
86       any modifications and updates to your LDAP entries.
87
88       addValue     Add a value to an attribute. If the attribute value
89                    already exists, or we couldn't add the value for any other
90                    reason, we'll return FALSE \fIs0(0), otherwise we return
91                    TRUE \fIs0(1). The first two arguments are the attribute
92                    name, and the value to add.
93
94                    The optional third argument is a flag, indicating that we
95                    want to add the attribute without checking for duplicates.
96                    This is useful if you know the values are unique already,
97                    or if you perhaps want to allow duplicates for a
98                    particular attribute. The fourth argument (again optional)
99                    is a flag indicating that we want to perform DN
100                    normalization on the attribute. The final, fifth, optional
101                    argument indicates that the attribute values are case
102                    insensitive (CIS).
103
104                    To add a CN to an existing entry/attribute, do:
105
106                        $entry->addValue("cn", "Leif Hedstrom");
107
108       addDNValue   Just like addValue, except this method assume the value is
109                    a DN attribute, and will enforce DN normalization. For
110                    instance
111
112                       $dn = "uid=Leif, dc=Netscape, dc=COM";
113                       $entry->addDNValue("uniqueMember", $dn);
114
115                    will only add the DN for "uid=leif" if it does not exist
116                    as a DN in the uniqueMember attribute.
117
118       attrModified This is an internal function, that can be used to force
119                    the API to consider an attribute (value) to have been
120                    modified. The only argument is the name of the attribute.
121                    In almost all situation, you never, ever, should call
122                    this. If you do, please contact the developers, and as us
123                    to fix the API. Example
124
125                        $entry->attrModified("cn");
126
127       copy         Copy the value of one attribute to another.  Requires at
128                    least two arguments.  The first argument is the name of
129                    the attribute to copy, and the second argument is the name
130                    of the new attribute to copy to.  The new attribute can
131                    not currently exist in the entry, else the copy will fail.
132                    There is an optional third argument (a boolean flag),
133                    which, when set to 1, will force an override and copy to
134                    the new attribute even if it already exists.  Returns TRUE
135                    if the copy was successful.
136
137                        $entry->copy("cn", "description");
138
139       exists       Return TRUE if the specified attribute is defined in the
140                    LDAP entry. This is useful to know if an entry has a
141                    particular attribute, regardless of the value. For
142                    instance:
143
144                        if ($entry->exists("jpegphoto")) { # do something special }
145
146       getDN        Return the DN for the entry. For instance
147
148                        print "The DN is: ", $entry->getDN(), "\n";
149
150                    Just like setDN, this method also has an optional
151                    argument, which indicates we should normalize the DN
152                    before returning it to the caller.
153
154       getValues    Returns an entire array of values for the attribute
155                    specified.  Note that this returns an array, and not a
156                    pointer to an array.  In a scalar context, this returns
157                    the first value.  This is different - this method used to
158                    always return an array, which meant the array size in a
159                    scalar context.  If you need to get the array size, use
160                    the size method described below.
161
162                        @someArray = $entry->getValues("description");
163                        $scalval = $entry->getValues("cn");
164
165       hasValue     Return TRUE or FALSE if the attribute has the specified
166                    value. A typical usage is to see if an entry is of a
167                    certain object class, e.g.
168
169                        if ($entry->hasValue("objectclass", "person", 1)) { # do something }
170
171                    The (optional) third argument indicates if the string
172                    comparison should be case insensitive or not, and the
173                    (optional) fourth argument indicats wheter we should
174                    normalize the string as if it was a DN. The first two
175                    arguments are the name and value of the attribute,
176                    respectively.
177
178       hasDNValue   Exactly like hasValue, except we assume the attribute
179                    values are DN attributes.
180
181       isAttr       This method can be used to decide if an attribute name
182                    really is a valid LDAP attribute in the current entry. Use
183                    of this method is fairly limited, but could potentially be
184                    useful. Usage is like previous examples, like
185
186                        if ($entry->isAttr("cn")) { # do something }
187
188                    The code section will only be executed if these criterias
189                    are true:
190
191                        1. The name of the attribute is a non-empty string.
192                        2. The name of the attribute does not begin, and end, with an
193                           underscore character (_).
194                        2. The attribute has one or more values in the entry.
195
196       isDeleted    This is almost identical to isModified, except it tests if
197                    an attribute has been deleted. You use it the same way as
198                    above, like
199
200                        if (! $entry->isDeleted("cn")) { # do something }
201
202       isModified   This is a somewhat more useful method, which will return
203                    the internal modification status of a particular
204                    attribute. The argument is the name of the attribute, and
205                    the return value is True or False. If the attribute has
206                    been modified, in any way, we return True (1), otherwise
207                    we return False (0). For example:
208
209                        if ($entry->isModified("cn")) { # do something }
210
211       isEntryModified
212                    This is a wrapper over isModified(), and it will check if
213                    any attribute in the entry object has been modified or
214                    deleted.
215
216       matchValue   This is very similar to hasValue, except it does a regular
217                    expression match instead of a full string match. It takes
218                    the same arguments, including the optional third argument
219                    to specify case insensitive matching. The usage is
220                    identical to the example for hasValue, e.g.
221
222                        if ($entry->matchValue("objectclass", "pers", 1)) { # do something }
223
224       matchDNValue Like matchValue, except the attribute values are
225                    considered being DNs.
226
227       move         Identical to the copy method, except the original
228                    attribute is deleted once the move to the new attribute is
229                    complete.
230
231                        $entry->move("cn", "sn");
232
233       printLDIF    Print the entry in a format called LDIF (LDAP Data
234                    Interchange Format, RFC xxxx). An example of an LDIF entry
235                    is:
236
237                        dn: uid=leif,ou=people,dc=netscape,dc=com
238                        objectclass: top
239                        objectclass: person
240                        objectclass: inetOrgPerson
241                        uid: leif
242                        cn: Leif Hedstrom
243                        mail: leif@netscape.com
244
245                    The above would be the result of
246
247                        $entry->printLDIF();
248
249                    If you need to write to a file, open and then select() it.
250                    For more useful LDIF functionality, check out the
251                    Mozilla::LDAP::LDIF.pm module.
252
253       remove       This will remove the entire attribute, including all it's
254                    values, from the entry. The only argument is the name of
255                    the attribute to remove. Let's say you want to nuke all
256                    mailAlternateAddress values (i.e. the entire attribute
257                    should be removed from the entry):
258
259                        $entry->remove("mailAlternateAddress");
260
261       removeValue  Remove a value from an attribute, if it exists. Of course,
262                    if the attribute has no such value, we won't try to remove
263                    it, and instead return a False (0) status code. The
264                    arguments are the name of the attribute, and the
265                    particular value to remove. Note that values are
266                    considered case sensitive, so make sure you preserve case
267                    properly. An example is:
268
269                        $entry->removeValue("objectclass", "nscpPerson");
270
271       removeDNValue
272                    This is almost identical to removeValue, except it will
273                    normalize the attribute values before trying to remove
274                    them. This is useful if you know that the attribute is a
275                    DN value, but perhaps the values are not cosistent in all
276                    LDAP entries. For example
277
278                       $dn = "uid=Leif, dc=Netscape, dc=COM";
279                       $entry->removeDNValue("owner", $dn);
280
281                    will remove the owner "uid=leif,dc=netscape,dc=com", no
282                    matter how it's capitalized and formatted in the entry.
283
284       setDN        Set the DN to the specified value. Only do this on new
285                    entries, it will not work well if you try to do this on an
286                    existing entry. If you wish to rename an entry, use the
287                    Mozilla::Conn::modifyRDN method instead.  Eventually we'll
288                    provide a complete "rename" method. To set the DN for a
289                    newly created entry, we can do
290
291                        $entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");
292
293                    There is an optional third argument, a boolean flag,
294                    indicating that we should normalize the DN before setting
295                    it. This will assure a consistent format of your DNs.
296
297       setValues    Set the specified attribute to the new value (or values),
298                    overwriting whatever old values it had before. This is a
299                    little dangerous, since you can lose attribute values you
300                    didn't intend to remove. Therefore, it's usually
301                    recommended to use removeValue() and setValues(). If you
302                    know exactly what the new values should be like, you can
303                    use this method like
304
305                        $entry->setValues("cn", "Leif Hedstrom", "The Swede");
306                        $entry->setValues("mail", @mailAddresses);
307
308                    or if it's a single value attribute,
309
310                        $entry->setValues("uidNumber", "12345");
311
312       size         Return the number of values for a particular attribute.
313                    For instance
314
315                        $entry->{cn} = [ "Leif Hedstrom", "The Swede" ];
316                        $numVals = $entry->size("cn");
317
318                    This will set $numVals to two (2). The only argument is
319                    the name of the attribute, and the return value is the
320                    size of the value array.
321
322   Deleting entries
323       To delete an LDAP entry from the LDAP server, you have to use the
324       delete method from the Mozilla::LDAP::Conn module. It will actually
325       delete any entry, if you provide an legitimate DN.
326
327   Renaming entries
328       Again, there's no functionality in this object class to rename the
329       entry (i.e. changing it's DN). For now, there is a way to modify the
330       RDN component of a DN through the Mozilla::LDAP::Conn module, with
331       modifyRDN. Eventually we hope to have a complete rename method, which
332       should be capable of renaming any entry, in any way, including moving
333       it to a different part of the DIT (Directory Information Tree).
334

EXAMPLES

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

INSTALLATION

340       Installing this package is part of the Makefile supplied in the
341       package. See the installation procedures which are part of this
342       package.
343

AVAILABILITY

345       This package can be retrieved from a number of places, including:
346
347           http://www.mozilla.org/directory/
348           Your local CPAN server
349

CREDITS

351       Most of this code was developed by Leif Hedstrom, Netscape
352       Communications Corporation.
353

BUGS

355       None. :)
356

SEE ALSO

358       Mozilla::LDAP::Conn, Mozilla::LDAP::API, and of course Perl.
359
360
361
362perl v5.16.3                      2007-06-14                          Entry(3)
Impressum