netscape.ldap

Interface LDAPv2

Known Subinterfaces:
LDAPv3
Known Implementing Classes:
LDAPConnection

public interface LDAPv2

This interface summarizes the basic functionality available in the Lightweight Directory Access Protocol (LDAP) version 2. (See RFC 1777 for the definition of the protocol.)

In the general model for this protocol, objects exist under a directory in a particular server. Objects are identified by unique, hierarchical names called Distinguished Names, commonly abreviated "DN". An example of a DN:

  cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=us
 
Objects have attributes, of the form
  attributeName = attributeValue(s)
 
Attribute names must be Strings, and attribute values can be any 8-bit sequence (Strings or binary values).
Version:
1.0

Field Summary

static int
BATCHSIZE
Option specifying the number of results to return at a time.
static int
BIND
Option specifying the object containing the method for authenticating to the server.
static int
DEFAULT_PORT
The default port number for LDAP servers.
static int
DEREF
Option specifying how aliases are dereferenced.
static int
DEREF_ALWAYS
Specifies that aliases are always dereferenced.
static int
DEREF_FINDING
Specifies that aliases are dereferenced when finding the starting point for the search (but not when searching under that starting entry).
static int
DEREF_NEVER
Specifies that aliases are never dereferenced.
static int
DEREF_SEARCHING
Specifies that aliases are dereferenced when searching the entries beneath the starting point of the search (but not when finding the starting entry).
static int
PROTOCOL_VERSION
Option specifying the version of the LDAP protocol used by your client when interacting with the LDAP server.
static int
REFERRALS
Option specifying whether or not referrals to other LDAP servers are followed automatically.
static int
REFERRALS_HOP_LIMIT
Option specifying the maximum number of referrals to follow in a sequence when requesting an LDAP operation.
static int
REFERRALS_REBIND_PROC
Option specifying the object containing the method for getting authentication information (the distinguished name and password) used during a referral.
static int
SCOPE_BASE
Specifies that the scope of a search includes only the base DN (distinguished name).
static int
SCOPE_ONE
Specifies that the scope of a search includes only the entries one level below the base DN (distinguished name).
static int
SCOPE_SUB
Specifies that the scope of a search includes the base DN (distinguished name) and all entries at all levels beneath that base.
static int
SERVER_TIMELIMIT
Option specifying the maximum number of milliseconds the server should spend returning search results before aborting the search.
static int
SIZELIMIT
Option specifying the maximum number of search results to return.
static int
TIMELIMIT
Option specifying the maximum number of milliseconds to wait for an operation to complete.

Method Summary

void
abandon(LDAPSearchResults results)
Notifies the server to not send additional results associated with this LDAPSearchResults object, and discards any results already received.
void
add(LDAPEntry entry)
Adds an entry to the directory.
void
add(LDAPEntry entry, LDAPConstraints cons)
Adds an entry to the directory.
void
authenticate(String DN, String passwd)
Authenticates user with the LDAP server.
void
bind(String DN, String passwd)
Authenticates user with the LDAP server.
boolean
compare(String DN, LDAPAttribute attr)
Compares the given entry's attribute value to the specified attribute value.
boolean
compare(String DN, LDAPAttribute attr, LDAPConstraints cons)
Compares the given entry's attribute value to the specified attribute value.
void
connect(String host, int port)
Connects to the LDAP server.
void
connect(String host, int port, String dn, String passwd)
Connects and authenticates to the LDAP server.
void
delete(String DN)
Removes an entry from the directory.
void
delete(String DN, LDAPConstraints cons)
Removes an entry from the directory.
void
disconnect()
Disconnects from the LDAP server.
Object
getOption(int option)
Retrieves an option that applies to the connection.
void
modify(String DN, LDAPModification mod)
Modifies an attribute of a directory entry.
void
modify(String DN, LDAPModification mod, LDAPConstraints cons)
Modifies an attribute of a directory entry.
void
modify(String DN, LDAPModificationSet mods)
Modifies the attributes of a directory entry.
void
modify(String DN, LDAPModificationSet mods, LDAPConstraints cons)
Modifies the attributes of a directory entry.
LDAPEntry
read(String DN)
Read the entry corresponding to the specified distinguished name (DN).
LDAPEntry
read(String DN, attrs[] )
Read the entry corresponding to the specified distinguished name (DN), and retrieve only the specified attributes.
LDAPEntry
read(String DN, attrs[] , LDAPSearchConstraints cons)
Read the entry corresponding to the specified distinguished name (DN), and retrieve only the specified attributes.
void
rename(String DN, String newRDN, boolean deleteOldRDN)
Changes the name of an entry in the directory.
void
rename(String DN, String newRDN, boolean deleteOldRDN, LDAPConstraints cons)
Changes the name of an entry in the directory.
LDAPSearchResults
search(String base, int scope, String filter, String[] attrs, boolean attrsOnly)
Searches for entries in the directory.
LDAPSearchResults
search(String base, int scope, String filter, String[] attrs, boolean attrsOnly, LDAPSearchConstraints cons)
Searches for entries in the directory.
void
setOption(int option, Object value)
Sets an option that applies to the connection.

Field Details

BATCHSIZE

public static final int BATCHSIZE
Option specifying the number of results to return at a time.
Field Value:
20

BIND

public static final int BIND
Option specifying the object containing the method for authenticating to the server.
Field Value:
13

DEFAULT_PORT

public static final int DEFAULT_PORT
The default port number for LDAP servers. You can specify this identifier when calling the LDAPConnection.connect method to connect to an LDAP server.
Field Value:
389
See Also:
netscape.ldap.LDAPConnection.connect

DEREF

public static final int DEREF
Field Value:
2

DEREF_ALWAYS

public static final int DEREF_ALWAYS
Specifies that aliases are always dereferenced.
Field Value:
3

DEREF_FINDING

public static final int DEREF_FINDING
Specifies that aliases are dereferenced when finding the starting point for the search (but not when searching under that starting entry).
Field Value:
2

DEREF_NEVER

public static final int DEREF_NEVER
Specifies that aliases are never dereferenced.
Field Value:
0

DEREF_SEARCHING

public static final int DEREF_SEARCHING
Specifies that aliases are dereferenced when searching the entries beneath the starting point of the search (but not when finding the starting entry).
Field Value:
1

PROTOCOL_VERSION

public static final int PROTOCOL_VERSION
Option specifying the version of the LDAP protocol used by your client when interacting with the LDAP server. If no version is set, the default version is 2. If you are planning to use LDAP v3 features (such as controls or extended operations), you should set this version to 3 or specify version 3 as an argument to the authenticate method of the LDAPConnection object.
Field Value:
17
See Also:
LDAPConnection.getOption(int), LDAPConnection.setOption(int,Object), netscape.ldap.LDAPConnection.authenticate(int, java.lang.String, java.lang.String)

REFERRALS

public static final int REFERRALS
Option specifying whether or not referrals to other LDAP servers are followed automatically.
Field Value:
8

REFERRALS_HOP_LIMIT

public static final int REFERRALS_HOP_LIMIT
Option specifying the maximum number of referrals to follow in a sequence when requesting an LDAP operation.
Field Value:
10

REFERRALS_REBIND_PROC

public static final int REFERRALS_REBIND_PROC
Option specifying the object containing the method for getting authentication information (the distinguished name and password) used during a referral. For example, when referred to another LDAP server, your client uses this object to obtain the DN and password. Your client authenticates to the LDAP server using this DN and password.
Field Value:
9

SCOPE_BASE

public static final int SCOPE_BASE
Specifies that the scope of a search includes only the base DN (distinguished name).
Field Value:
0
See Also:
netscape.ldap.LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints)

SCOPE_ONE

public static final int SCOPE_ONE
Specifies that the scope of a search includes only the entries one level below the base DN (distinguished name).
Field Value:
1
See Also:
netscape.ldap.LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints)

SCOPE_SUB

public static final int SCOPE_SUB
Specifies that the scope of a search includes the base DN (distinguished name) and all entries at all levels beneath that base.
Field Value:
2
See Also:
netscape.ldap.LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints)

SERVER_TIMELIMIT

public static final int SERVER_TIMELIMIT
Option specifying the maximum number of milliseconds the server should spend returning search results before aborting the search.
Field Value:
5

SIZELIMIT

public static final int SIZELIMIT
Option specifying the maximum number of search results to return.

Field Value:
3

TIMELIMIT

public static final int TIMELIMIT
Option specifying the maximum number of milliseconds to wait for an operation to complete.
Field Value:
4

Method Details

abandon

public void abandon(LDAPSearchResults results)
            throws LDAPException
Notifies the server to not send additional results associated with this LDAPSearchResults object, and discards any results already received.
Parameters:
results - LDAPSearchResults object returned from a search
Throws:
LDAPException - Failed to notify the server.

add

public void add(LDAPEntry entry)
            throws LDAPException
Adds an entry to the directory.
Parameters:
entry - new entry to add to the directory
Throws:
LDAPException - Failed to add the entry to the directory.

add

public void add(LDAPEntry entry,
                LDAPConstraints cons)
            throws LDAPException
Adds an entry to the directory.
Parameters:
entry - new entry to add to the directory
cons - the constraints set for the add operation
Throws:
LDAPException - Failed to add the entry to the directory.

authenticate

public void authenticate(String DN,
                         String passwd)
            throws LDAPException
Authenticates user with the LDAP server.
Parameters:
DN - distinguished name to use for authentication
passwd - password for authentication
Throws:
LDAPException - Failed to authenticate to the server.

bind

public void bind(String DN,
                 String passwd)
            throws LDAPException
Authenticates user with the LDAP server.
Parameters:
DN - distinguished name to use for authentication
passwd - password for authentication
Throws:
LDAPException - Failed to authenticate to the server.

compare

public boolean compare(String DN,
                       LDAPAttribute attr)
            throws LDAPException
Compares the given entry's attribute value to the specified attribute value.
Parameters:
DN - distinguished name of the entry that you want compared against the specified attribute value
attr - attribute name and value to use in the comparison
Throws:
LDAPException - Failed to perform the comparison.

compare

public boolean compare(String DN,
                       LDAPAttribute attr,
                       LDAPConstraints cons)
            throws LDAPException
Compares the given entry's attribute value to the specified attribute value.
Parameters:
DN - distinguished name of the entry that you want compared against the specified attribute value
attr - attribute name and value to use in the comparison
cons - the constraints set for the compare operation
Throws:
LDAPException - Failed to perform the comparison.

connect

public void connect(String host,
                    int port)
            throws LDAPException
Connects to the LDAP server.
Parameters:
host - hostname of the LDAP server
port - port number of the LDAP server. To specify the default port, use DEFAULT_PORT.
Throws:
LDAPException - Failed to connect to the server.

connect

public void connect(String host,
                    int port,
                    String dn,
                    String passwd)
            throws LDAPException
Connects and authenticates to the LDAP server.
Parameters:
host - hostname of the LDAP server
port - port number of the LDAP server. To specify the default port, use DEFAULT_PORT.
dn - distinguished name to use for authentication
passwd - password for authentication
Throws:
LDAPException - Failed to connect and authenticate to the server.

delete

public void delete(String DN)
            throws LDAPException
Removes an entry from the directory.
Parameters:
DN - distinguished name identifying the entry to remove
Throws:
LDAPException - Failed to remove the entry from the directory.

delete

public void delete(String DN,
                   LDAPConstraints cons)
            throws LDAPException
Removes an entry from the directory.
Parameters:
DN - distinguished name identifying the entry to remove
cons - the constraints set for the delete operation
Throws:
LDAPException - Failed to remove the entry from the directory.

disconnect

public void disconnect()
            throws LDAPException
Disconnects from the LDAP server. Subsequent operational calls will first try to re-establish the connection to the same LDAP server.
Throws:
LDAPException - Failed to disconnect from the server.

getOption

public Object getOption(int option)
            throws LDAPException
Retrieves an option that applies to the connection. The particular meaning may be implementation-dependent. The standard options are the options described by the LDAPSearchConstraints and LDAPConstraints classes.
Throws:
LDAPException - Failed to retrieve the value of the specified option.

modify

public void modify(String DN,
                   LDAPModification mod)
            throws LDAPException
Modifies an attribute of a directory entry.
Parameters:
DN - distinguished name identifying the entry to modify
mod - the modification to make
Throws:
LDAPException - Failed to modify the specified entry.

modify

public void modify(String DN,
                   LDAPModification mod,
                   LDAPConstraints cons)
            throws LDAPException
Modifies an attribute of a directory entry.
Parameters:
DN - distinguished name identifying the entry to modify
mod - the modification to make
cons - the constraints set for the modify operation
Throws:
LDAPException - Failed to modify the specified entry.

modify

public void modify(String DN,
                   LDAPModificationSet mods)
            throws LDAPException
Modifies the attributes of a directory entry.
Parameters:
DN - distinguished name identifying the entry to modify
mods - list of the modifications to make
Throws:
LDAPException - Failed to modify the specified entry.

modify

public void modify(String DN,
                   LDAPModificationSet mods,
                   LDAPConstraints cons)
            throws LDAPException
Modifies the attributes of a directory entry.
Parameters:
DN - distinguished name identifying the entry to modify
mods - list of the modifications to make
cons - the constraints set for the modify operation
Throws:
LDAPException - Failed to modify the specified entry.

read

public LDAPEntry read(String DN)
            throws LDAPException
Read the entry corresponding to the specified distinguished name (DN).
Parameters:
DN - distinguished name of the entry to retrieve
Throws:
LDAPException - Failed to retrieve the specified entry.

read

public LDAPEntry read(String DN,
                      attrs[] )
            throws LDAPException
Read the entry corresponding to the specified distinguished name (DN), and retrieve only the specified attributes.
Parameters:
DN - distinguished name of the entry to retrieve
Throws:
LDAPException - Failed to retrieve the specified entry.

read

public LDAPEntry read(String DN,
                      attrs[] ,
                      LDAPSearchConstraints cons)
            throws LDAPException
Read the entry corresponding to the specified distinguished name (DN), and retrieve only the specified attributes.
Parameters:
DN - distinguished name of the entry to retrieve
cons - the constraints set for the read operation
Throws:
LDAPException - Failed to retrieve the specified entry.

rename

public void rename(String DN,
                   String newRDN,
                   boolean deleteOldRDN)
            throws LDAPException
Changes the name of an entry in the directory.
Parameters:
DN - distinguished name (DN) of entry
newRDN - the new relative distinguished name (RDN) of the entry
deleteOldRDN - true if the original RDN should no longer be an attribute of the entry; false if it should
Throws:
LDAPException - Failed to rename the entry in the directory.

rename

public void rename(String DN,
                   String newRDN,
                   boolean deleteOldRDN,
                   LDAPConstraints cons)
            throws LDAPException
Changes the name of an entry in the directory.
Parameters:
DN - distinguished name (DN) of entry
newRDN - new relative distinguished name (RDN) of the entry
deleteOldRDN - specifies whether or not the original RDN remains as an attribute of the entry. If true, the original RDN is no longer an attribute of the entry.
cons - the constraints set for the rename operation
Throws:
LDAPException - Failed to rename the entry in the directory.

search

public LDAPSearchResults search(String base,
                                int scope,
                                String filter,
                                String[] attrs,
                                boolean attrsOnly)
            throws LDAPException
Searches for entries in the directory.
Parameters:
base - starting point for the search in the directory (distinguished name)
scope - indicates whether the scope of the search includes only the base DN (equivalent to a read operation), only the entries one level below the base DN, or all entries at all levels beneath the base DN (including the base DN itself)
filter - String which describes the search criteria. The format of the string is described fully in RFC 1558.
attrs - names of the attributes to return for each matching directory entry. If null, all attributes are returned.
attrsOnly - if true, the search will return only the names of the attributes (and not their values)
Throws:
LDAPException - Failed to complete the requested search.

search

public LDAPSearchResults search(String base,
                                int scope,
                                String filter,
                                String[] attrs,
                                boolean attrsOnly,
                                LDAPSearchConstraints cons)
            throws LDAPException
Searches for entries in the directory.
Parameters:
base - starting point for the search in the directory (distinguished name)
scope - indicates whether the scope of the search includes only the base DN (equivalent to a read operation), only the entries one level below the base DN, or all entries at all levels beneath the base DN (including the base DN itself)
filter - String which describes the search criteria. The format of the string is described fully in RFC 1558.
attrs - names of the attributes to return for each matching directory entry. If null, all attributes are returned.
attrsOnly - if true, the search will return only the names of the attributes (and not their values)
cons - constraints specific to the search (for example, the maximum number of entries to return or the maximum time to wait for the search operation to complete)
Throws:
LDAPException - Failed to complete the requested search.

setOption

public void setOption(int option,
                      Object value)
            throws LDAPException
Sets an option that applies to the connection. The particular meaning may be implementation-dependent. The standard options are the options described by the LDAPSearchConstraints and LDAPConstraints classes.
Throws:
LDAPException - Failed to set the specified option.