Package com.isode.dsapi

Class Indication

java.lang.Object
com.isode.dsapi.Indication
All Implemented Interfaces:
SWIG_DSAPIConstants, Iterable<Entry>
public class Indication extends Object implements SWIG_DSAPIConstants, Iterable<Entry>
An Indication contains information about a directory operation. Indications are returned by the class library; they cannot be created by a user application.

Indication objects may contain:

  • an errorType and, optionally, an errorValue which represent the result of the operation.
  • for LDAP operations, the Indication may contain extra supplementary text returned by the server
  • information about whether a read or search was subject to some kind of limit
  • Password Policy Status, if this was returned by the directory
  • for a compare operation, the result of the comparison
  • In the case of a successful read or search operation, one or more Entry objects, as well as zero or more referral objects representing reference or referrals returned by the directory

  • Field Details

    • NoLimitProblem

      public static final int NoLimitProblem
      Value returned by getLimitProblem() to indicate that all results were received.
      See Also:

    • TimeLimitExceeded

      public static final int TimeLimitExceeded
      Value returned by getLimitProblem() to indicate that a time limit was reached
      See Also:

    • SizeLimitExceeded

      public static final int SizeLimitExceeded
      Value returned by getLimitProblem() to indicate that a size limit was reached.
      See Also:

    • AdminLimitExceeded

      public static final int AdminLimitExceeded
      Value returned by getLimitProblem() to indicate that an administrative limit was reached.
      See Also:

  • Method Details

    • finalize

      protected void finalize() throws Throwable
      Releases any native structures associated with this object.
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • toString

      public String toString() throws NativeLibraryException
      A user-friendly String representation of an Indication, which contains as much information about it as possible. This is primarily useful for debugging.
      Overrides:
      toString in class Object
      Returns:
      String representation of the Indication
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • getOperationAndDN

      public String getOperationAndDN()
      Return a String representing the operation (and DN if possible) that resulted in this Indication. In no DN is present, then the method simply returns the operation name. Example values returned could be Read(cn=jim,c=gb) or Modify(<root>) or Anonymous Bind.
      Returns:
      a String containing the operation and DN, if applicable, for this indication

    • getLimitProblem

      public int getLimitProblem() throws NativeLibraryException
      Returns a value to indicate what, if anything, limited the results in this set. The value returned will be one of
      • Indication.NoLimitProblem
      • Indication.TimeLimitExceeded
      • Indication.SizeLimitExceeded
      • Indication.AdminLimitExceeded
      Returns:
      an integer value.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • compareMatched

      public boolean compareMatched() throws NativeLibraryException
      Determine whether an Indication returned from a compare operation shows that a match was successful.
      Returns:
      true if this object represents an Indication returned by a call DirectorySession.compare() where the specified value exists in the directory. If the directory indicated that there was no such value, or if this Indication was not returned by a compare operation, then false will be returned.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library.
      See Also:

    • getEntryCount

      public int getEntryCount()
      Return a count of the set of entries contained in the operation outcome. Only read and search operations return entries, so it only makes sense to use this call for Indication objects returned from reads or searches.
      Returns:
      the number of entries (will be zero for an Indication object that does not represent a read or a search).

    • getReferenceCount

      public int getReferenceCount()
      Return a count of the set of continuation references contained in the operation outcome. Only read and search operations return continuation references, so it only makes sense to use this call for Indication objects returned from searches.
      Returns:
      the number of continuation references (which will be zero for an Indication object that does not represent a search).

    • getReferralCount

      public int getReferralCount()
      Return a count of the set of referrals contained in the operation outcome. This will only be non-zero when the Indication represents an operation which failed with a referral error.
      Returns:
      the number of referrals (which will be zero for an Indication object that does not represent an operation which failed with a ReferralException).
      See Also:

    • hasLimitProblem

      public boolean hasLimitProblem() throws NativeLibraryException
      Determines whether this indication was constrained by some limit problem.
      Returns:
      true if the results for this indication were constrained by a limit, false otherwise.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      See Also:

    • getEntry

      public Entry getEntry(int index) throws ArrayIndexOutOfBoundsException
      Return a specific Entry from the Indication
      Parameters:
      index - the index of the Entry to be returned (starting from zero)
      Returns:
      an Entry
      Throws:
      ArrayIndexOutOfBoundsException - if index is greater than or equal to the value returned by getEntryCount().

    • getReference

      public Referral getReference(int index) throws ArrayIndexOutOfBoundsException
      Return a specific continuation reference from the Indication
      Parameters:
      index - the index of the reference to be returned (starting from zero)
      Returns:
      a Referral object containing information about the specified continuation reference
      Throws:
      ArrayIndexOutOfBoundsException - if index is greater than or equal to the value returned by getReferenceCount().

    • getReferral

      public Referral getReferral(int index) throws ArrayIndexOutOfBoundsException
      Return a specific referral from the Indication
      Parameters:
      index - the index of the referral to be returned (starting from zero)
      Returns:
      a Referral object containing information about the specified referral
      Throws:
      ArrayIndexOutOfBoundsException - if index is greater than or equal to the value returned by getReferralCount().

    • iterator

      public Iterator<Entry> iterator()
      Returns an iterator over the entries in this Indication
      Specified by:
      iterator in interface Iterable<Entry>
      Returns:
      an iterator that can be used to process all the entries in this Indication

    • referenceIterator

      public Iterator<Referral> referenceIterator()
      Returns an iterator over the continuation references in this Indication
      Returns:
      an iterator that can be used to process all the continuation references in this Indication

    • referralIterator

      public Iterator<Referral> referralIterator()
      Returns an iterator over the referrals in this Indication
      Returns:
      an iterator that can be used to process all the referrals in this Indication

    • getErrorType

      public int getErrorType()
      Returns the value of the "error type" field for this Indication.

      The table below shows the values (defined in SWIG_DSAPIConstants) that may be returned by this method; in cases noted, the value returned by getErrorValue() will provide supplementary information.

      The IndicationException.getErrorTypeString(int) method can be used to obtain textual versions of error types.

      DS_E_ATTRIBUTE Attribute error. Will be accompanied by a DS_E_AT_xxxx error value
      DS_E_NAME Name error. Will be accompanied by a DS_E_NAME_xxxx error value
      DS_E_SERVICE Service error. Will be accompanied by a DS_E_SVC_xxxx error value
      DS_E_REFERRAL Referral error.
      DS_E_ABANDONED Operation abandoned error.
      DS_E_SECURITY Security error. Will be accompanied by a DS_E_SEC_xxxx error value
      DS_E_ABANDONFAILED Abandon failed error. Will be accompanied by a DS_E_AB_xxxx error value
      DS_E_UPDATE Update error. Will be accompanied by a DS_E_UPD_xxxx error value
      DS_E_DSAREFERRAL DSA referral error.
      DS_E_LOCAL Unknown local error.
      DS_E_REMOTE Unknown remote error.
      DS_E_UNKNOWN Unknown error.
      DS_E_X509 Error detected by X509 library. Will be accompanied by a DS_E_X509_xxxx error value
      Returns:
      error type
      See Also:

    • getErrorValue

      public int getErrorValue()
      Returns the value of the "error value" field for this Indication.

      The table below shows the values (defined in SWIG_DSAPIConstants) which may be returned by this method:

      DS_E_NOINFO No more information
      DS_E_AT_NOSUCHATTRIBUTE No such attribute
      DS_E_AT_INVALIDATTRIBUTESYNTAX Invalid attribute syntax
      DS_E_AT_UNDEFINEDATTRIBUTETYPE Undefined attribute type
      DS_E_AT_INAPPROPRIATEMATCHING Inappropriate matching
      DS_E_AT_CONSTRAINTVIOLATION Constraint violation
      DS_E_AT_TYPEORVALUEEXISTS Type or value exists
      DS_E_NAME_NOSUCHOBJECT No such object
      DS_E_NAME_ALIASPROBLEM Alias problem
      DS_E_NAME_INVALIDATTRIBUTESYNTAX Invalid attribute syntax
      DS_E_NAME_ALIASDEREFERENCE Alias dereference
      DS_E_SVC_BUSY Busy
      DS_E_SVC_UNAVAILABLE Unavailable
      DS_E_SVC_UNWILLINGTOPERFORM Unwilling to perform
      DS_E_SVC_CHAININGREQUIRED Chaining required
      DS_E_SVC_UNABLETOPROCEED Unable to proceed
      DS_E_SVC_INVALIDREFERENCE Invalid reference
      DS_E_SVC_TIMELIMITEXCEEDED Timelimit exceeded
      DS_E_SVC_ADMINISTRATIVELIMITEXCEEDED Administrative limit exceeded
      DS_E_SVC_LOOPDETECTED Loop detected
      DS_E_SVC_UNAVAILABLECRITICALEXTENSION Unavailable critical extension
      DS_E_SVC_OUTOFSCOPE Out of scope
      DS_E_SVC_DITERROR DIT error
      DS_E_SVC_INVALIDQUERYREFERENCE Invalid query reference
      DS_E_SEC_AUTHENTICATION Invalid authentication
      DS_E_SEC_INVALIDCREDENTIALS Invalid credentials
      DS_E_SEC_ACCESSRIGHTS Insufficient access rights
      DS_E_SEC_INVALIDSIGNATURE Invalid signature
      DS_E_SEC_PROTECTIONREQUIRED Protection required
      DS_E_SEC_NOINFORMATION No information
      DS_E_AB_NOSUCHOPERATION No such operation
      DS_E_AB_TOOLATE Too late to abandon
      DS_E_AB_CANNOTABANDON Cannot abandon
      DS_E_UPD_NAMINGVIOLATION Naming violation
      DS_E_UPD_OBJECTCLASSVIOLATION Objectclass violation
      DS_E_UPD_NOTONNONLEAF Not on non-leaf
      DS_E_UPD_NOTONRDN Not on RDN
      DS_E_UPD_ALREADYEXISTS Already exists
      DS_E_UPD_AFFECTSMULTIPLEDSAS Affects multiple DSAs
      DS_E_UPD_NOOBJECTCLASSMODS No objectclass modifications
      DS_E_X509_RESULTSDISCARDED Not all search results were properly signed
      Returns:
      error value
      See Also:

    • hasDSASignatureVerificationError

      public boolean hasDSASignatureVerificationError()
      Determine whether there was a DSA signature verification failure whilst obtaining any of the results requested in the operation that generated this Indication. This only tests for indications of bad signatures received from the DSAs involved in the operation.
      Returns:
      true if this Indication is associated with a signed operation which reported an error on DSA signature verification, false if no such error was reported, or if the associated operation was not signed.

    • hasDUASignatureVerificationError

      public boolean hasDUASignatureVerificationError()
      Determine whether there was a DUA signature verification failure on the operation sent to the DSA. This means that the DSA rejected our signature and refused to perform the operation.
      Returns:
      true if this Indication is associated with a signed operation which failed due to the DSA rejecting our signature, or otherwise false

    • getOperation

      public String getOperation()
      Determine the operation which returned this Indication.
      Returns:
      the name of the operation which returned this indication (such as "Read", "Modify", etc.).

    • getDN

      public DN getDN()
      Determine the DN (if any) that relates to this Indication. For an Add, Delete, Modify, Read, this will be the DN of the entry that was read. For a Search it will be the base DN of the search. for a Rename, it will be the DN of the entry being renamed. There may be no DN associated with the operation, so callers should check for a null return.
      Returns:
      the DN (which may be null) that relates to the operation which resulted in this indication.

    • hasContinuationReferences

      public boolean hasContinuationReferences()
      Determine whether this Indication contains any continuation references.
      Returns:
      true if there are some continuation references in this Indication, false otherwise.

    • isReferral

      public boolean isReferral()
      Determine whether this Indication represents a referral error.
      Returns:
      true if this indication corresponds with an operation that resulted in a referral, false otherwise.

    • sortByDN

      public void sortByDN()
      Sort the entries in the indication by DN. This gives a heirarchical sorted order, parents before children, in order of RDN type and value.

    • getPasswordPolicyResponse

      public Indication.PasswordPolicyResponse getPasswordPolicyResponse()
      Returns any information related to a password policy response associated with this Indication in a single object. If no such information was returned by the server, then this method returns null.
      Returns:
      a PasswordPolicyResponse object, or null if no password policy response information was returned.
      See Also:

    • getPasswordPolicyExpiryWarning

      public int getPasswordPolicyExpiryWarning()
      Determine the expiry time of the current account's password.

      This method returns -1 if the Indication does not contain the requested information: this may be because the requesting operation did not use the ReadPasswordPolicy flag in the CommonArgs, or if the directory was not willing or able to return the information.

      Returns:
      an integer value representing the number of seconds remaining before the current password expires, or a value of -1 to indicate that no such information was contained in the Indication.
      See Also:

    • getPasswordPolicyGraceWarning

      public int getPasswordPolicyGraceWarning()
      Determine the number of grace authentications left for the current account's password. The value returned indicates the remaining number of times a user will be able to authenticate with an expired password.

      This method will return -1 if the Indication does not contain the requested information: this may be because the requesting operation did not use the ReadPasswordPolicy flag in the CommonArgs, or if the directory was not willing or able to return the information.

      Returns:
      an integer value representing the number of grace authentications remaining; a value of -1 indicates that no such information was contained in the Indication.
      See Also:

    • getPasswordPolicyStatus

      public Indication.PasswordPolicyStatus getPasswordPolicyStatus()
      Determine the error relating to the current account's password.

      This method returns null if the Indication does not contain the requested information: this may be because the requesting operation did not use the ReadPasswordPolicy flag in the CommonArgs, or if the directory was not willing or able to return the information.

      Returns:
      a PasswordPolicyStatus representing the status returned by the directory, or null if no such information was contained in the Indication.
      See Also:

    • getExtraErrorText

      public String getExtraErrorText() throws NativeLibraryException
      Determine the extra error text (if any) associated with this Indication. Certain directory operations may return supplementary error text (specifically, responses to LDAP operations may contain a text string containing extra information from the directory server).
      Returns:
      a String with supplementary text about this operation (which will be null if no such text is available).
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • getDirectorySession

      public DirectorySession getDirectorySession()
      Determine the DirectorySession associated with this Indication
      Returns:
      the DirectorySession associated with this Indication.
      Since:
      14.4

    • hasMorePagedResults

      public boolean hasMorePagedResults() throws NativeLibraryException
      Determine whether more pages are available for a paged-results search.

      For an Indication which is being used to process a series of paged results, this method can be used to determine whether the server has indicated that not all results have yet been returned (i.e. that it is worth calling nextPagedResultsPage()).

      Returns:
      true if this is an Indication for a paged results request that has more results still to be read from the server, false otherwise.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      Since:
      14.4
      See Also:

    • getTxnStartResult

      public byte[] getTxnStartResult() throws NativeLibraryException
      Return transaction ID from an Indication from a TxnStart

      If the last operation was to start a transaction, this returns the transaction ID.

      Returns:
      byte[] Transaction ID.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      Since:
      14.4
      See Also:

    • getTxnEndResult

      public int getTxnEndResult() throws NativeLibraryException
      Return result codefrom an Indication from a TxnEnd

      If the last operation was to end a transaction, this returns the result code.

      Returns:
      int result code.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      Since:
      14.4

    • nextPagedResultsPage

      public void nextPagedResultsPage() throws OperationFailedException, NotBoundException, SignedOpFailedException, DirectoryOperationFailedException, NoMorePagedResultsException
      Update the Indication with the next set of paged results.

      For an Indication which is being used to process a series of paged results, this method requests that the server return the next page of results. The Indication object will be updated to contain the next set of results (and any previous results will be discarded).

      In the case of an error, any previous entries in the Indication will be lost.

      For an alternative version of this method which does not throw an exception when no more pages are available, use getNextResultsPage()

      Throws:
      OperationFailedException - if this Indication is not one that was returned by a paged-results search.
      NoMorePagedResultsException - if no more paged results are available.
      NotBoundException - if the DirectorySession corresponding to this Indication is no longer bound.
      SignedOpFailedException - if for a signed operation, an error occurred when attempting to sign the request.
      DirectoryOperationFailedException - if the operation was sent to the directory, and the directory returned an "operation failed" status with no extra indication or information.
      NativeLibraryException - if an unrecoverable error was detected by the native library
      Since:
      14.4
      See Also:

    • getNextResultsPage

      public boolean getNextResultsPage() throws OperationFailedException, NotBoundException, SignedOpFailedException, DirectoryOperationFailedException
      Update the Indication with the next set of paged results.

      For an Indication which is being used to process a series of paged results, this method requests that the server return the next page of results. The Indication object will be updated to contain the next set of results (and any previous results will be discarded).

      In the case of an error, any previous entries in the Indication will be lost.

      For an alternative version of this method which will throw an exception when no more pages are available, use nextPagedResultsPage()

      Returns:
      true if the next page of results was returned, false if no more pages are available.
      Throws:
      OperationFailedException - if this Indication is not one that was returned by a paged-results search.
      NotBoundException - if the DirectorySession corresponding to this Indication is no longer bound.
      SignedOpFailedException - if for a signed operation, an error occurred when attempting to sign the request.
      DirectoryOperationFailedException - if the operation was sent to the directory, and the directory returned an "operation failed" status with no extra indication or information.
      NativeLibraryException - if an unrecoverable error was detected by the native library
      Since:
      14.6

    • isPagedResultsIndication

      public boolean isPagedResultsIndication()
      Determine whether this Indication relates to a search that requested paged results. Note that the value returned by this method does not take into account whether the server was able/willing to honour the request.
      Returns:
      true if the search that returned this Indication requested paged results, false otherwise.
      Since:
      14.4
      See Also:

    • getRestrictionWarnings

      public List<String> getRestrictionWarnings()
      Check to see if the results have been subject to some kind of limit, and if so return a list of strings describing those limits. The checks made are for a result set that has been constrained by a size/admin/time limit, and for the case when some results have been discarded from a signed search operation because the X.509 library was unable to verify their signature.
      Returns:
      a list of Strings each of which describes a reason that has caused the results to be constrained in some way. The method will return null if no such problems occurred.
      Since:
      14.6

    • getRestrictionWarnings

      public List<String> getRestrictionWarnings(List<DN> chop)
      Check to see if the results have been subject to some kind of limit, and if so return a list of strings describing those limits. The checks made are for a result set that has been constrained by a size/admin/time limit, and for the case when some results have been discarded from a signed search operation because the X.509 library was unable to verify their signature.
      Parameters:
      chop - List of DNs to ignore, or null if not required; this affects reference warnings, omitting them if they are not relevant due to the DN being a chop point
      Returns:
      a list of Strings each of which describes a reason that has caused the results to be constrained in some way. The method will return null if no such problems occurred.
      Since:
      14.6

    • getLimitProblemText

      public String getLimitProblemText()
      Get user-friendly string corresponding to the limit problem, if any.
      Returns:
      String corresponding to the limit problem if there is one, null if there is no limit problem
      Since:
      15.0