com.unboundid.ldap.sdk
Class LDAPException

java.lang.Object
  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by com.unboundid.util.LDAPSDKException
              extended by com.unboundid.ldap.sdk.LDAPException
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
LDAPBindException, LDAPExtendedOperationException, LDAPPersistException, LDAPSearchException

@NotExtensible
@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public class LDAPException
extends LDAPSDKException

This class defines an exception that can be thrown if a problem occurs while performing LDAP-related processing. An LDAP exception can include all of the elements of an LDAPResult, so that all of the response elements will be available.

See Also:
Serialized Form

Field Summary
protected static Control[] NO_CONTROLS
          An empty array that will be used when no controls were provided.
protected static java.lang.String[] NO_REFERRALS
          An empty array that will be used when no referrals were provided.
 
Constructor Summary
LDAPException(LDAPException e)
          Creates a new LDAP exception using the information contained in the provided LDAP exception.
LDAPException(LDAPResult ldapResult)
          Creates a new LDAP exception using the information contained in the provided LDAP result object.
LDAPException(LDAPResult ldapResult, java.lang.Throwable cause)
          Creates a new LDAP exception using the information contained in the provided LDAP result object.
LDAPException(ResultCode resultCode)
          Creates a new LDAP exception with the provided result code.
LDAPException(ResultCode resultCode, java.lang.String errorMessage)
          Creates a new LDAP exception with the provided result code and message.
LDAPException(ResultCode resultCode, java.lang.String errorMessage, java.lang.String matchedDN, java.lang.String[] referralURLs)
          Creates a new LDAP exception with the provided information.
LDAPException(ResultCode resultCode, java.lang.String errorMessage, java.lang.String matchedDN, java.lang.String[] referralURLs, Control[] controls)
          Creates a new LDAP exception with the provided information.
LDAPException(ResultCode resultCode, java.lang.String errorMessage, java.lang.String matchedDN, java.lang.String[] referralURLs, Control[] controls, java.lang.Throwable cause)
          Creates a new LDAP exception with the provided information.
LDAPException(ResultCode resultCode, java.lang.String errorMessage, java.lang.String matchedDN, java.lang.String[] referralURLs, java.lang.Throwable cause)
          Creates a new LDAP exception with the provided information.
LDAPException(ResultCode resultCode, java.lang.String errorMessage, java.lang.Throwable cause)
          Creates a new LDAP exception with the provided result code and message.
LDAPException(ResultCode resultCode, java.lang.Throwable cause)
          Creates a new LDAP exception with the provided result code.
 
Method Summary
 java.lang.String getDiagnosticMessage()
          Retrieves the diagnostic message returned by the directory server.
 java.lang.String getExceptionMessage()
          Retrieves a string representation of this exception suitable for use in messages.
 java.lang.String getMatchedDN()
          Retrieves the matched DN for this LDAP exception.
 java.lang.String[] getReferralURLs()
          Retrieves the set of referral URLs for this LDAP exception.
 Control getResponseControl(java.lang.String oid)
          Retrieves the response control with the specified OID.
 Control[] getResponseControls()
          Retrieves the set of response controls for this LDAP exception.
 ResultCode getResultCode()
          Retrieves the result code for this LDAP exception.
 java.lang.String getResultString()
          Retrieves a string representation of this LDAP result, consisting of the result code, diagnostic message (if present), matched DN (if present), and referral URLs (if present).
 boolean hasResponseControl()
          Indicates whether this result contains at least one control.
 boolean hasResponseControl(java.lang.String oid)
          Indicates whether this result contains at least one control with the specified OID.
 LDAPResult toLDAPResult()
          Creates a new LDAPResult object from this exception.
 void toString(java.lang.StringBuilder buffer)
          Appends a string representation of this exception to the provided buffer.
 
Methods inherited from class com.unboundid.util.LDAPSDKException
toString
 
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

NO_CONTROLS

protected static final Control[] NO_CONTROLS
An empty array that will be used when no controls were provided.


NO_REFERRALS

protected static final java.lang.String[] NO_REFERRALS
An empty array that will be used when no referrals were provided.

Constructor Detail

LDAPException

public LDAPException(ResultCode resultCode)
Creates a new LDAP exception with the provided result code. A default message (based on the result code) will be used.

Parameters:
resultCode - The result code for this LDAP exception.

LDAPException

public LDAPException(ResultCode resultCode,
                     java.lang.Throwable cause)
Creates a new LDAP exception with the provided result code. A default message (based on the result code) will be used.

Parameters:
resultCode - The result code for this LDAP exception.
cause - The underlying exception that triggered this exception.

LDAPException

public LDAPException(ResultCode resultCode,
                     java.lang.String errorMessage)
Creates a new LDAP exception with the provided result code and message.

Parameters:
resultCode - The result code for this LDAP exception.
errorMessage - The error message for this LDAP exception.

LDAPException

public LDAPException(ResultCode resultCode,
                     java.lang.String errorMessage,
                     java.lang.Throwable cause)
Creates a new LDAP exception with the provided result code and message.

Parameters:
resultCode - The result code for this LDAP exception.
errorMessage - The error message for this LDAP exception.
cause - The underlying exception that triggered this exception.

LDAPException

public LDAPException(ResultCode resultCode,
                     java.lang.String errorMessage,
                     java.lang.String matchedDN,
                     java.lang.String[] referralURLs)
Creates a new LDAP exception with the provided information.

Parameters:
resultCode - The result code for this LDAP exception.
errorMessage - The error message for this LDAP exception.
matchedDN - The matched DN for this LDAP exception.
referralURLs - The set of referral URLs for this LDAP exception.

LDAPException

public LDAPException(ResultCode resultCode,
                     java.lang.String errorMessage,
                     java.lang.String matchedDN,
                     java.lang.String[] referralURLs,
                     java.lang.Throwable cause)
Creates a new LDAP exception with the provided information.

Parameters:
resultCode - The result code for this LDAP exception.
errorMessage - The error message for this LDAP exception.
matchedDN - The matched DN for this LDAP exception.
referralURLs - The set of referral URLs for this LDAP exception.
cause - The underlying exception that triggered this exception.

LDAPException

public LDAPException(ResultCode resultCode,
                     java.lang.String errorMessage,
                     java.lang.String matchedDN,
                     java.lang.String[] referralURLs,
                     Control[] controls)
Creates a new LDAP exception with the provided information.

Parameters:
resultCode - The result code for this LDAP exception.
errorMessage - The error message for this LDAP exception.
matchedDN - The matched DN for this LDAP exception.
referralURLs - The set of referral URLs for this LDAP exception.
controls - The set of response controls for this LDAP exception.

LDAPException

public LDAPException(ResultCode resultCode,
                     java.lang.String errorMessage,
                     java.lang.String matchedDN,
                     java.lang.String[] referralURLs,
                     Control[] controls,
                     java.lang.Throwable cause)
Creates a new LDAP exception with the provided information.

Parameters:
resultCode - The result code for this LDAP exception.
errorMessage - The error message for this LDAP exception.
matchedDN - The matched DN for this LDAP exception.
referralURLs - The set of referral URLs for this LDAP exception.
controls - The set of response controls for this LDAP exception.
cause - The underlying exception that triggered this exception.

LDAPException

public LDAPException(LDAPResult ldapResult)
Creates a new LDAP exception using the information contained in the provided LDAP result object.

Parameters:
ldapResult - The LDAP result object containing the information to use for this LDAP exception.

LDAPException

public LDAPException(LDAPResult ldapResult,
                     java.lang.Throwable cause)
Creates a new LDAP exception using the information contained in the provided LDAP result object.

Parameters:
ldapResult - The LDAP result object containing the information to use for this LDAP exception.
cause - The underlying exception that triggered this exception.

LDAPException

public LDAPException(LDAPException e)
Creates a new LDAP exception using the information contained in the provided LDAP exception.

Parameters:
e - The LDAP exception to use to create this exception.
Method Detail

getResultCode

public final ResultCode getResultCode()
Retrieves the result code for this LDAP exception.

Returns:
The result code for this LDAP exception.

getMatchedDN

public final java.lang.String getMatchedDN()
Retrieves the matched DN for this LDAP exception.

Returns:
The matched DN for this LDAP exception, or null if there is none.

getDiagnosticMessage

public final java.lang.String getDiagnosticMessage()
Retrieves the diagnostic message returned by the directory server.

Returns:
The diagnostic message returned by the directory server, or null if there is none.

getReferralURLs

public final java.lang.String[] getReferralURLs()
Retrieves the set of referral URLs for this LDAP exception.

Returns:
The set of referral URLs for this LDAP exception, or an empty array if there are none.

hasResponseControl

public final boolean hasResponseControl()
Indicates whether this result contains at least one control.

Returns:
true if this result contains at least one control, or false if not.

hasResponseControl

public final boolean hasResponseControl(java.lang.String oid)
Indicates whether this result contains at least one control with the specified OID.

Parameters:
oid - The object identifier for which to make the determination. It must not be null.
Returns:
true if this result contains at least one control with the specified OID, or false if not.

getResponseControls

public final Control[] getResponseControls()
Retrieves the set of response controls for this LDAP exception. Individual response controls of a specific type may be retrieved and decoded using the get method in the response control class, using the toLDAPResult() method to convert this exception to an LDAPResult.

Returns:
The set of response controls for this LDAP exception, or an empty array if there are none.

getResponseControl

public final Control getResponseControl(java.lang.String oid)
Retrieves the response control with the specified OID.

Parameters:
oid - The OID of the control to retrieve.
Returns:
The response control with the specified OID, or null if there is no such control.

toLDAPResult

public LDAPResult toLDAPResult()
Creates a new LDAPResult object from this exception.

Returns:
The LDAPResult object created from this exception.

getResultString

public java.lang.String getResultString()
Retrieves a string representation of this LDAP result, consisting of the result code, diagnostic message (if present), matched DN (if present), and referral URLs (if present).

Returns:
A string representation of this LDAP result.

toString

public void toString(java.lang.StringBuilder buffer)
Appends a string representation of this exception to the provided buffer.

Overrides:
toString in class LDAPSDKException
Parameters:
buffer - The buffer to which the string representation of this exception is to be appended.

getExceptionMessage

public final java.lang.String getExceptionMessage()
Retrieves a string representation of this exception suitable for use in messages.

Overrides:
getExceptionMessage in class LDAPSDKException
Returns:
A string representation of this exception suitable for use in messages.