Package org.dlese.dpc.ldap

Class LdapClient

java.lang.Object
org.dlese.dpc.ldap.LdapClient
Direct Known Subclasses:
NSDLLdapClient
public class LdapClient extends 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
invalid @link 
{@link #getListMembers(String,String,String,)
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
invalid reference 
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 invalid input: '<' entries.length; ii++) {
             System.out.println("\nEntry " + ii + " dn: "
                 + entries[ii].getDn());
 
             // For each attribute of the entry:
             for (int jj = 0; jj invalid input: '<' 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 invalid input: '<' 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 Details

  • Constructor Details

    • LdapClient

      public LdapClient(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 Details

    • 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 Date getUtcCreateTimestamp(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 Date getUtcModifyTimestamp(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(String subjectName, 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 String[] getSingleAttribute(String authName, String password, String subjectName, 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 String[] getSingleAttribute(String subjectName, 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 String[] getSingleAttributeDn(String authDn, String password, String subjectDn, 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(String authName, String password, String subjectName, 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(String subjectName, 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(String authDn, String password, String subjectDn, 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(String authName, String password, String base, String filter, 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(String base, String filter, 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:
      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.
      authName - the uid of the caller
      password - the password associated with authName
      Throws:
      LdapException

    • searchDn

      public LdapEntry[] searchDn(String authDn, String password, String specBase, String filter, 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(String authName, String password, String subjectName, String attrName, 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(String subjectName, String attrName, 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(String authDn, String password, String subjectDn, String attrName, 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(String authName, String password, String subjectName, String attrName, 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(String subjectName, String attrName, String value) throws LdapException
      Adds a single value to a single attribute, using the admin dn/pswd for authorization. See addAttributeValueDn.
      Parameters:
      subjectName - the uid containing the attribute to be modified
      attrName - the attribute name
      value - the new value
      authName - the uid of the caller
      password - the password associated with authName
      Throws:
      LdapException

    • addAttributeValueDn

      public void addAttributeValueDn(String authDn, String password, String subjectDn, String attrName, 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(String authName, String password, String subjectName, String attrName, 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:
      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.
      host - the URI of the LDAP server.
      Throws:
      LdapException

    • removeUserAttributeValue

      public void removeUserAttributeValue(String subjectName, String attrName, 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:
      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.
      host - the URI of the LDAP server.
      authName - the uid of the caller
      password - the password associated with authName
      Throws:
      LdapException

    • removeAttributeValueDn

      public void removeAttributeValueDn(String authDn, String password, String subjectDn, String attrName, 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:
      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.
      host - the URI of the LDAP server.
      Throws:
      LdapException

    • addUserEntry

      public void addUserEntry(String newName, 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(String authDn, String password, String newDn, 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(String authName, String password, String userName, String objectName, 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".
      obj - the Java Object to be serialized.
      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

    • storeObjectDn

      public void storeObjectDn(String authDn, String password, String curDn, String[][] attrStgs, 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
      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.
      newDn - the new dn
      Throws:
      LdapException

    • removeUserObject

      public void removeUserObject(String authName, String password, String userName, 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 Object getUserObject(String authName, String password, String userName, 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 Object getObjectDn(String authDn, String password, 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(String authName, String password, String userName, String objectName, 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(String oldName, 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:
      oldName - the old uid.
      newName - the new uid.
      authName - the uid of the caller
      password - the password associated with authName
      Throws:
      LdapException

    • renameEntryDn

      public void renameEntryDn(String authDn, String password, String oldDn, String newDn) throws LdapException
      Deprecated: Low level method: renames an entry in the LDAP database, using the specified dn/pswd for authorization.
      Parameters:
      authDn - the authorized dn (distinguished name) of the caller
      password - the password associated with authDn
      oldDn - the old dn.
      newDn - the new dn.
      host - the URI of the LDAP server.
      Throws:
      LdapException

    • removeUserEntry

      public void removeUserEntry(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(String authDn, String password, 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:
      authDn - the authorized dn (distinguished name) of the caller
      password - the password associated with authDn
      subjectDn - the dn to be removed.
      host - the URI of the LDAP server.
      Throws:
      LdapException

    • userExists

      public boolean userExists(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(String listName, 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(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(String authName, String password, String listName, 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(String authName, String password, String listName, 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 String[] getListMembers(String authName, String password, 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 String[] getListMembers(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:
      listName - the name of the list to be created.
      authName - the uid of the caller
      password - the password associated with authName
      Throws:
      LdapException

    • getListMembersDn

      public String[] getListMembersDn(String authDn, String password, 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:
      password - the password associated with authName
      authName - the uid of the caller
      listName - the name of the list to be created.
      Throws:
      LdapException

    • getListNames

      public String[] getListNames(String authName, String password, 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 String[] getListNames(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(String authName, String password, String listName, 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(String listName, 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 String getProperty(String propName, Properties props, 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 String mkUserDn(String userName)
      Given a UID, returns the corresponding full dn (distinguished name).