Package com.isode.dsapi

Class Indication

  • All Implemented Interfaces:
    SWIG_DSAPIConstants, java.lang.Iterable<Entry>
    public class Indication
extends java.lang.Object
implements SWIG_DSAPIConstants, java.lang.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 Detail

      • NoLimitProblem

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

      • TimeLimitExceeded

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

      • SizeLimitExceeded

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

      • AdminLimitExceeded

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

    • Method Detail

      • finalize

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

      • toString

        public java.lang.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 java.lang.Object
        Returns:
        String representation of the Indication
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getOperationAndDN

        public java.lang.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:
        DirectorySession.compare(DN, Attribute, CommonArgs)

      • 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:
        ReferralException

      • 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:
        getLimitProblem()

      • getEntry

        public Entry getEntry​(int index)
               throws java.lang.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:
        java.lang.ArrayIndexOutOfBoundsException - if index is greater than or equal to the value returned by getEntryCount().

      • getReference

        public Referral getReference​(int index)
                      throws java.lang.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:
        java.lang.ArrayIndexOutOfBoundsException - if index is greater than or equal to the value returned by getReferenceCount().

      • getReferral

        public Referral getReferral​(int index)
                     throws java.lang.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:
        java.lang.ArrayIndexOutOfBoundsException - if index is greater than or equal to the value returned by getReferralCount().

      • iterator

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

      • referenceIterator

        public java.util.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 java.util.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

      • 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 java.lang.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.

      • 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:
        getPasswordPolicyResponse(), CommonArgs.setRequestPasswordPolicy(boolean)

      • 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:
        getPasswordPolicyResponse(), CommonArgs.setRequestPasswordPolicy(boolean)

      • 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:
        getPasswordPolicyResponse(), CommonArgs.setRequestPasswordPolicy(boolean)

      • getExtraErrorText

        public java.lang.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

      • 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

      • 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:
        DirectorySession.search(DN, String, int, Selection, CommonArgs, int), nextPagedResultsPage()

      • getRestrictionWarnings

        public java.util.List<java.lang.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 java.util.List<java.lang.String> getRestrictionWarnings​(java.util.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 java.lang.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