netscape.ldap

Interface LDAPv2

All Known Subinterfaces:

LDAPv3

All 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

Fields

Modifier and Type	Field and Description
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

Modifier and Type	Method and Description
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(java.lang.String DN, java.lang.String passwd) Authenticates user with the LDAP server.
void	bind(java.lang.String DN, java.lang.String passwd) Authenticates user with the LDAP server.
boolean	compare(java.lang.String DN, LDAPAttribute attr) Compares the given entry's attribute value to the specified attribute value.
boolean	compare(java.lang.String DN, LDAPAttribute attr, LDAPConstraints cons) Compares the given entry's attribute value to the specified attribute value.
void	connect(java.lang.String host, int port) Connects to the LDAP server.
void	connect(java.lang.String host, int port, java.lang.String dn, java.lang.String passwd) Connects and authenticates to the LDAP server.
void	delete(java.lang.String DN) Removes an entry from the directory.
void	delete(java.lang.String DN, LDAPConstraints cons) Removes an entry from the directory.
void	disconnect() Disconnects from the LDAP server.
java.lang.Object	getOption(int option) Retrieves an option that applies to the connection.
void	modify(java.lang.String DN, LDAPModification mod) Modifies an attribute of a directory entry.
void	modify(java.lang.String DN, LDAPModification mod, LDAPConstraints cons) Modifies an attribute of a directory entry.
void	modify(java.lang.String DN, LDAPModificationSet mods) Modifies the attributes of a directory entry.
void	modify(java.lang.String DN, LDAPModificationSet mods, LDAPConstraints cons) Modifies the attributes of a directory entry.
LDAPEntry	read(java.lang.String DN) Read the entry corresponding to the specified distinguished name (DN).
LDAPEntry	read(java.lang.String DN, java.lang.String[] attrs) Read the entry corresponding to the specified distinguished name (DN), and retrieve only the specified attributes.
LDAPEntry	read(java.lang.String DN, java.lang.String[] attrs, LDAPSearchConstraints cons) Read the entry corresponding to the specified distinguished name (DN), and retrieve only the specified attributes.
void	rename(java.lang.String DN, java.lang.String newRDN, boolean deleteOldRDN) Changes the name of an entry in the directory.
void	rename(java.lang.String DN, java.lang.String newRDN, boolean deleteOldRDN, LDAPConstraints cons) Changes the name of an entry in the directory.
LDAPSearchResults	search(java.lang.String base, int scope, java.lang.String filter, java.lang.String[] attrs, boolean attrsOnly) Searches for entries in the directory.
LDAPSearchResults	search(java.lang.String base, int scope, java.lang.String filter, java.lang.String[] attrs, boolean attrsOnly, LDAPSearchConstraints cons) Searches for entries in the directory.
void	setOption(int option, java.lang.Object value) Sets an option that applies to the connection.

Field Detail

DEFAULT_PORT

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.

See Also:

LDAPConnection.connect(java.lang.String, int), Constant Field Values

DEREF

static final int DEREF

Option specifying how aliases are dereferenced.

This option can have one of the following values:

• DEREF_NEVER
• DEREF_FINDING
• DEREF_SEARCHING
• DEREF_ALWAYS

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

SIZELIMIT

static final int SIZELIMIT

Option specifying the maximum number of search results to return.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

TIMELIMIT

static final int TIMELIMIT

Option specifying the maximum number of milliseconds to wait for an operation to complete.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

SERVER_TIMELIMIT

static final int SERVER_TIMELIMIT

Option specifying the maximum number of milliseconds the server should spend returning search results before aborting the search.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

REFERRALS

static final int REFERRALS

Option specifying whether or not referrals to other LDAP servers are followed automatically.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), LDAPRebind, LDAPRebindAuth, Constant Field Values

REFERRALS_REBIND_PROC

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.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), LDAPRebind, LDAPRebindAuth, Constant Field Values

REFERRALS_HOP_LIMIT

static final int REFERRALS_HOP_LIMIT

Option specifying the maximum number of referrals to follow in a sequence when requesting an LDAP operation.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

BIND

static final int BIND

Option specifying the object containing the method for authenticating to the server.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), LDAPBind, Constant Field Values

PROTOCOL_VERSION

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.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), LDAPConnection.authenticate(int, java.lang.String, java.lang.String), Constant Field Values

BATCHSIZE

static final int BATCHSIZE

Option specifying the number of results to return at a time.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

SCOPE_BASE

static final int SCOPE_BASE

Specifies that the scope of a search includes only the base DN (distinguished name).

See Also:

LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints), Constant Field Values

SCOPE_ONE

static final int SCOPE_ONE

Specifies that the scope of a search includes only the entries one level below the base DN (distinguished name).

See Also:

LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints), Constant Field Values

SCOPE_SUB

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.

See Also:

LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints), Constant Field Values

DEREF_NEVER

static final int DEREF_NEVER

Specifies that aliases are never dereferenced.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

DEREF_SEARCHING

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).

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

DEREF_FINDING

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).

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

DEREF_ALWAYS

static final int DEREF_ALWAYS

Specifies that aliases are always dereferenced.

See Also:

LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), Constant Field Values

Method Detail

connect

void connect(java.lang.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

void connect(java.lang.String host,
             int port,
             java.lang.String dn,
             java.lang.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.

disconnect

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.

abandon

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.

authenticate

void authenticate(java.lang.String DN,
                  java.lang.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

void bind(java.lang.String DN,
          java.lang.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.

read

LDAPEntry read(java.lang.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

LDAPEntry read(java.lang.String DN,
               java.lang.String[] 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

attrs - names of attributes to retrieve

Throws:

LDAPException - Failed to retrieve the specified entry.

read

LDAPEntry read(java.lang.String DN,
               java.lang.String[] 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

attrs - names of attributes to retrieve

cons - the constraints set for the read operation

Throws:

LDAPException - Failed to retrieve the specified entry.

search

LDAPSearchResults search(java.lang.String base,
                         int scope,
                         java.lang.String filter,
                         java.lang.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

LDAPSearchResults search(java.lang.String base,
                         int scope,
                         java.lang.String filter,
                         java.lang.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.

compare

boolean compare(java.lang.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

boolean compare(java.lang.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.

add

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

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.

modify

void modify(java.lang.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

void modify(java.lang.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

void modify(java.lang.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

void modify(java.lang.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.

delete

void delete(java.lang.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

void delete(java.lang.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.

rename

void rename(java.lang.String DN,
            java.lang.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

void rename(java.lang.String DN,
            java.lang.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.

getOption

java.lang.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.

setOption

void setOption(int option,
               java.lang.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.