Package com.isode.dsapi

Class CommonArgs

java.lang.Object
com.isode.dsapi.CommonArgs
All Implemented Interfaces:
SWIG_DSAPIConstants
public class CommonArgs extends 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 Details

    • CommonArgs

      public CommonArgs() throws NativeLibraryException
      Create a new CommonArgs object with defaults as defined in the setDefaults() method.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

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

    • CommonArgs

      public CommonArgs(String stringRep) throws 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:
      IllegalArgumentException - if stringRep cannot be parsed.
      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

    • 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

      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:

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

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

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

    • 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

    • getDontDerefAlias

      public boolean getDontDerefAlias() throws NativeLibraryException
      Determine whether aliases are dereferenced.
      Returns:
      true if the flag is set, false otherwise.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      See Also:

    • getSearchAliases

      public boolean getSearchAliases() throws NativeLibraryException
      Determine whether aliases are followed in search operations.
      Returns:
      true if the flag is set, false otherwise.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      See Also:

    • getUseAliasOnUpdate

      public boolean getUseAliasOnUpdate() throws NativeLibraryException
      Determine whether aliases are dereferenced in add, modify and remove operations.
      Returns:
      true if the flag is set, false otherwise.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      See Also:

    • 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

    • getDisableVerification

      public boolean getDisableVerification() throws NativeLibraryException
      Determine whether the verification of server certificates is disabled.
      Returns:
      true if the flag is set, false otherwise.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      Since:
      14.4
      See Also:

    • 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

    • setTransactionID

      public void setTransactionID(byte[] txn_id) throws NativeLibraryException
      Sets the transaction ID for a operation.
      Parameters:
      transaction - ID.
      Throws:
      NativeLibraryException

    • toString

      public 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 Object
      Returns:
      a String representation of the object

    • getStringRepresentation

      public 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:

    • setDefaults

      public void setDefaults()
      Set default common arguments. This method sets default values for all of the fields in the object, as follows:
      PreferChaintrue
      ChainingProhibitfalse
      LocalScopefalse
      DontUseCopyfalse
      DontDerefAliastrue
      SubEntriesfalse
      CopyShallDotrue
      AttrsOnlyfalse
      SearchAliasesfalse
      UseAliasOnUpdatefalse
      Signedfalse
      Encryptedfalse
      DisableVerificationfalse
      ManageDsaITfalse
      RequestPasswordPolicyfalse
      Priority2
      SizeLimit-1
      TimeLimit-1