com.nitido.nimx.services.dirpool.mozilla
Class DirectoryImpl

java.lang.Object
  com.nitido.nimx.services.dirpool.mozilla.DirectoryImpl

All Implemented Interfaces:

Directory

public class DirectoryImpl
extends java.lang.Object
implements Directory

This class implements the Directory interface by using the Netscape set of libraries.

Field Summary

protected DirConnection	_dirCon
protected DirPoolServiceImpl	_poolService
protected int	SCOPE_BASE
protected int	SCOPE_ONE
protected int	SCOPE_SUB

Method Summary

void	addAttributeValue(java.lang.String dn, java.lang.String name, java.io.Serializable value) Add Serializable attribute.
void	addAttributeValues(java.lang.String dn, java.lang.String name, 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.lang.String	getPoolName()
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 dn, java.lang.String name, java.io.Serializable value) Modify Serializable attribute.
void	modifyAttributeValues(java.lang.String dn, java.lang.String name, java.util.Vector values) Modify attribute (for multi value attributes).
void	modifyEntry(java.lang.String dn, DirModifier[] modifiers) Modify a specific entry with multiple changes to the attributes.
void	removeAttributeValue(java.lang.String dn, java.lang.String attribute, java.io.Serializable value) Remove a Serializable attribute value.
void	removeAttributeValues(java.lang.String dn, java.lang.String attribute) Remove all attribute value under the attribute name.
void	removeEntry(java.lang.String dn) 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.
java.util.Vector	search(java.lang.String baseDN, java.lang.String filter, java.lang.String[] attributes, long maxResult)
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.

Methods inherited from class java.lang.Object

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

Field Detail

SCOPE_SUB

protected final int SCOPE_SUB

See Also:

Constant Field Values

SCOPE_ONE

protected final int SCOPE_ONE

See Also:

Constant Field Values

SCOPE_BASE

protected final int SCOPE_BASE

See Also:

Constant Field Values

_poolService

protected final DirPoolServiceImpl _poolService

_dirCon

protected transient DirConnection _dirCon

Method Detail

connect

public void connect(java.lang.String username,
                    java.lang.String password)
             throws DirAuthenticationFailedException,
                    DirectoryException

Description copied from interface: Directory

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.

Specified by:

connect in interface Directory

Parameters:

username - The username to authenticate with to the directory.

password - The password to authenticate with to the directory.

Throws:

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.

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

public void disconnect()
                throws DirectoryException

Description copied from interface: Directory

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.

Specified by:

disconnect in interface Directory

Throws:

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error.

See Also:

com.nitido.directory

terminate

public void terminate()
               throws DirectoryException

Description copied from interface: Directory

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.

Specified by:

terminate in interface Directory

Throws:

DirReferralException - The exception for LDAP referrals.

DirectoryException - The exception for general system error.

See Also:

com.nitido.directory

bind

public void bind()
          throws DirAuthenticationFailedException,
                 DirectoryException

Description copied from interface: Directory

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.

Specified by:

bind in interface Directory

Throws:

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.

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

public void bind(java.lang.String username,
                 java.lang.String password)
          throws DirAuthenticationFailedException,
                 DirectoryException

Description copied from interface: Directory

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.

Specified by:

bind in interface Directory

Parameters:

username - The new username

password - The new password

Throws:

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.

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

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

Description copied from interface: Directory

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.

Specified by:

search in interface Directory

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

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

Description copied from interface: Directory

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.

Specified by:

search in interface Directory

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

public 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

Description copied from interface: Directory

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.

Specified by:

search in interface Directory

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

search

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

Throws:

IllegalSearchFilterException

java.lang.IllegalArgumentException

java.lang.IllegalStateException

DirReferralException

DirectoryException

getEntry

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

Description copied from interface: Directory

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.

Specified by:

getEntry in interface Directory

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

public void addEntry(Entry entry)
              throws DirectoryException

Description copied from interface: Directory

Add a new entry.

The package description contains the exception handling guide.

Specified by:

addEntry in interface Directory

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.

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

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

public void removeEntry(java.lang.String dn)
                 throws DirectoryException

Description copied from interface: Directory

Remove an entry.

The package description contains the exception handling guide.

Specified by:

removeEntry in interface Directory

Parameters:

dn - The target entry's DN.

Throws:

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

public void removeAttributeValue(java.lang.String dn,
                                 java.lang.String attribute,
                                 java.io.Serializable value)
                          throws DirectoryException

Description copied from interface: Directory

Remove a Serializable attribute value.

The package description contains the exception handling guide.

Specified by:

removeAttributeValue in interface Directory

Parameters:

dn - 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:

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

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

modifyAttributeValue

public void modifyAttributeValue(java.lang.String dn,
                                 java.lang.String name,
                                 java.io.Serializable value)
                          throws DirectoryException

Description copied from interface: Directory

Modify Serializable attribute.

The package description contains the exception handling guide.

Specified by:

modifyAttributeValue in interface Directory

Parameters:

dn - The target entry's DN.

name - The name of the attribute.

value - the attribute value to be compared.

Throws:

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.

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

public void addAttributeValue(java.lang.String dn,
                              java.lang.String name,
                              java.io.Serializable value)
                       throws DirectoryException

Description copied from interface: Directory

Add Serializable attribute.

The package description contains the exception handling guide.

Specified by:

addAttributeValue in interface Directory

Parameters:

dn - The target entry's DN.

name - The name of the attribute.

value - the attribute value to be compared.

Throws:

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

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

public void removeAttributeValues(java.lang.String dn,
                                  java.lang.String attribute)
                           throws DirectoryException

Description copied from interface: Directory

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

The package description contains the exception handling guide.

Specified by:

removeAttributeValues in interface Directory

Parameters:

dn - The target entry's DN.

attribute - The name of the attribute.

Throws:

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

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

public void modifyAttributeValues(java.lang.String dn,
                                  java.lang.String name,
                                  java.util.Vector values)
                           throws DirectoryException

Description copied from interface: Directory

Modify attribute (for multi value attributes).

The package description contains the exception handling guide.

Specified by:

modifyAttributeValues in interface Directory

Parameters:

dn - The target entry's DN.

name - 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:

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

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

public void modifyEntry(java.lang.String dn,
                        DirModifier[] modifiers)
                 throws DirectoryException

Description copied from interface: Directory

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.

Specified by:

modifyEntry in interface Directory

Parameters:

dn - The target entry's DN.

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

Throws:

DirectoryException

addAttributeValues

public void addAttributeValues(java.lang.String dn,
                               java.lang.String name,
                               java.util.Vector values)
                        throws DirectoryException

Description copied from interface: Directory

Add attribute (for multi value attributes).

The package description contains the exception handling guide.

Specified by:

addAttributeValues in interface Directory

Parameters:

dn - The target entry's DN.

name - 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:

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

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

setScope

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

Description copied from interface: Directory

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.

Specified by:

setScope in interface Directory

Parameters:

scope - The new scope for search.

Throws:

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

setBase

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

Description copied from interface: Directory

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.

Specified by:

setBase in interface Directory

Parameters:

base - the new base DN.

Throws:

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

getScopeSUB

public int getScopeSUB()

Description copied from interface: Directory

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

Specified by:

getScopeSUB in interface Directory

Returns:

the int scope for SUB.

getScopeONE

public int getScopeONE()

Description copied from interface: Directory

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

Specified by:

getScopeONE in interface Directory

Returns:

the int scope for BASE.

getScopeBASE

public int getScopeBASE()

Description copied from interface: Directory

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

Specified by:

getScopeBASE in interface Directory

Returns:

the int scope for BASE.

getBase

public java.lang.String getBase()

Description copied from interface: Directory

Get Base DN.

Specified by:

getBase in interface Directory

Returns:

the base DN string.

getScope

public int getScope()

Description copied from interface: Directory

Get Scope.

Specified by:

getScope in interface Directory

Returns:

scope string.

getUserName

public java.lang.String getUserName()

Description copied from interface: Directory

Get User Name.

Specified by:

getUserName in interface Directory

Returns:

the user name.

getPoolName

public java.lang.String getPoolName()

getRoots

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

Description copied from interface: Directory

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.

Specified by:

getRoots in interface Directory

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

isConnected

public boolean isConnected()

Description copied from interface: Directory

Check whether the connection is connected.

Specified by:

isConnected in interface Directory

Returns:

true if the backend connection has been established.