Class MultiUpdateExtendedRequest

  • All Implemented Interfaces:
    ProtocolOp, ReadOnlyLDAPRequest, java.io.Serializable

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class MultiUpdateExtendedRequest
    extends ExtendedRequest
    This class provides an implementation of an extended request that can be used to send multiple update requests to the server in a single packet, optionally processing them as a single atomic unit.
    NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

    The OID for this request is 1.3.6.1.4.1.30221.2.6.17, and the value must have the following encoding:

       MultiUpdateRequestValue ::= SEQUENCE {
            errorBehavior     ENUMERATED {
                 atomic              (0),
                 quitOnError         (1),
                 continueOnError     (2),
                 ... },
            requests          SEQUENCE OF SEQUENCE {
                 updateOp     CHOICE {
                      modifyRequest     ModifyRequest,
                      addRequest        AddRequest,
                      delRequest        DelRequest,
                      modDNRequest      ModifyDNRequest,
                      extendedReq       ExtendedRequest,
                      ... },
                 controls     [0] Controls OPTIONAL,
                 ... },
            ... }
     


    Example

    The following example demonstrates the use of the multi-update extended request to create a new user entry and modify an existing group entry to add the new user as a member:
     MultiUpdateExtendedRequest multiUpdateRequest =
          new MultiUpdateExtendedRequest(
               MultiUpdateErrorBehavior.ABORT_ON_ERROR,
               new AddRequest(
                    "dn: uid=new.user,ou=People,dc=example,dc=com",
                    "objectClass: top",
                    "objectClass: person",
                    "objectClass: organizationalPerson",
                    "objectClass: inetOrgPerson",
                    "uid: new.user",
                    "givenName: New",
                    "sn: User",
                    "cn: New User"),
               new ModifyRequest(
                    "dn: cn=Test Group,ou=Groups,dc=example,dc=com",
                    "changetype: modify",
                    "add: member",
                    "member: uid=new.user,ou=People,dc=example,dc=com"));
    
     MultiUpdateExtendedResult multiUpdateResult =
          (MultiUpdateExtendedResult)
          connection.processExtendedOperation(multiUpdateRequest);
     if (multiUpdateResult.getResultCode() == ResultCode.SUCCESS)
     {
       // The server successfully processed the multi-update request, although
       // this does not necessarily mean that any or all of the changes
       // contained in it were successful.  For that, we should look at the
       // changes applied and/or results element of the response.
       switch (multiUpdateResult.getChangesApplied())
       {
         case NONE:
           // There were no changes applied.  Based on the configuration of the
           // request, this means that the attempt to create the user failed
           // and there was no subsequent attempt to add that user to a group.
           break;
         case ALL:
           // Both parts of the update succeeded.  The user was created and
           // successfully added to a group.
           break;
         case PARTIAL:
           // At least one update succeeded, and at least one failed.  Based on
           // the configuration of the request, this means that the user was
           // successfully created but not added to the target group.
           break;
       }
     }
     else
     {
       // The server encountered a failure while attempting to parse or process
       // the multi-update operation itself and did not attempt to process any
       // of the changes contained in the request.
     }
     
    See Also:
    MultiUpdateErrorBehavior, MultiUpdateExtendedResult, Serialized Form
    • Constructor Detail

      • MultiUpdateExtendedRequest

        public MultiUpdateExtendedRequest​(@NotNull
                                          MultiUpdateErrorBehavior errorBehavior,
                                          @NotNull
                                          LDAPRequest... requests)
                                   throws LDAPException
        Creates a new multi-update extended request with the provided information.
        Parameters:
        errorBehavior - The behavior to exhibit if errors are encountered. It must not be null.
        requests - The set of requests to be processed. It must not be null or empty. Only add, delete, modify, modify DN, and certain extended requests (as determined by the server) should be included.
        Throws:
        LDAPException - If the set of requests includes one or more invalid request types.
      • MultiUpdateExtendedRequest

        public MultiUpdateExtendedRequest​(@NotNull
                                          MultiUpdateErrorBehavior errorBehavior,
                                          @NotNull
                                          LDAPRequest[] requests,
                                          @Nullable
                                          Control... controls)
                                   throws LDAPException
        Creates a new multi-update extended request with the provided information.
        Parameters:
        errorBehavior - The behavior to exhibit if errors are encountered. It must not be null.
        requests - The set of requests to be processed. It must not be null or empty. Only add, delete, modify, modify DN, and certain extended requests (as determined by the server) should be included. Each request may include zero or more controls that should apply only to that request.
        controls - The set of controls to be included in the multi-update extended request. It may be empty or null if no extended request controls are needed in the multi-update request.
        Throws:
        LDAPException - If the set of requests includes one or more invalid request types.
      • MultiUpdateExtendedRequest

        public MultiUpdateExtendedRequest​(@NotNull
                                          MultiUpdateErrorBehavior errorBehavior,
                                          @NotNull
                                          java.util.List<LDAPRequest> requests,
                                          @Nullable
                                          Control... controls)
                                   throws LDAPException
        Creates a new multi-update extended request with the provided information.
        Parameters:
        errorBehavior - The behavior to exhibit if errors are encountered. It must not be null.
        requests - The set of requests to be processed. It must not be null or empty. Only add, delete, modify, modify DN, and certain extended requests (as determined by the server) should be included. Each request may include zero or more controls that should apply only to that request.
        controls - The set of controls to be included in the multi-update extended request. It may be empty or null if no extended request controls are needed in the multi-update request.
        Throws:
        LDAPException - If the set of requests includes one or more invalid request types.
      • MultiUpdateExtendedRequest

        public MultiUpdateExtendedRequest​(@NotNull
                                          ExtendedRequest extendedRequest)
                                   throws LDAPException
        Creates a new multi-update extended request from the provided generic extended request.
        Parameters:
        extendedRequest - The generic extended request to use to create this multi-update extended request.
        Throws:
        LDAPException - If a problem occurs while decoding the request.
    • Method Detail

      • process

        @NotNull
        public MultiUpdateExtendedResult process​(@NotNull
                                                 LDAPConnection connection,
                                                 int depth)
                                          throws LDAPException
        Sends this extended request to the directory server over the provided connection and returns the associated response.
        Overrides:
        process in class ExtendedRequest
        Parameters:
        connection - The connection to use to communicate with the directory server.
        depth - The current referral depth for this request. It should always be one for the initial request, and should only be incremented when following referrals.
        Returns:
        An LDAP result object that provides information about the result of the extended operation processing.
        Throws:
        LDAPException - If a problem occurs while sending the request or reading the response.
      • getRequests

        @NotNull
        public java.util.List<LDAPRequestgetRequests()
        Retrieves the set of requests to be processed.
        Returns:
        The set of requests to be processed.
      • duplicate

        @NotNull
        public MultiUpdateExtendedRequest duplicate​(@Nullable
                                                    Control[] controls)
        Creates a new instance of this LDAP request that may be modified without impacting this request. The provided controls will be used for the new request instead of duplicating the controls from this request.. Subclasses should override this method to return a duplicate of the appropriate type.
        Specified by:
        duplicate in interface ReadOnlyLDAPRequest
        Overrides:
        duplicate in class ExtendedRequest
        Parameters:
        controls - The set of controls to include in the duplicate request.
        Returns:
        A new instance of this LDAP request that may be modified without impacting this request.
      • getExtendedRequestName

        @NotNull
        public java.lang.String getExtendedRequestName()
        Retrieves the user-friendly name for the extended request, if available. If no user-friendly name has been defined, then the OID will be returned.
        Overrides:
        getExtendedRequestName in class ExtendedRequest
        Returns:
        The user-friendly name for this extended request, or the OID if no user-friendly name is available.