com.nitido.directory
Interface Directory

All Known Implementing Classes:

DirectoryImpl, DirectoryImpl

public interface Directory

The Directory base class encapsulates the access of an LDAP compliant directory server. An implementation returned by a factory is necessary to create an instance of an extender of this object.

See Also:

com.nitido.directory

Method Summary

void	addAttributeValue(java.lang.String entryDN, java.lang.String attribute, java.io.Serializable value) Add Serializable attribute.
void	addAttributeValues(java.lang.String entryDN, java.lang.String attribute, java.util.Vector values) Add attribute (for multi value attributes).
void	addEntry(Entry entry) Add a new entry.
void	bind() Rebinding to the directory service with the same username and password.
void	bind(java.lang.String username, java.lang.String password) Rebinding to the directory service with new username and password.
void	connect(java.lang.String username, java.lang.String password) Create the connection to the directory server.
void	disconnect() Disconnect the connection to the directory server.
java.lang.String	getBase() Get Base DN.
Entry	getEntry(java.lang.String entryDN, java.lang.String[] attributes) Get an Entry with the specified attributes.
java.util.Enumeration	getRoots() Get the roots.
int	getScope() Get Scope.
int	getScopeBASE() Get value of constant BASE.
int	getScopeONE() Get value of constant ONE.
int	getScopeSUB() Get value of constant SUB.
java.lang.String	getUserName() Get User Name.
boolean	isConnected() Check whether the connection is connected.
void	modifyAttributeValue(java.lang.String entryDN, java.lang.String attribute, java.io.Serializable value) Modify Serializable attribute.
void	modifyAttributeValues(java.lang.String entryDN, java.lang.String attribute, java.util.Vector values) Modify attribute (for multi value attributes).
void	modifyEntry(java.lang.String entryDN, DirModifier[] modifiers) Modify a specific entry with multiple changes to the attributes.
void	removeAttributeValue(java.lang.String entryDN, java.lang.String attribute, java.io.Serializable value) Remove a Serializable attribute value.
void	removeAttributeValues(java.lang.String entryDN, java.lang.String attribute) Remove all attribute value under the attribute name.
void	removeEntry(java.lang.String entryDN) Remove an entry.
java.util.Vector	search(java.lang.String filter) Search with the specific filter.
java.util.Vector	search(java.lang.String filter, java.lang.String[] attributes) Search with the specific filter and return the specific attributes.
java.util.Vector	search(java.lang.String base, java.lang.String filter, java.lang.String[] attributes) Search with the specific filter and return the specific attributes.
void	setBase(java.lang.String base) Set the base DN for the directory access.
void	setScope(int scope) Set the scope.
void	terminate() This method not only disconnect the underlying connection, but also removing the connection from any potential connection pool completely.

Method Detail

connect

void connect(java.lang.String username,
             java.lang.String password)
             throws java.lang.IllegalArgumentException,
                    DirAuthenticationFailedException,
                    java.lang.IllegalStateException,
                    DirReferralException,
                    DirectoryException

Create the connection to the directory server. This method is also responsible for binding the user to the system.

The package description contains the exception handling guide.

Parameters:

username - The username to authenticate with to the directory.

password - The password to authenticate with to the directory.

Throws:

java.lang.IllegalArgumentException - This runtime exception is thrown if the parameters (username and password) or the underlying settings (host and port) are illegal or invalid.

DirAuthenticationFailedException - This exception is thrown if the authorization fails. This problem may be caused by invalid username/password/base/scope. Since this exception inherit from DirectoryException, you don't need to catch it explicitly. However, if you want to catch it, you should catch it before catching DirectoryException.

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (For example, the directory has been connected already)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

disconnect

void disconnect()
                throws DirReferralException,
                       DirectoryException

Disconnect the connection to the directory server. Once this method has been completed successfully, no more LDAP operation is allowed. The caller must invoke connect() again if it needs to perform additional operations.

If the directory has already been disconnected, this method would not throw any exception (i.e. just return without doing anything). This method will never throw IllegalArgumentException or IllegalStateException.

The package description contains the exception handling guide.

Throws:

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error.

See Also:

com.nitido.directory

terminate

void terminate()
               throws DirReferralException,
                      DirectoryException

This method not only disconnect the underlying connection, but also removing the connection from any potential connection pool completely. If you call disconnect() method, the underlying connection may still be reused if the connection pool is used. However, with terminate() method, the physical connection will be terminated and discarded.

This method is mainly used to help releasing connection that the application noticed there is some problem. It is also good for handling errors from the backend server that fails to reset the connection after a major error (or the backend server drops a connection when they don't really need to).

Once this method has been completed successfully, no more LDAP operation is allowed. The caller must invoke connect() again if it needs to perform additional operations.

If the directory has already been disconnected, this method would not throw any exception (i.e. just return without doing anything). This method will never throw IllegalArgumentException or IllegalStateException.

The package description contains the exception handling guide.

Throws:

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error.

See Also:

com.nitido.directory

bind

void bind()
          throws java.lang.IllegalArgumentException,
                 DirAuthenticationFailedException,
                 java.lang.IllegalStateException,
                 DirReferralException,
                 DirectoryException

Rebinding to the directory service with the same username and password. This methods actually calls disconnect() and then connect() with the original username and password.

The package description contains the exception handling guide.

Throws:

java.lang.IllegalArgumentException - This runtime exception is thrown if the parameters (username and password) or the underlying settings (host and port) are illegal or invalid.

DirAuthenticationFailedException - This exception is thrown if the authorization fails. This problem may be caused by invalid username/password/base/scope. Since this exception inherit from DirectoryException, you don't need to catch it explicitly. However, if you want to catch it, you should catch it before catching DirectoryException.

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state.

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

bind

void bind(java.lang.String username,
          java.lang.String password)
          throws java.lang.IllegalArgumentException,
                 DirAuthenticationFailedException,
                 java.lang.IllegalStateException,
                 DirReferralException,
                 DirectoryException

Rebinding to the directory service with new username and password. This methods actually calls disconnect() and then connect() with the new username and password.

The package description contains the exception handling guide.

Parameters:

username - The new username

password - The new password

Throws:

java.lang.IllegalArgumentException - This runtime exception is thrown if the parameters (username and password) or the underlying settings (host and port) are illegal or invalid.

DirAuthenticationFailedException - This exception is thrown if the authorization fails. This problem may be caused by invalid username/password/base/scope. Since this exception inherit from DirectoryException, you don't need to catch it explicitly. However, if you want to catch it, you should catch it before catching DirectoryException.

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state.

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

search

java.util.Vector search(java.lang.String filter)
                        throws IllegalSearchFilterException,
                               java.lang.IllegalArgumentException,
                               java.lang.IllegalStateException,
                               DirReferralException,
                               DirectoryException

Search with the specific filter. The list of attributes of the result will depend on the directory service setting. (For most cases, it returns all attributes.)

The developer should have invoked the setBase() method before invoking this method. If this is not the case, this method will throw an IllegalStateException. The developer should invoke the other search() methods that takes the base DN as the parameter.

The package description contains the exception handling guide.

Parameters:

filter - the filter string, e.g. "(name=*)".

Returns:

a vector of Entry objects.

Throws:

IllegalSearchFilterException - This runtime exception is thrown if the search filter is invalid or illegal. (e.g. the filter doesn't have the closing bracket.) Note: This exception inherits from java.lang.IllegalArgumentException.

java.lang.IllegalArgumentException - This runtime exception is thrown if this object has an invalid or illegal base (which can be changed by the method setScope( String ) ).

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

search

java.util.Vector search(java.lang.String filter,
                        java.lang.String[] attributes)
                        throws IllegalSearchFilterException,
                               java.lang.IllegalArgumentException,
                               java.lang.IllegalStateException,
                               DirReferralException,
                               DirectoryException

Search with the specific filter and return the specific attributes. Before the search, one should call the setScope to correctly set the scope of the search.

Even if the attribute list contains invalid attribute names, this method will not throw any exception. Those bad attribute names are simply ignored.

The developer should have invoked the setBase() method before invoking this method. If this is not the case, this method will throw an IllegalStateException. The developer should invoke the other search() methods that takes the base DN as the parameter.

The package description contains the exception handling guide.

Parameters:

filter - the filter string, e.g. "name=*".

attributes - The names of the attributes you want to fetch.

Returns:

a vector of Entry objects.

Throws:

IllegalSearchFilterException - This runtime exception is thrown if the search filter is invalid or illegal. (e.g. the filter doesn't have the closing bracket.) Note: This exception inherits from java.lang.IllegalArgumentException.

java.lang.IllegalArgumentException - This runtime exception is thrown if this object has an invalid or illegal base (which can be changed by the method setScope( String ) ).

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

search

java.util.Vector search(java.lang.String base,
                        java.lang.String filter,
                        java.lang.String[] attributes)
                        throws IllegalSearchFilterException,
                               java.lang.IllegalArgumentException,
                               java.lang.IllegalStateException,
                               DirReferralException,
                               DirectoryException

Search with the specific filter and return the specific attributes. Before the search, one should call the setScope to correctly set the scope of the search.

Even if the attribute list contains invalid attribute names, this method will not throw any exception. Those bad attribute names are simply ignored.

The package description contains the exception handling guide.

Parameters:

base - the base DN for the search.

filter - the filter string, e.g. "name=*".

attributes - The names of the attributes you want to fetch.

Returns:

a vector of Entry objects.

Throws:

IllegalSearchFilterException - This runtime exception is thrown if the search filter is invalid or illegal. (e.g. the filter doesn't have the closing bracket.) Note: This exception inherits from java.lang.IllegalArgumentException.

java.lang.IllegalArgumentException - This runtime exception is thrown if the parameter "base" is invalid.

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

getEntry

Entry getEntry(java.lang.String entryDN,
               java.lang.String[] attributes)
               throws IllegalEntryDNException,
                      java.lang.IllegalStateException,
                      DirReferralException,
                      DirectoryException

Get an Entry with the specified attributes.

Even if the attribute list contains invalid attribute names, this method will not throw any exception. Those bad attribute names are simply ignored.

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

attributes - The names of the attributes you want to fetch. If it is null, it returns all attributes of the entry.

Returns:

An entry object that contains the requested attributes.

Throws:

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent/node doesn't exists or has syntax error.) Note: This exception inherits from java.lang.IllegalArgumentException.

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

addEntry

void addEntry(Entry entry)
              throws DirEntryAlreadyExistsException,
                     IllegalEntryDNException,
                     DirSchemaViolationException,
                     java.lang.IllegalStateException,
                     DirReferralException,
                     DirectoryException

Add a new entry.

The package description contains the exception handling guide.

Parameters:

entry - The new entry being added to the directory.

Throws:

DirEntryAlreadyExistsException - This exception is thrown if the new entry already exists in the backend directory.

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent doesn't exists or has syntax error) Note: This exception inherits from java.lang.IllegalArgumentException.

DirSchemaViolationException - This exception is thrown if the modification violates the schema, such as missing required attribute, incorrect attribute value type, or failed to satisfy the attribute value constraint (e.g. adding multi-values to a single-value attribute).

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

removeEntry

void removeEntry(java.lang.String entryDN)
                 throws IllegalEntryDNException,
                        java.lang.IllegalStateException,
                        DirReferralException,
                        DirectoryException

Remove an entry.

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

Throws:

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent doesn't exists or has syntax error) Note: This exception inherits from java.lang.IllegalArgumentException

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems. This exception can be also thrown if the server cannot remove the entry due to schema or LDAP constraint (e.g. can't remove a non-leaf node).

See Also:

com.nitido.directory

removeAttributeValue

void removeAttributeValue(java.lang.String entryDN,
                          java.lang.String attribute,
                          java.io.Serializable value)
                          throws IllegalEntryDNException,
                                 DirSchemaViolationException,
                                 java.lang.IllegalStateException,
                                 DirReferralException,
                                 DirectoryException

Remove a Serializable attribute value.

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

attribute - The name of the attribute.

value - The value of the attribute to be removed. This parameter is mainly used by multi-valued attribute and thus, it is optional. If the caller pass null and the attribute is multivalued, all values of the attribute will be removed.

Throws:

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent doesn't exists or has syntax error) Note: This exception inherits from java.lang.IllegalArgumentException.

DirSchemaViolationException - This exception is thrown if the modification violates the schema, such as removing a required attribute.

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

modifyEntry

void modifyEntry(java.lang.String entryDN,
                 DirModifier[] modifiers)
                 throws IllegalEntryDNException,
                        DirSchemaViolationException,
                        java.lang.IllegalStateException,
                        DirReferralException,
                        DirectoryException

Modify a specific entry with multiple changes to the attributes.

Unlike the other attribute modification methods, this method is responsible for updating multiple attributes of the same entry at the same time (instead of one-by-one). This method should be used whenever you need to modify more than one attribute in order to improve the performance.

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

modifiers - An array of DirModifier that describes the actions and the attributes to be modified.

Throws:

IllegalEntryDNException

DirSchemaViolationException

java.lang.IllegalStateException

DirReferralException

DirectoryException

modifyAttributeValue

void modifyAttributeValue(java.lang.String entryDN,
                          java.lang.String attribute,
                          java.io.Serializable value)
                          throws IllegalEntryDNException,
                                 DirSchemaViolationException,
                                 java.lang.IllegalStateException,
                                 DirReferralException,
                                 DirectoryException

Modify Serializable attribute.

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

attribute - The name of the attribute.

value - the attribute value to be compared.

Throws:

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent doesn't exists or has syntax error) Note: This exception inherits from java.lang.IllegalArgumentException.

DirSchemaViolationException - This exception is thrown if the modification violates the schema, such as missing required attribute, incorrect attribute value type, or failed to satisfy the attribute value constraint.

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

addAttributeValue

void addAttributeValue(java.lang.String entryDN,
                       java.lang.String attribute,
                       java.io.Serializable value)
                       throws IllegalEntryDNException,
                              DirSchemaViolationException,
                              java.lang.IllegalStateException,
                              DirReferralException,
                              DirectoryException

Add Serializable attribute.

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

attribute - The name of the attribute.

value - the attribute value to be compared.

Throws:

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent doesn't exists or has syntax error) Note: This exception inherits from java.lang.IllegalArgumentException.

DirSchemaViolationException - This exception is thrown if the modification violates the schema, such as missing required attribute, incorrect attribute value type, or failed to satisfy the attribute value constraint (e.g. adding multi-values to a single-value attribute).

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

removeAttributeValues

void removeAttributeValues(java.lang.String entryDN,
                           java.lang.String attribute)
                           throws IllegalEntryDNException,
                                  DirSchemaViolationException,
                                  java.lang.IllegalStateException,
                                  DirReferralException,
                                  DirectoryException

Remove all attribute value under the attribute name. (i.e. remove the whole attribute)

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

attribute - The name of the attribute.

Throws:

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent doesn't exists or has syntax error) Note: This exception inherits from java.lang.IllegalArgumentException.

DirSchemaViolationException - This exception is thrown if the modification violates the schema, such as removing a required attribute.

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

modifyAttributeValues

void modifyAttributeValues(java.lang.String entryDN,
                           java.lang.String attribute,
                           java.util.Vector values)
                           throws IllegalEntryDNException,
                                  DirSchemaViolationException,
                                  java.lang.IllegalStateException,
                                  DirReferralException,
                                  DirectoryException

Modify attribute (for multi value attributes).

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

attribute - The name of the attribute.

values - the attribute values to be modify. It can be either a vector of string or a vector of serializable. (It determines the vector type by the first element of the vector.)

Throws:

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent doesn't exists or has syntax error) Note: This exception inherits from java.lang.IllegalArgumentException.

DirSchemaViolationException - This exception is thrown if the modification violates the schema, such as missing required attribute, incorrect attribute value type, or failed to satisfy the attribute value constraint (e.g. adding multi-values to a single-value attribute).

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

addAttributeValues

void addAttributeValues(java.lang.String entryDN,
                        java.lang.String attribute,
                        java.util.Vector values)
                        throws IllegalEntryDNException,
                               DirSchemaViolationException,
                               java.lang.IllegalStateException,
                               DirReferralException,
                               DirectoryException

Add attribute (for multi value attributes).

The package description contains the exception handling guide.

Parameters:

entryDN - The target entry's DN.

attribute - The name of the attribute.

values - the attribute values to be add. It can be either a vector of string or a vector of serializable. (It determines the vector type by the first element of the vector.)

Throws:

IllegalEntryDNException - This runtime exception is thrown if the specified entryDN is illegal. (e.g. null, parent doesn't exists or has syntax error.) Note: This exception inherits from java.lang.IllegalArgumentException.

DirSchemaViolationException - This exception is thrown if the modification violates the schema, such as missing required attribute, incorrect attribute value type, or failed to satisfy the attribute value constraint (e.g. adding multi-values to a single-value attribute).

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory

setBase

void setBase(java.lang.String base)
             throws java.lang.IllegalArgumentException

Set the base DN for the directory access. This method does not involves any binding or immediate LDAP access. It only changes default base DN for subsequent searches. It can be invoked at any state of this object.

Parameters:

base - the new base DN.

Throws:

java.lang.IllegalArgumentException - This exception is thrown if the parameter is null.

setScope

void setScope(int scope)
              throws java.lang.IllegalArgumentException

Set the scope. This method does not involves any binding or immediate LDAP access. It only changes default base DN for subsequent searches. It can be invoked at any state of this object.

Parameters:

scope - The new scope for search.

Throws:

java.lang.IllegalArgumentException - This exception is thrown if the parameter is not supported.

getScopeSUB

int getScopeSUB()

Get value of constant SUB. This allow the application to set the scope constant value without worrying about which implementation is actually used.

Returns:

the int scope for SUB.

getScopeBASE

int getScopeBASE()

Get value of constant BASE. This allow the application to set the scope constant value without worrying about which implementation is actually used.

Returns:

the int scope for BASE.

getScopeONE

int getScopeONE()

Get value of constant ONE. This allow the application to set the scope constant value without worrying about which implementation is actually used.

Returns:

the int scope for BASE.

getBase

java.lang.String getBase()

Get Base DN.

Returns:

the base DN string.

getUserName

java.lang.String getUserName()

Get User Name.

Returns:

the user name.

getScope

int getScope()

Get Scope.

Returns:

scope string.

isConnected

boolean isConnected()

Check whether the connection is connected.

Returns:

true if the backend connection has been established.

getRoots

java.util.Enumeration getRoots()
                               throws java.lang.IllegalStateException,
                                      DirReferralException,
                                      DirectoryException

Get the roots. This method may need to talk to the backend directory server to get the strings for the roots.

The package description contains the exception handling guide.

Returns:

an enumeration of string that represents the roots.

Throws:

java.lang.IllegalStateException - This runtime exception is thrown if this object is in illegal state. (i.e. it has not been connected.)

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error, including network failures, protocol errors and naming problems.

See Also:

com.nitido.directory