org.dlese.dpc.ldap

Class LdapClient

java.lang.Object

org.dlese.dpc.ldap.LdapClient

Direct Known Subclasses:

NSDLLdapClient

public class LdapClient
extends java.lang.Object

Handles all LDAP communications for DLESE applications.

General

For info on the properties file, see the LdapClient constructor.
For info on required and optional attributes, see addUserEntry.
For info on search filter syntax and semantics, see searchDn.

Caution: The properties file contains an unencrypted administrator password. The file must not be readable by outsiders!

Lists

To make list names more practical and intuitive, there is a hierarchical system of list names layered over LDAP's messy syntax. So, for example, the list name
lists/open/hydrology
is translated by this LDAP interface to the LDAP dn (distinguished name):
DLESElistName=hydrology,DLESEsetName=open,DLESEou=lists,dc=dlese,dc=org

All list names must start with either "lists/" or "groups/". They may have as many levels as desired. Contrary to standard LDAP, this interface constructs intermediate levels for list entrys as needed. So if you create a list
/lists/committees/steering/voting
the intermediate LDAP entries are created if needed:
/lists
/lists/committees
/lists/committees/steering

Currently this interface does not remove unused intermediate entries. So, for example, if you remove the list
/lists/committees/steering/voting
the intermediate LDAP entries are not removed:
/lists
/lists/committees
/lists/committees/steering
If need be, they may be removed using the ldapmodify shell command, which is part of standard OpenLDAP.

All lists starting with "lists/open/" have open enrollment, meaning users can self-register and self-remove. All other lists can be changed only by the list owner or an admin.

Example: lists/open/hydrology
Corresponding LDAP dn: DLESElistName=hydrology,DLESEsetName=open,DLESEou=lists,dc=dlese,dc=org
Meaning: Hydrology interest group; open enrollment

Example: lists/committees/steering/voting
Corresponding Ldap dn: DLESElistName=voting,DLESEsetName=steering,DLESEsetName=committees,DLESEou=lists,dc=dlese,dc=org
Meaning: Voting members of the steering committee; controlled enrollment

Example: groups/dpc/cataloguers/experienced
Corresponding Ldap dn: DLESElistName=experienced,DLESEsetName=cataloguers,DLESEsetName=dpc,DLESEou=groups,dc=dlese,dc=org
Meaning: Experienced DPC cataloguers; controlled enrollment

Summary of Primary API Methods

Many methods come in two flavors. One flavor is called with a UID and password, which are used for authentication. The other flavor is called without UID and password, and uses the admin UID: it should always authenticate successfully.

Flavors	Method	Desc
People entries:
admin	userAuthenticates: Test: does a user authenticate
admin	addUserEntry: Creates a new user entry
admin	removeUserEntry: Removes a user entry
admin	userExists: Tests if a user entry exists
user, admin	getUserAttributes: Gets attributes for 1 user entry
user, admin	getSingleAttribute: Gets 1 attribute for 1 user entry
user, admin	setUserAttribute: Sets/replaces 1 attribute and all it's values
user, admin	addUserAttributeValue: Adds a new value for an attribute
user, admin	removeUserAttributeValue: Removes a value for an attribute
Object entries:
user	getUserObject: Retrieves a java object
user	storeUserObject: Stores a java object associated with a user
user	removeUserObject: Removes a java object associated with a user
Lists:
admin	createList: Creates a new list
admin	removeEntireList: Removes an entire list
user	addListName: Adds a name to a list
user	removeListName: Removes a name from a list
user, admin	getListAttributes: Gets attributes of all members of a list
user, admin	getListMembers: Gets dns of all members of a list
user, admin	getListNames: Gets UIDs of all members of a list
All entries:
user, admin	search: Searches all entries using the specified filter

Groups of methods

The methods are divided into four groups:

• Public API methods that use a specified UID and password for authorization. These methods, like getUserAttributes( String authName, String password, String subjectName, String[] attrNames) , take the uid and password as the first two parameters.
• Public API methods that use the internal administrator's dn (distinguished name) and password from the properties file for authorization. For example: getUserAttributes( String subjectName, String[] attrNames) .
• Public API methods that take full dns (distinguished names) for parameters instead of UIDs. These are noted as "Low level" in the doc, but can be used publicly.
• Private internal methods.

Typical usage

Typical usage is shown below. For a more complete example, see LdapDemo.

 void testDemoClient(
     String propsFile)       // Name of properties file
 throws LdapException
 {
     LdapClient democlient = new LdapClient( propsFile);
     try { democlient.isAlive(); }
     catch( LdapException lex) {
         System.out.println(
            "\nDemoClient: isAlive says there's trouble: " + lex);
         throw lex;
     }
     LdapEntry[] entries = democlient.search(
         null,               // base = null: start at top of DB tree
         "objectclass=*",    // filter: find all entries
         null,               // attrNames = null: return all attributes
         0);                 // maxres = 0 implies return all results
     if (entries == null) System.out.println("\nDemoClient: No entries found");
     else {
         System.out.println("\nDemoClient: num entries found: "
             + entries.length);
 
         // For each returned entry:
         for (int ii = 0; ii < entries.length; ii++) {
             System.out.println("\nEntry " + ii + " dn: "
                 + entries[ii].getDn());
 
             // For each attribute of the entry:
             for (int jj = 0; jj < entries[ii].getAttrsRows(); jj++) {
                 System.out.print("  Attribute: "
                     + entries[ii].getAttrName( jj) + "  Values:");
                 String[] valueStrings = entries[ii].getAttrStrings(jj);
 
                 // For each value of the attribute:
                 for (int kk = 0; kk < valueStrings.length; kk++) {
                     System.out.print("  \""
                         + valueStrings[kk] + "\"");
                 } // end for kk
                 System.out.println();
             } // end for jj
         } // end for ii
         System.out.println();
     } // if entries != null
 } // end testDemoClient

 

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Properties	props

Constructor Summary

Constructors

Constructor and Description
LdapClient(java.lang.String pfile) Creates a client using the info in the specified properties file.

Method Summary

Modifier and Type	Method and Description
void	addAttributeValueDn(java.lang.String authDn, java.lang.String password, java.lang.String subjectDn, java.lang.String attrName, java.lang.String value) Low level method: adds a single value to a single attribute, using the specified dn/pswd for authorization.
void	addEntryDn(java.lang.String authDn, java.lang.String password, java.lang.String newDn, java.lang.String[][] attrStgs) Low level method: adds a new LDAP entry, using the specified dn/pswd for authorization.
void	addListName(java.lang.String authName, java.lang.String password, java.lang.String listName, java.lang.String userName) Adds a single "DLESElistMember" name to the specified list.
void	addUserAttributeValue(java.lang.String subjectName, java.lang.String attrName, java.lang.String value) Adds a single value to a single attribute, using the admin dn/pswd for authorization.
void	addUserAttributeValue(java.lang.String authName, java.lang.String password, java.lang.String subjectName, java.lang.String attrName, java.lang.String value) Adds a single value to a single attribute, using the specified uid/pswd for authorization.
void	addUserEntry(java.lang.String newName, java.lang.String[][] attrStgs) Adds a new LDAP entry for a user, using a the admin dn/pswd for authorization.
void	createList(java.lang.String listName, java.lang.String ownerName) Creates an empty list of names, using a the admin dn/pswd for authorization, and adds the owner as a DLESElistMember of the list.
LdapEntry	getAttributesDn(java.lang.String authDn, java.lang.String password, java.lang.String subjectDn, java.lang.String[] attrNames) Low level method: Retrieves attributes of a single entry, using the specified dn/pswd for authorization.
LdapEntry[]	getListAttributes(java.lang.String listName, java.lang.String[] attrNames) Returns the desired attributes for each "DLESElistMember" attribute value from a list, using a the admin dn/pswd for authorization.
LdapEntry[]	getListAttributes(java.lang.String authName, java.lang.String password, java.lang.String listName, java.lang.String[] attrNames) Returns the desired attributes for each "DLESElistMember" attribute value from a list, using the specified dn/pswd for authorization.
java.lang.String[]	getListMembers(java.lang.String listName) Returns all the "DLESElistMember" attribute values from a list, as full dn's (distinguished names), using a the admin dn/pswd for authorization.
java.lang.String[]	getListMembers(java.lang.String authName, java.lang.String password, java.lang.String listName) Returns all the "DLESElistMember" attribute values from a list, as full dn's (distinguished names), using a the specified dn/pswd for authorization.
java.lang.String[]	getListMembersDn(java.lang.String authDn, java.lang.String password, java.lang.String listDn) Low level: Returns all the "DLESElistMember" attribute values from a list, as full dn's (distinguished names); returns null if no DLESElistMembers in the list.
java.lang.String[]	getListNames(java.lang.String listName) Returns all the "DLESElistMember" attribute values from a list, as uids (not full dn's); returns null if no DLESElistMembers in the list.
java.lang.String[]	getListNames(java.lang.String authName, java.lang.String password, java.lang.String listName) Returns all the "DLESElistMember" attribute values from a list, as uids (not full dn's); returns null if no DLESElistMembers in the list.
java.lang.Object	getObjectDn(java.lang.String authDn, java.lang.String password, java.lang.String objectDn) Low level method: Retrieves a serialized Java Object, using the specified dn/pswd for authorization.
protected java.lang.String	getProperty(java.lang.String propName, java.util.Properties props, java.lang.String pfile) Returns the desired property value; throws an LdapException if not found.
java.lang.String[]	getSingleAttribute(java.lang.String subjectName, java.lang.String attrName) Retrieves values for a single attribute of a single entry, using the admin dn/pswd for authorization.
java.lang.String[]	getSingleAttribute(java.lang.String authName, java.lang.String password, java.lang.String subjectName, java.lang.String attrName) Retrieves values for a single attribute of a single entry, using the specified uid/pswd for authorization.
java.lang.String[]	getSingleAttributeDn(java.lang.String authDn, java.lang.String password, java.lang.String subjectDn, java.lang.String attrName) Low level method: Returns the values associated with a single attribute of a single entry, or null if no values exist.
LdapEntry	getUserAttributes(java.lang.String subjectName, java.lang.String[] attrNames) Retrieves attributes of a single entry, using the admin dn/pswd for authorization.
LdapEntry	getUserAttributes(java.lang.String authName, java.lang.String password, java.lang.String subjectName, java.lang.String[] attrNames) Retrieves attributes of a single entry, using the specified uid/pswd for authorization.
java.lang.Object	getUserObject(java.lang.String authName, java.lang.String password, java.lang.String userName, java.lang.String objectName) Retrieves a serialized Java Object, using the specified uid/pswd for authorization.
LdapEntry	getUserObjectAttributes(java.lang.String authName, java.lang.String password, java.lang.String userName, java.lang.String objectName, java.lang.String[] attrNames) Deprecated: Retrieves the attributes associated with a serialized Java Object, using the specified uid/pswd for authorization.
java.util.Date	getUtcCreateTimestamp(java.lang.String subjectName) Returns the UTC (GMT) time of creation for a given entry.
java.util.Date	getUtcModifyTimestamp(java.lang.String subjectName) Returns the UTC (GMT) time of last modification for a given entry.
void	isAlive() Tests to see if the server, adminDn, and adminPswd specified in the properties file are actually working.
protected java.lang.String	mkUserDn(java.lang.String userName) Given a UID, returns the corresponding full dn (distinguished name).
void	removeAttributeValueDn(java.lang.String authDn, java.lang.String password, java.lang.String subjectDn, java.lang.String attrName, java.lang.String value) Low level method: removes a single value from a single attribute, or removes the entire attribute and all values, using the specified dn/pswd for authorization.
void	removeEntireList(java.lang.String listName) Removes a list of names, using a the admin dn/pswd for authorization.
void	removeEntryDn(java.lang.String authDn, java.lang.String password, java.lang.String subjectDn) Low level method: removes an entry from the LDAP database, using the specified dn/pswd for authorization.
void	removeListName(java.lang.String authName, java.lang.String password, java.lang.String listName, java.lang.String userName) Removes a single "DLESElistMember" name from the specified list.
void	removeUserAttributeValue(java.lang.String subjectName, java.lang.String attrName, java.lang.String value) Removes a single value from a single attribute, or removes the entire attribute and all values, using a the admin dn/pswd for authorization.
void	removeUserAttributeValue(java.lang.String authName, java.lang.String password, java.lang.String subjectName, java.lang.String attrName, java.lang.String value) Removes a single value from a single attribute, or removes the entire attribute and all values, using the specified uid/pswd for authorization.
void	removeUserEntry(java.lang.String subjectName) Removes an entry from the LDAP database, using a the admin dn/pswd for authorization.
void	removeUserObject(java.lang.String authName, java.lang.String password, java.lang.String userName, java.lang.String objectName) Removes a serialized Java Object, and associated attributes, using the specified uid/pswd for authorization.
void	renameEntryDn(java.lang.String authDn, java.lang.String password, java.lang.String oldDn, java.lang.String newDn) Deprecated: Low level method: renames an entry in the LDAP database, using the specified dn/pswd for authorization.
void	renameUserEntry(java.lang.String oldName, java.lang.String newName) Deprecated: Renames an user entry in the LDAP database, using a the admin dn/pswd for authorization.
LdapEntry[]	search(java.lang.String base, java.lang.String filter, java.lang.String[] attrNames, int maxres) Searches and retrieves attributes for 0 or more entries, using the admin dn/pswd for authorization.
LdapEntry[]	search(java.lang.String authName, java.lang.String password, java.lang.String base, java.lang.String filter, java.lang.String[] attrNames, int maxres) Searches and retrieves attributes for 0 or more entries, using the specified uid/pswd for authorization.
LdapEntry[]	searchDn(java.lang.String authDn, java.lang.String password, java.lang.String specBase, java.lang.String filter, java.lang.String[] attrNames, int maxres) Low level method: searches and retrieves attributes for 0 or more entries, using the specified dn/pswd for authorization.
void	setAttributeDn(java.lang.String authDn, java.lang.String password, java.lang.String subjectDn, java.lang.String attrName, java.lang.String[] values) Low level method: sets the value of a single attribute, using the specified dn/pswd for authorization.
void	setUserAttribute(java.lang.String subjectName, java.lang.String attrName, java.lang.String[] values) Sets the value of a single attribute, using the admin dn/pswd for authorization.
void	setUserAttribute(java.lang.String authName, java.lang.String password, java.lang.String subjectName, java.lang.String attrName, java.lang.String[] values) Sets the value of a single attribute, using the specified uid/pswd for authorization.
void	storeObjectDn(java.lang.String authDn, java.lang.String password, java.lang.String curDn, java.lang.String[][] attrStgs, java.lang.Object obj) Low level method: stores a serialized Java Object, and associated attributes, using the specified dn/pswd for authorization.
void	storeUserObject(java.lang.String authName, java.lang.String password, java.lang.String userName, java.lang.String objectName, java.lang.Object obj) Stores a serialized Java Object, and associated attributes, using the specified uid/pswd for authorization.
boolean	userAuthenticates(java.lang.String subjectName, java.lang.String password) Returns true if the subjectName/password pair authenticates successfully; false otherwise.
boolean	userExists(java.lang.String subjectName) Tests to see if a user entry exists in the LDAP database, using a the admin dn/pswd for authorization.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

props

protected java.util.Properties props

Constructor Detail

LdapClient

public LdapClient(java.lang.String pfile)
           throws LdapException

Creates a client using the info in the specified properties file.

Caution: The properties file contains an unencrypted administrator password. The file must not be readable by outsiders!

Properties file fields:

Field	Meaning
hostUrl	URL of the LDAP server
dnbase	The suffix of the dn (distinguished names) for all entries in the LDAP database
adminDn	The full dn (distinguished name) of the administrator for this DLESE subgroup
adminPswd	The unencrypted password for the adminDn

Sample properties file:

       hostUrl    ldap://localhost:3890
       dnbase     dc=dlese,dc=org
       adminDn    DLESEloginName=jsmith,DLESEou=people,dc=dlese,dc=org
       adminPswd  someSecret
 

Throws:

LdapException

Method Detail

isAlive

public void isAlive()
             throws LdapException

Tests to see if the server, adminDn, and adminPswd specified in the properties file are actually working.

Throws:

LdapException

getUtcCreateTimestamp

public java.util.Date getUtcCreateTimestamp(java.lang.String subjectName)
                                     throws LdapException

Returns the UTC (GMT) time of creation for a given entry.

Parameters:

subjectName - the uid about which info is requested

Throws:

LdapException

getUtcModifyTimestamp

public java.util.Date getUtcModifyTimestamp(java.lang.String subjectName)
                                     throws LdapException

Returns the UTC (GMT) time of last modification for a given entry.

Parameters:

subjectName - the uid about which info is requested

Throws:

LdapException

userAuthenticates

public boolean userAuthenticates(java.lang.String subjectName,
                                 java.lang.String password)
                          throws LdapException

Returns true if the subjectName/password pair authenticates successfully; false otherwise.

Parameters:

subjectName - the uid about which info is requested

password - the password associated with subjectName

Throws:

LdapException

getSingleAttribute

public java.lang.String[] getSingleAttribute(java.lang.String authName,
                                             java.lang.String password,
                                             java.lang.String subjectName,
                                             java.lang.String attrName)
                                      throws LdapException

Retrieves values for a single attribute of a single entry, using the specified uid/pswd for authorization. See getSingleAttributeDn. See addUserEntry for doc on the attribute names.

Parameters:

authName - the uid of the caller

password - the password associated with authName

subjectName - the uid about which info is requested

attrName - is the name of the desired attribute.

Returns:

An array of the attribute values, or null if the attribute is not found. The returned values may be in any order.

Throws:

LdapException

getSingleAttribute

public java.lang.String[] getSingleAttribute(java.lang.String subjectName,
                                             java.lang.String attrName)
                                      throws LdapException

Retrieves values for a single attribute of a single entry, using the admin dn/pswd for authorization. See getSingleAttributeDn. See addUserEntry for doc on the attribute names.

Parameters:

subjectName - the uid about which info is requested

attrName - is the name of the desired attribute.

Returns:

An array of the attribute values, or null if the attribute is not found. The returned values may be in any order.

Throws:

LdapException

getSingleAttributeDn

public java.lang.String[] getSingleAttributeDn(java.lang.String authDn,
                                               java.lang.String password,
                                               java.lang.String subjectDn,
                                               java.lang.String attrName)
                                        throws LdapException

Low level method: Returns the values associated with a single attribute of a single entry, or null if no values exist.

Parameters:

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

subjectDn - the dn about which info is requested

attrName - is the name of the desired attribute.

Returns:

An array of the attribute values, or null if the attribute is not found. The returned values may be in any order.

Throws:

LdapException

getUserAttributes

public LdapEntry getUserAttributes(java.lang.String authName,
                                   java.lang.String password,
                                   java.lang.String subjectName,
                                   java.lang.String[] attrNames)
                            throws LdapException

Retrieves attributes of a single entry, using the specified uid/pswd for authorization. See getAttributesDn. See addUserEntry for doc on the attribute names.

Parameters:

authName - the uid of the caller

password - the password associated with authName

subjectName - the uid about which info is requested

attrNames - an array of attribute names to be returned. If null, all available attributes are returned.

Returns:

An LdapEntry representing one returned entry. Throws LdapNotFoundException if entry not found. If attrNames was specified, the LdapEntry has the same attributes in the specified order.

If attrNames is null, the LdapEntry contains all available attributes for the entry, sorted by attribute name.

Throws:

LdapException

getUserAttributes

public LdapEntry getUserAttributes(java.lang.String subjectName,
                                   java.lang.String[] attrNames)
                            throws LdapException

Retrieves attributes of a single entry, using the admin dn/pswd for authorization. See getAttributesDn.

Parameters:

subjectName - the uid about which info is requested

attrNames - an array of attribute names to be returned. If null, all available attributes are returned.

Returns:

An LdapEntry representing one returned entry. Throws LdapNotFoundException if entry not found. If attrNames was specified, the LdapEntry has the same attributes in the specified order.

If attrNames is null, the LdapEntry contains all available attributes for the entry, sorted by attribute name.

Throws:

LdapException

getAttributesDn

public LdapEntry getAttributesDn(java.lang.String authDn,
                                 java.lang.String password,
                                 java.lang.String subjectDn,
                                 java.lang.String[] attrNames)
                          throws LdapException

Low level method: Retrieves attributes of a single entry, using the specified dn/pswd for authorization.

Parameters:

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

subjectDn - the dn about which info is requested

attrNames - an array of attribute names to be returned. If null, all available attributes are returned.

Returns:

An LdapEntry representing one returned entry. Throws LdapNotFoundException if entry not found. If attrNames was specified, the LdapEntry has the same attributes in the specified order.

If attrNames is null, the LdapEntry contains all available attributes for the entry, sorted by attribute name.

Throws:

LdapException

search

public LdapEntry[] search(java.lang.String authName,
                          java.lang.String password,
                          java.lang.String base,
                          java.lang.String filter,
                          java.lang.String[] attrNames,
                          int maxres)
                   throws LdapException

Searches and retrieves attributes for 0 or more entries, using the specified uid/pswd for authorization. See searchDn for details. See addUserEntry for doc on the attribute names.

Parameters:

authName - the uid of the caller

password - the password associated with authName

base - The starting dn of the search. If null or "", start at top.

filter - The search phrase. See associated notes on filter syntax.

attrNames - an array of attribute names to be returned. If attrNames is non-null, each LdapEntry has the same attributes in the specified order. If attrNames == null, all available attributes are returned for each entry, sorted by attribute name.

maxres - the maximum number of LDAP entries to return. If maxres <= 0, all matching entries are returned.

Throws:

LdapException

search

public LdapEntry[] search(java.lang.String base,
                          java.lang.String filter,
                          java.lang.String[] attrNames,
                          int maxres)
                   throws LdapException

Searches and retrieves attributes for 0 or more entries, using the admin dn/pswd for authorization. See searchDn for details. See addUserEntry for doc on the attribute names.

Parameters:

authName - the uid of the caller

password - the password associated with authName

base - The starting dn of the search. If null or "", start at top.

filter - The search phrase.

attrNames - an array of attribute names to be returned If null, all available attributes are returned.

maxres - the maximum number of LDAP entries to return. If maxres <= 0, all matching entries are returned.

Throws:

LdapException

searchDn

public LdapEntry[] searchDn(java.lang.String authDn,
                            java.lang.String password,
                            java.lang.String specBase,
                            java.lang.String filter,
                            java.lang.String[] attrNames,
                            int maxres)
                     throws LdapException

Low level method: searches and retrieves attributes for 0 or more entries, using the specified dn/pswd for authorization. See addUserEntry for doc on the attribute names.

Filter syntax

Filter syntax is described in RFC 2254 and associated RFCs. The attributes contained in the various DLESE entry types are specified in the OpenLDAP configuration file, "slapd.conf", and in the OpenLDAP schema files. Here is a summary of the syntax.

Filter character set

The character set used in filters is the UTF-8 encoding of ISO 10646 (Unicode): see www.unicode.org/. Any character in the character set may be represented by a backslash with two hex chars. For example, the asterisk * could also be written \2A.

Filter items

A filter expression is composed of items. An item is a single comparison, of the form: ( attributeName=value )
The simplest filter is a single item, like:
(sn=smith)
This filter matches all entries having a surname (sn) of smith. Most searches are case insensitive, so this would find surnames like "Smith", "SmiTH", "smith", etc.

Some attributes are optional. To find all entries in which an attribute exists, even if it has a blank value, use a filter item like:
(labeledURI=*)
This finds all entries having a labeledURI (used to specify a URL).

The "*" acts much like a shell wildcard, so to find all entries having a labeledURI that uses http and involves dlese, one could use:
(labeledURI=*http://*dlese*)

Filter expressions

Boolean expressions may be build up from items using the idiotic "prefix notation" specified by RFC 2254. I guess they didn't feel like writing a real expression parser. For example, to find all entries having givenName = "sally" and surname = "smith" and phone with a "303" area code, one could use:
(& (givenName=sally) (sn=smith) (telephoneNumber=303*) )
That is, the "&" operator precedes all its operands.

Quotes in filters

Quotes within filters are not used. In some cases they happen to work, but in general they do not. So the following two filters appear to work identically, although only the first is correct.
(cn=sally smith) OK
(cn="sally smith") Incorrect

Filter operators and symbols

The exact meaning of the comparison operators "=", "~=", ">=", "<=" are defined in the attribute's definition. For example, attributeType "sn" (a surname) is defined in the OpenLDAP schema file "core.schema". There "sn" inherits the syntax of attributeType "name". The definition of "name" specifies "EQUALITY caseIgnoreMatch", meaning that comparisons are case insensitive.

Incredibly, RFC 2254 defines no operators for "<" and ">".

Operator or symbol	Meaning
=	Test equality, according to the attribute definition Example: (sn=smith) Notes: Matches all entries having an sn of "smith", or a case-changed variant thereof. Usually case insensitive.
=~	Test approximate equality, according to the attribute definition Example: (sn=~smith) Notes: seldom used
<=	Test less than or equal, according to the attribute definition Example: (numWidgets<=33) Notes: seldom used
>=	Test greater than or equal, according to the attribute definition Example: (numWidgets>=33) Notes: seldom used
*	Wildcard: 0 or more chars Example: (sn=*smith*) Notes: matches all entries having sn that contains "smith" in any case: "Smithsonian", "Arrowsmith", "blacksmIThing", etc. Example: (sn=*) Notes: matches all entries having an "sn" attribute Example: (objectclass=*) Notes: matches all entries in the LDAP database, since all entries must have an "objectclass" attribute
&	Logical and Example: (& (sn=smith) (givenName=Sally)) Notes: Matches all entries having both sn=smith and givenName=Sally Caution: uses idiotic prefix notation: (& item1 item2 item3 ... )
|	Logical or Example: (| (sn=smith) (givenName=Sally)) Notes: Matches all entries having either sn=smith or givenName=Sally Caution: uses idiotic prefix notation: (| item1 item2 item3 ... )
!	Logical negation Example: (! (sn=*smith*)) Notes: Matches all entries that don't contain the string "smith" or a case-changed variant thereof.
\	Escape character Example: (cn=stars \2A for sale) Notes: Matches all entries having cn="stars * for sale". Example: (cn=parens \28\29 for sale) Notes: Matches all entries having cn="parens () for sale". Example: (cn=*\A9*) Notes: Matches all entries with cn containing a copyright symbol.

Parameters:

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

specBase - The starting dn of the search. If null or "", start at top.

filter - The search phrase.

attrNames - an array of attribute names to be returned If null, all available attributes are returned.

maxres - the maximum number of LDAP entries to return. If maxres <= 0, all matching entries are returned.

Returns:

An array of LdapEntry. Each LdapEntry represents one returned entry. If attrNames was specified, each LdapEntry has the same attributes in the specified order.

If attrNames is null, ALL available attributes are returned for each entry. In this case:

• Caution: The entries may have different numbers of attribute names.
• Caution: Within an entry, the attributes may have different numbers of values.
• The attribute names within each entry are sorted independently.

Throws:

LdapException

setUserAttribute

public void setUserAttribute(java.lang.String authName,
                             java.lang.String password,
                             java.lang.String subjectName,
                             java.lang.String attrName,
                             java.lang.String[] values)
                      throws LdapException

Sets the value of a single attribute, using the specified uid/pswd for authorization. Any previous values for the attribute are removed. See setAttributeDn.

Parameters:

authName - the uid of the caller

password - the password associated with authName

subjectName - the uid containing the attribute to be modified

attrName - the attribute name

values - the new values for the attribute

Throws:

LdapException

setUserAttribute

public void setUserAttribute(java.lang.String subjectName,
                             java.lang.String attrName,
                             java.lang.String[] values)
                      throws LdapException

Sets the value of a single attribute, using the admin dn/pswd for authorization. Any previous values for the attribute are removed. See setAttributeDn.

Parameters:

subjectName - the uid containing the attribute to be modified

attrName - the attribute name

values - the new values for the attribute

Throws:

LdapException

setAttributeDn

public void setAttributeDn(java.lang.String authDn,
                           java.lang.String password,
                           java.lang.String subjectDn,
                           java.lang.String attrName,
                           java.lang.String[] values)
                    throws LdapException

Low level method: sets the value of a single attribute, using the specified dn/pswd for authorization. Any previous values for the attribute are removed.

Parameters:

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

subjectDn - the dn containing the attribute to be modified

attrName - the attribute name

values - the new values for the attribute

Throws:

LdapException

addUserAttributeValue

public void addUserAttributeValue(java.lang.String authName,
                                  java.lang.String password,
                                  java.lang.String subjectName,
                                  java.lang.String attrName,
                                  java.lang.String value)
                           throws LdapException

Adds a single value to a single attribute, using the specified uid/pswd for authorization. See addAttributeValueDn.

Parameters:

authName - the uid of the caller

password - the password associated with authName

subjectName - the uid containing the attribute to be modified

attrName - the attribute name

value - the new value

Throws:

LdapException

addUserAttributeValue

public void addUserAttributeValue(java.lang.String subjectName,
                                  java.lang.String attrName,
                                  java.lang.String value)
                           throws LdapException

Adds a single value to a single attribute, using the admin dn/pswd for authorization. See addAttributeValueDn.

Parameters:

authName - the uid of the caller

password - the password associated with authName

subjectName - the uid containing the attribute to be modified

attrName - the attribute name

value - the new value

Throws:

LdapException

addAttributeValueDn

public void addAttributeValueDn(java.lang.String authDn,
                                java.lang.String password,
                                java.lang.String subjectDn,
                                java.lang.String attrName,
                                java.lang.String value)
                         throws LdapException

Low level method: adds a single value to a single attribute, using the specified dn/pswd for authorization.

Parameters:

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

subjectDn - the dn containing the attribute to be modified

attrName - the attribute name

value - the new value

Throws:

LdapException

removeUserAttributeValue

public void removeUserAttributeValue(java.lang.String authName,
                                     java.lang.String password,
                                     java.lang.String subjectName,
                                     java.lang.String attrName,
                                     java.lang.String value)
                              throws LdapException

Removes a single value from a single attribute, or removes the entire attribute and all values, using the specified uid/pswd for authorization.

Parameters:

host - the URI of the LDAP server.

authName - the uid of the caller

password - the password associated with authName

subjectName - the uid containing the attribute to be modified

attrName - the attribute name

value - the value to be removed. If null, the entire attribute and all values are removed.

Throws:

LdapException

removeUserAttributeValue

public void removeUserAttributeValue(java.lang.String subjectName,
                                     java.lang.String attrName,
                                     java.lang.String value)
                              throws LdapException

Removes a single value from a single attribute, or removes the entire attribute and all values, using a the admin dn/pswd for authorization.

Parameters:

host - the URI of the LDAP server.

authName - the uid of the caller

password - the password associated with authName

subjectName - the uid containing the attribute to be modified

attrName - the attribute name

value - the value to be removed. If null, the entire attribute and all values are removed.

Throws:

LdapException

removeAttributeValueDn

public void removeAttributeValueDn(java.lang.String authDn,
                                   java.lang.String password,
                                   java.lang.String subjectDn,
                                   java.lang.String attrName,
                                   java.lang.String value)
                            throws LdapException

Low level method: removes a single value from a single attribute, or removes the entire attribute and all values, using the specified dn/pswd for authorization.

Parameters:

host - the URI of the LDAP server.

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

subjectDn - the dn containing the attribute to be modified

attrName - the attribute name

value - the value to be removed. If null, the entire attribute and all values are removed.

Throws:

LdapException

addUserEntry

public void addUserEntry(java.lang.String newName,
                         java.lang.String[][] attrStgs)
                  throws LdapException

Adds a new LDAP entry for a user, using a the admin dn/pswd for authorization.

Required attributes
All values are unique except as noted. See the OpenLDAP configuration file, slapd.conf, for the final say.

Attribute	Meaning	Typical values
DLESEemailPrimary	primary email address	somebody@someplace.org
DLESEloginName	login name	jsmith
DLESEnameFirst	first name (given name)	James
DLESEnameLast	last name (surname or family name)	Smith
userPassword	login password	aBigSecret

Optional attributes
All values are unique except as noted. See the OpenLDAP configuration file, slapd.conf, for the final say.

Attribute	Meaning	Typical values
DLESEadr1	street address line 1	123 Some Street
DLESEadr2	street address line 2	Dept 456
DLESEcity	street address: city	Whoville
DLESEcounty	street address: county	Tack County
DLESEcountry	street address: country	USA
DLESEemailAlt	alternate email address	someOther@someU.edu
DLESEfax	fax phone number	303-555-1212
DLESEfocus	focus (may have multiple values)	elementary school, graduate students, ...
DLESEnameMiddle	middle name or initial	M
DLESEnameNick	nick name or casual name	Slim
DLESEnameSuffix	name suffix, like Sr or PhD	PhD
DLESEnameTitle	common title, like Mr, Ms, Dr	Dr
DLESEorg1	organization 1	UCAR
DLESEorg2	organization 2	U of Colorado
DLESEphone1	primary phone number	303-555-1212
DLESEphone2	secondary phone number	303-555-1212
DLESEpostalCode	street address: postalCode	81234-4321
DLESEprofResp	professional responsibility (may have multiple values)	teaching, student, administrator, ...
DLESEstate	street address: state	CO
DLESEurl	url	http://www.somesite.org
DLESEuserPasswordPhrase	password reminder phrase	Mother's name
DLESEworkSphere	work sphere (may have multiple values)	atmosphere, biosphere, solid earth, ...

Parameters:

newName - the new uid

attrStgs - the names and values of the attributes. Each row i represents one attribute and it's values: attrs[i][0] is the String attribute name, and attrs[i][1 ... rowlen-1] are the String values.

Note: the attrStgs matrix need not be rectangular, since different attributes may have different numbers of values.

The "objectclass" attribute is added automatically, and should not be specified in attrStgs.

Throws:

LdapException

addEntryDn

public void addEntryDn(java.lang.String authDn,
                       java.lang.String password,
                       java.lang.String newDn,
                       java.lang.String[][] attrStgs)
                throws LdapException

Low level method: adds a new LDAP entry, using the specified dn/pswd for authorization.

Parameters:

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

newDn - the new dn

attrStgs - the names and values of the attributes. Each row i represents one attribute and it's values: attrs[i][0] is the String attribute name, and attrs[i][1 ... rowlen-1] are the String values.

Note: the attrStgs matrix need not be rectangular, since different attributes may have different numbers of values.

Throws:

LdapException

storeUserObject

public void storeUserObject(java.lang.String authName,
                            java.lang.String password,
                            java.lang.String userName,
                            java.lang.String objectName,
                            java.lang.Object obj)
                     throws LdapException

Stores a serialized Java Object, and associated attributes, using the specified uid/pswd for authorization. See getUserObject.

CAUTION: Storing a null object leaves a JNDI Context in the database, and on the next getUserObject call the Context will be returned instead of a user object. Storing a null object is NOT RECOMMENDED!

Parameters:

authName - the uid of the caller

password - the password associated with authName

userName - the name of the user associated with this object

objectName - the name associated with this object, such as "dcsState".

attrStgs - the names and values of the attributes. Each row i represents one attribute and it's values: attrs[i][0] is the String attribute name, and attrs[i][1 ... rowlen-1] are the String values.

Note: the attrStgs matrix need not be rectangular, since different attributes may have different numbers of values.

obj - the Java Object to be serialized.

Throws:

LdapException

storeObjectDn

public void storeObjectDn(java.lang.String authDn,
                          java.lang.String password,
                          java.lang.String curDn,
                          java.lang.String[][] attrStgs,
                          java.lang.Object obj)
                   throws LdapException

Low level method: stores a serialized Java Object, and associated attributes, using the specified dn/pswd for authorization. See getObjectDn.

Parameters:

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

newDn - the new dn

attrStgs - the names and values of the attributes. This must contain ALL the needed attributes: objectclass, etc.
Each row i represents one attribute and it's values:
attrs[i][0] is the String attribute name,
and attrs[i][1 ... rowlen-1] are the String values.

Note: the attrStgs matrix need not be rectangular, since different attributes may have different numbers of values.

obj - the Java Object to be serialized.

Throws:

LdapException

removeUserObject

public void removeUserObject(java.lang.String authName,
                             java.lang.String password,
                             java.lang.String userName,
                             java.lang.String objectName)
                      throws LdapException

Removes a serialized Java Object, and associated attributes, using the specified uid/pswd for authorization.

Parameters:

authName - the uid of the caller

password - the password associated with authName

userName - the name of the user associated with this object

objectName - the name associated with this object, such as "dcsState".

Silly JNDI/LDAP spec: Returns void, with no exceptions, whether or not the objectName existed before the call.

Throws:

LdapException

getUserObject

public java.lang.Object getUserObject(java.lang.String authName,
                                      java.lang.String password,
                                      java.lang.String userName,
                                      java.lang.String objectName)
                               throws LdapException

Retrieves a serialized Java Object, using the specified uid/pswd for authorization. See storeUserObject. To retrieve the attributes, use getUserObjectAttributes.

Parameters:

authName - the uid of the caller

password - the password associated with authName

userName - the name of the user associated with this object

objectName - the name associated with this object.

Throws:

LdapException

getObjectDn

public java.lang.Object getObjectDn(java.lang.String authDn,
                                    java.lang.String password,
                                    java.lang.String objectDn)
                             throws LdapException

Low level method: Retrieves a serialized Java Object, using the specified dn/pswd for authorization. See storeObjectDn.

Parameters:

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

objectDn - the dn of the object.

Throws:

LdapException

getUserObjectAttributes

public LdapEntry getUserObjectAttributes(java.lang.String authName,
                                         java.lang.String password,
                                         java.lang.String userName,
                                         java.lang.String objectName,
                                         java.lang.String[] attrNames)
                                  throws LdapException

Deprecated: Retrieves the attributes associated with a serialized Java Object, using the specified uid/pswd for authorization.

This method is deprecated since currently no user-accessible attributes are stored with Java objects. At some future date we could change this, allowing attributes to be stored with Java objects. See storeUserObject.

See storeUserObject. To retrieve the Object itself, use getUserObject.

Parameters:

authName - the uid of the caller

password - the password associated with authName

userName - the name of the user associated with this object

objectName - the name associated with this object.

attrNames - an array of attribute names to be returned. If null, all available attributes are returned.

Returns:

An LdapEntry representing one returned entry. Throws LdapNotFoundException if entry not found. If attrNames was specified, the LdapEntry has the same attributes in the specified order.

If attrNames is null, the LdapEntry contains all available attributes for the entry, sorted by attribute name.

Throws:

LdapException

renameUserEntry

public void renameUserEntry(java.lang.String oldName,
                            java.lang.String newName)
                     throws LdapException

Deprecated: Renames an user entry in the LDAP database, using a the admin dn/pswd for authorization.

CAUTION: This will throw an Exception if any user objects are stored for this user, since OpenLDAP does not yet support renaming subtrees. NOT RECOMMENDED!

Parameters:

authName - the uid of the caller

password - the password associated with authName

oldName - the old uid.

newName - the new uid.

Throws:

LdapException

renameEntryDn

public void renameEntryDn(java.lang.String authDn,
                          java.lang.String password,
                          java.lang.String oldDn,
                          java.lang.String newDn)
                   throws LdapException

Deprecated: Low level method: renames an entry in the LDAP database, using the specified dn/pswd for authorization.

Parameters:

host - the URI of the LDAP server.

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

oldDn - the old dn.

newDn - the new dn.

Throws:

LdapException

removeUserEntry

public void removeUserEntry(java.lang.String subjectName)
                     throws LdapException

Removes an entry from the LDAP database, using a the admin dn/pswd for authorization.

Silly JNDI/LDAP spec: Returns void, with no exceptions, whether or not the subjectName existed before the call.

Parameters:

subjectName - the uid to be removed.

Throws:

LdapException

removeEntryDn

public void removeEntryDn(java.lang.String authDn,
                          java.lang.String password,
                          java.lang.String subjectDn)
                   throws LdapException

Low level method: removes an entry from the LDAP database, using the specified dn/pswd for authorization.

Silly JNDI/LDAP spec: Returns void, with no exceptions, whether or not the subjectDn existed before the call.

Parameters:

host - the URI of the LDAP server.

authDn - the authorized dn (distinguished name) of the caller

password - the password associated with authDn

subjectDn - the dn to be removed.

Throws:

LdapException

userExists

public boolean userExists(java.lang.String subjectName)
                   throws LdapException

Tests to see if a user entry exists in the LDAP database, using a the admin dn/pswd for authorization.

Parameters:

subjectName - the uid to be removed.

Throws:

LdapException

createList

public void createList(java.lang.String listName,
                       java.lang.String ownerName)
                throws LdapException

Creates an empty list of names, using a the admin dn/pswd for authorization, and adds the owner as a DLESElistMember of the list.

Parameters:

listName - the name of the list to be created. On open lists, the user can add/remove themself. On all other lists, only the list owner can add/remove DLESEloginNames.

ownerName - the uid of the list owner.

Throws:

LdapException

removeEntireList

public void removeEntireList(java.lang.String listName)
                      throws LdapException

Removes a list of names, using a the admin dn/pswd for authorization.

Silly JNDI/LDAP spec: Returns void, with no exceptions, whether or not the listName existed before the call.

Parameters:

listName - the name of the list to be created.

Throws:

LdapException

addListName

public void addListName(java.lang.String authName,
                        java.lang.String password,
                        java.lang.String listName,
                        java.lang.String userName)
                 throws LdapException

Adds a single "DLESElistMember" name to the specified list.

Parameters:

authName - the uid of the caller

password - the password associated with authName

listName - the name of the list to be created.

userName - the uid to be added to the list.

Throws:

LdapException

removeListName

public void removeListName(java.lang.String authName,
                           java.lang.String password,
                           java.lang.String listName,
                           java.lang.String userName)
                    throws LdapException

Removes a single "DLESElistMember" name from the specified list.

Parameters:

authName - the uid of the caller

password - the password associated with authName

listName - the name of the list to be created.

userName - the uid to be removed from the list.

Throws:

LdapException

getListMembers

public java.lang.String[] getListMembers(java.lang.String authName,
                                         java.lang.String password,
                                         java.lang.String listName)
                                  throws LdapException

Returns all the "DLESElistMember" attribute values from a list, as full dn's (distinguished names), using a the specified dn/pswd for authorization. Returns null if no DLESElistMembers in the list.

Parameters:

authName - the uid of the caller

password - the password associated with authName

listName - the name of the list to be created.

Throws:

LdapException

getListMembers

public java.lang.String[] getListMembers(java.lang.String listName)
                                  throws LdapException

Returns all the "DLESElistMember" attribute values from a list, as full dn's (distinguished names), using a the admin dn/pswd for authorization. Returns null if no DLESElistMembers in the list.

Parameters:

authName - the uid of the caller

password - the password associated with authName

listName - the name of the list to be created.

Throws:

LdapException

getListMembersDn

public java.lang.String[] getListMembersDn(java.lang.String authDn,
                                           java.lang.String password,
                                           java.lang.String listDn)
                                    throws LdapException

Low level: Returns all the "DLESElistMember" attribute values from a list, as full dn's (distinguished names); returns null if no DLESElistMembers in the list.

Parameters:

authName - the uid of the caller

password - the password associated with authName

listName - the name of the list to be created.

Throws:

LdapException

getListNames

public java.lang.String[] getListNames(java.lang.String authName,
                                       java.lang.String password,
                                       java.lang.String listName)
                                throws LdapException

Returns all the "DLESElistMember" attribute values from a list, as uids (not full dn's); returns null if no DLESElistMembers in the list. See also getListMembers.

Parameters:

authName - the uid of the caller

password - the password associated with authName

listName - the name of the list to be created.

Throws:

LdapException

getListNames

public java.lang.String[] getListNames(java.lang.String listName)
                                throws LdapException

Returns all the "DLESElistMember" attribute values from a list, as uids (not full dn's); returns null if no DLESElistMembers in the list. See also getListMembers.

Parameters:

listName - the name of the list to be created.

Throws:

LdapException

getListAttributes

public LdapEntry[] getListAttributes(java.lang.String authName,
                                     java.lang.String password,
                                     java.lang.String listName,
                                     java.lang.String[] attrNames)
                              throws LdapException

Returns the desired attributes for each "DLESElistMember" attribute value from a list, using the specified dn/pswd for authorization. Returns null if no DLESElistMembers in the list. See also getListMembers.

Parameters:

authName - the uid of the caller

password - the password associated with authName

listName - the name of the list to be created.

attrNames - an array of attribute names to be returned. If null, all available attributes are returned.

Throws:

LdapException

getListAttributes

public LdapEntry[] getListAttributes(java.lang.String listName,
                                     java.lang.String[] attrNames)
                              throws LdapException

Returns the desired attributes for each "DLESElistMember" attribute value from a list, using a the admin dn/pswd for authorization. Returns null if no DLESElistMembers in the list. See also getListMembers.

Parameters:

listName - the name of the list to be created.

attrNames - an array of attribute names to be returned. If null, all available attributes are returned.

Throws:

LdapException

getProperty

protected java.lang.String getProperty(java.lang.String propName,
                                       java.util.Properties props,
                                       java.lang.String pfile)
                                throws LdapException

Returns the desired property value; throws an LdapException if not found.

Parameters:

propName - The name of the desired property.

props - The Properties container.

pfile - The name of the properties file: not opened, only used for error messages.

Throws:

LdapException

mkUserDn

protected java.lang.String mkUserDn(java.lang.String userName)

Given a UID, returns the corresponding full dn (distinguished name).