Package com.isode.dsapi

Class CommonArgs

  • All Implemented Interfaces:
    SWIG_DSAPIConstants
    public class CommonArgs
extends java.lang.Object
implements SWIG_DSAPIConstants
    A CommonArgs object contains a set of values, some boolean and some integers, which may be used to specify extra information about how a given directory operation should be performed. Often the same CommonArgs object will be used for a whole series of operations.

    Each of the values in CommonArgs has a default value. The default constructor creates an object with all the values set to their default state; the documentation for setDefaults() describes what these values are.

    • Constructor Detail

      • CommonArgs

        public CommonArgs​(CommonArgs orig)
           throws NativeLibraryException
        Create a new CommonArgs which will have the same values as the supplied value.
        Parameters:
        orig - a CommonArgs object from which to copy values. If this is null then the default values will be used.
        Throws:
        NativeLibraryException
        See Also:
        setDefaults()

      • CommonArgs

        public CommonArgs​(java.lang.String stringRep)
           throws java.lang.IllegalArgumentException
        Create a CommonArgs object with values as defined in the supplied string representation. For any fields that are not defined, a default value will be used (see setDefaults)
        Parameters:
        stringRep - a String representation of a set of common arguments. This value may be null, in which case an object containing the default values will be returned.
        Throws:
        java.lang.IllegalArgumentException - if stringRep cannot be parsed.
        See Also:
        getStringRepresentation()

    • 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

      • setPreferChain

        public void setPreferChain​(boolean enable)
                    throws NativeLibraryException
        Request chained operation rather than referral where necessary.
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setChainingProhibit

        public void setChainingProhibit​(boolean enable)
                         throws NativeLibraryException
        Prohibit the use of changing in a distributed operation.
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setLocalScope

        public void setLocalScope​(boolean enable)
                   throws NativeLibraryException
        Restrict operation to data stored in local scope (usually the local DSA).
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setDontUseCopy

        public void setDontUseCopy​(boolean enable)
                    throws NativeLibraryException
        Request that copied data not be used to satisfy the operation.
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setDontDerefAlias

        public void setDontDerefAlias​(boolean enable)
                       throws NativeLibraryException
        Request that any alias used to identify the entry affected by the operation is not to be dereferenced. This flag is treated in slightly different ways for DAP and LDAP connections:

        DAP

        For search operations, this flag determines whether or aliases are dereferenced when locating the base object.
        For add, modify, and delete operations, this flag is ignored (and treated as set) unless useAliasOnUpdate is set.
        For rename operations, this option is ignored.

        LDAP

        For LDAP, this flag only affects search operations. In conjunction with the searchAliases flag, it determines the setting of the LDAP_OPT_DEREF flag for search operations:
        searchAliasesdontDereferenceAlias
        LDAP_DEREF_SEARCHING
        set
        set
        LDAP_DEREF_ALWAYS
        set
        unset
        LDAP_DEREF_NEVER
        unset
        set
        LDAP_DEREF_FINDING
        unset
        unset
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library
        See Also:
        setUseAliasOnUpdate(boolean), setSearchAliases(boolean)

      • setUseAliasOnUpdate

        public void setUseAliasOnUpdate​(boolean enable)
                         throws NativeLibraryException
        This flag controls whether aliases are dereferenced in add, modify and remove operations.

        Note: this flag has no effect for LDAP connections.

        Aliases will be dereferenced for add, modify and delete operations if this flag is set and dontderefalias is not set.

        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library
        See Also:
        setDontDerefAlias(boolean)

      • setSearchAliases

        public void setSearchAliases​(boolean enable)
                      throws NativeLibraryException
        Requests that aliases within search results should be dereferenced. For DAP connections, this value determines how subordinates of the base object should be dereferenced during search operations.

        If the searchAliases parameter is true, aliases shall be dereferenced, if the parameter is false, aliases shall not be dereferenced. If the searchAliases parameter is true, the search shall continue in the subtree of the aliased entry.

        For LDAP connections, this flag, in conjunction with the dontDerefAlias flag, determines the alias dereferencing for search operations.

        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library
        See Also:
        setDontDerefAlias(boolean)

      • setSubentries

        public void setSubentries​(boolean enable)
                   throws NativeLibraryException
        Indicates that a Search or List operation is to access subentries only; normal entries become inaccessible.
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setCopyShallDo

        public void setCopyShallDo​(boolean enable)
                    throws NativeLibraryException
        Indicates that if the Directory is able to partly but not fully satisfy a query at a copy of an entry, it shall not chain the query
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setManageDsaIT

        public void setManageDsaIT​(boolean enable)
                    throws NativeLibraryException
        Indicates that the Directory operation should be processed against the DsaIT instead of the DIT.
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setSigned

        public void setSigned​(boolean enable)
               throws NativeLibraryException
        Indicates that the Directory operation should be cryptographically signed. This setting is only valid for strongly bound connections.
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setEncrypted

        public void setEncrypted​(boolean enable)
                  throws NativeLibraryException
        Indicates that the Directory operation should be encrypted.

        Note: this setting is currently not used.

        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setDisableVerification

        public void setDisableVerification​(boolean disable)
                            throws NativeLibraryException
        Used to specify server certificate verification should be disabled.

        Normally, when a server presents a certificate (during a strong bind, or one performed over an LDAP/TLS connection), DSAPI will perform certificate verification, allowing the bind to succeed only if the verification works.

        This verification operation can be disabled using this setting. It is assumed that a caller using this option will do his own verification. In such cases, clients may use DirectorySession.getSessionCertificates() to obtain information about the server certificate(s).

        This flag is only relevant for bind operations.

        Parameters:
        disable - true to turn off DSAPI's verification, false to allow DSAPI to perform verification (the default).
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library
        Since:
        14.4
        See Also:
        DirectorySession.getSessionCertificates()

      • setAttrsOnly

        public void setAttrsOnly​(boolean enable)
                  throws NativeLibraryException
        Indicate that a search or read operation should return matching Attributes, with no values present.
        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setRequestPasswordPolicy

        public void setRequestPasswordPolicy​(boolean enable)
                              throws NativeLibraryException
        Requests that the directory server returns information about password policy constraints for the currently bound user. A directory is not obliged to return any such information.

        This information, if available, will be returned in the Indication for an operation (whether or not the operation is successful). In the case of operations which fail as a result of password policy constraints, callers may obtain the failing Indication object via the IndicationException, for example: 

         try {
     CommonArgs ca = new CommonArgs();
     ca.setRequestPasswordPolicy(true);
     // Attempt to modify the password
     ds.modify(modifyEntry,ca);
     .
     .
  }
  catch (IndicationException e) {
     System.out.println("password modification failed : ");
     Indication ii = e.getIndication();
     if (ii != null) {
         Indication.PasswordPolicyResponse ppr;
         ppr = ii.getPasswordPolicyResponse();
         if (ppr != null) {
             System.out.println(ppr);
         }
         else {
             System.out.println("--no password policy response");
         }
     }
     else {
         System.out.println("--no further information available");
     }
  }

        This option has no effect on DAP connections.

        Parameters:
        enable - true to enable, false to disable.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library
        See Also:
        Indication.getPasswordPolicyStatus(), Indication.getPasswordPolicyExpiryWarning(), Indication.getPasswordPolicyGraceWarning(), Indication.getPasswordPolicyResponse()

      • getPreferChain

        public boolean getPreferChain()
                       throws NativeLibraryException
        Determine whether chained operations rather than referral will be used where necessary.
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getChainingProhibit

        public boolean getChainingProhibit()
                            throws NativeLibraryException
        Prohibit the use of changing in a distributed operation.
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getLocalScope

        public boolean getLocalScope()
                      throws NativeLibraryException
        Restrict operation to data stored in local scope (usually the local DSA).
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getDontUseCopy

        public boolean getDontUseCopy()
                       throws NativeLibraryException
        Request that copied data not be used to satisfy the operation.
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getSubentries

        public boolean getSubentries()
                      throws NativeLibraryException
        Indicates that a Search or List operation is to access subentries only; normal entries become inaccessible.
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getCopyShallDo

        public boolean getCopyShallDo()
                       throws NativeLibraryException
        Indicates that if the Directory is able to partly but not fully satisfy a query at a copy of an entry, it shall not chain the query
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getManageDsaIT

        public boolean getManageDsaIT()
                       throws NativeLibraryException
        Indicates that the Directory operation should be processed against the DsaIT instead of the DIT.
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getSigned

        public boolean getSigned()
                  throws NativeLibraryException
        Determine whether the Directory operation is to be cryptographically signed.
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getEncrypted

        public boolean getEncrypted()
                     throws NativeLibraryException
        Determine whether the Directory operation is to be encrypted
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getAttrsOnly

        public boolean getAttrsOnly()
                     throws NativeLibraryException
        Determine whether the "attrsonly" flag is set. A search or read operation performed with this flag set will return the requested Attributes from the entries, but the Attributes will contain no values.
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getRequestPasswordPolicy

        public boolean getRequestPasswordPolicy()
                                 throws NativeLibraryException
        Determine whether the "request password policy" flag is set. An operation on an LDAP connection that has this flag set requests that the directory returns the current account's password policy status, which will be stored in the operation's Indication.
        Returns:
        true if the flag is set, false otherwise.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setPriority

        public void setPriority​(int priority)
                 throws NativeLibraryException
        Sets the priority of the operation. 0 is low priority, 1 is medium, and 2 is high priority.
        Parameters:
        priority - the priority
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setTimeLimit

        public void setTimeLimit​(int timeLimit)
                  throws NativeLibraryException
        Sets the maximum time in seconds that this operation should be allowed to take. Note that this value is ignored by the client, and simply sent to the directory server. In other words, the value specified here does not limit how long the client will wait for a response; rather it indicates to the directory server (which may not always be able to comply) how long the client is prepared to wait.
        Parameters:
        timeLimit - time limit in seconds.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • setSizeLimit

        public void setSizeLimit​(int sizeLimit)
                  throws NativeLibraryException
        Sets the maximum number of entries that can be returned by a list or search operation. Note that the directory server may impose its own limit on the number of entries returned, which will not be affected by this setting.
        Parameters:
        sizeLimit - entry limit.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getPriority

        public int getPriority()
                throws NativeLibraryException
        Returns the priority associated with this operation
        Returns:
        the priority.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getTimeLimit

        public int getTimeLimit()
                 throws NativeLibraryException
        Returns the time limit associated with this operation.
        Returns:
        the time limit.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • getSizeLimit

        public int getSizeLimit()
                 throws NativeLibraryException
        Returns the size limit associated with this operation.
        Returns:
        the size limit.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • toString

        public java.lang.String toString()
        Return a string representation of this object. This will a String of the same form as returned by getStringRepresentation(), but may include extra information useful for debugging.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of the object

      • getStringRepresentation

        public java.lang.String getStringRepresentation()
                                         throws NativeLibraryException
        Return a String representation of the information inside this CommonArgs object, which may be parsed by the CommonArgs(String) constructor to re-create an object with the same settings.

        A typical result will look like this: 

         manageDsaIT=true encrypted=false priority=5 sizeLimit=100 timeLimit=200...
        Returns:
        a String representation of this CommonArgs object.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library
        See Also:
        CommonArgs(String)