Package com.nitido.directory

The Nitido directory library - with exception handling instruction in the detail package description.

See:
Description

Interface Summary

Directory	The Directory base class encapsulates the access of an LDAP compliant directory server.
DirectoryFactory	The DirectoryFactory base class defines the Factories that create the implementors of the Directory interface.

Class Summary

DirectoryUtil	This class contains the utility methods for directory operation, such as converting special characters in LDAP DN and LDAP Filters.
DirModifier	The DirModifier class contains the details of a directory attribute that is going to be modified.
Entry	The Entry class is used to encapsulate a directory entry.

Exception Summary

DirAuthenticationFailedException	The DirAuthenticationFailedException class is used in general to indicated a failed authentication attempt.
DirectoryException	The DirectoryException class is the generic exception thrown by this library.
DirEntryAlreadyExistsException
DirReferralException
DirSchemaViolationException
IllegalEntryDNException
IllegalSearchFilterException

Package com.nitido.directory Description

The Nitido directory library - with exception handling instruction in the detail package description.

Exception Handling

The exceptions thrown by this package can be grouped into two categories: runtime exceptions and non-runtime exceptions. In general, runtime exceptions in this package are designed for scenarios that should have been catched at development time or rarely occur. The non-runtime exceptions are situations that must be catched and handled by the application code.

Let's consider calling Directory.modifyAttributeValue(). An incorrect entry DN name will causes a runtime exception "IllegalEntryDNException" to be thrown. It is because the application developer should have already checked the entry name during development. (i.e. he/she should already know the correct entry DN because it should have searched for it earlier. This exception usually occurs when the specific entry has been deleted by somebody else at the same time.) On the other hand, if the attribute value does not matches the type/range in the LDAP, the method will throw a non-runtime exception "DirSchemaViolationException".

All runtime exceptions inherits from java.lang.RuntimException. Therefore, the application code does not need to catch them if the developer decided the exceptions doesn't need special handling.

All non-runtime exceptions inherits from DirectoryException. If you are not interested in handling them separately, you can encapsulate the method call with a try block that catches the DirectoryException only. However, if you decided to handle one of the special exception, you should catch it before catching the DirectoryException. For example,

try {
    Directory dir = 
        DirectoryFactoryImpl.createDirectory( ... ); // some params
    dir.modifyAttributeValues
} catch( DirSchemaViolationException {
    // your code that handles DirSchemaViolationException
} catch( DirectoryException {
    // your code that handles DirectoryException
}

This architecture can be best demonstrated with the following inheritence tree, where the bolded ones are thrown in this package:

• java.lang.Object
  • java.lang.Throwable (implements java.io.Serializable)
    • java.lang.Exception
      • com.nitido.directory.DirectoryException
        • com.nitido.directory.DirEntryAlreadyExistsException
        • com.nitido.directory.DirReferralException
        • com.nitido.directory.DirSchemaViolationException
      • java.lang.RuntimeException
        • java.lang.IllegalArgumentException
          • com.nitido.directory.IllegalEntryDNException
          • com.nitido.directory.IllegalSearchFilterException
        • java.lang.IllegalStateException