MultiUpdateExtendedRequest (UnboundID LDAP SDK for Java 7.0.1)

java.lang.Object
- com.unboundid.ldap.sdk.LDAPRequest
- - com.unboundid.ldap.sdk.ExtendedRequest
  - - com.unboundid.ldap.sdk.unboundidds.extensions.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

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String MULTI_UPDATE_REQUEST_OID
The OID (1.3.6.1.4.1.30221.2.6.17) for the multi-update extended request.
- Fields inherited from class com.unboundid.ldap.sdk.ExtendedRequest
  TYPE_EXTENDED_REQUEST_OID, TYPE_EXTENDED_REQUEST_VALUE

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`MULTI_UPDATE_REQUEST_OID` The OID (1.3.6.1.4.1.30221.2.6.17) for the multi-update extended request.

Constructor Summary

Constructors
Constructor and Description
`MultiUpdateExtendedRequest(ExtendedRequest extendedRequest)` Creates a new multi-update extended request from the provided generic extended request.
`MultiUpdateExtendedRequest(MultiUpdateErrorBehavior errorBehavior, LDAPRequest... requests)` Creates a new multi-update extended request with the provided information.
`MultiUpdateExtendedRequest(MultiUpdateErrorBehavior errorBehavior, LDAPRequest[] requests, Control... controls)` Creates a new multi-update extended request with the provided information.
`MultiUpdateExtendedRequest(MultiUpdateErrorBehavior errorBehavior, java.util.List<LDAPRequest> requests, Control... controls)` Creates a new multi-update extended request with the provided information.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`MultiUpdateExtendedRequest`	`duplicate()` Creates a new instance of this LDAP request that may be modified without impacting this request.
`MultiUpdateExtendedRequest`	`duplicate(Control[] controls)` Creates a new instance of this LDAP request that may be modified without impacting this request.
`MultiUpdateErrorBehavior`	`getErrorBehavior()` Retrieves the behavior to exhibit if errors are encountered.
`java.lang.String`	`getExtendedRequestName()` Retrieves the user-friendly name for the extended request, if available.
`java.util.List<LDAPRequest>`	`getRequests()` Retrieves the set of requests to be processed.
`MultiUpdateExtendedResult`	`process(LDAPConnection connection, int depth)` Sends this extended request to the directory server over the provided connection and returns the associated response.
`void`	`toString(java.lang.StringBuilder buffer)` Appends a string representation of this request to the provided buffer.

Methods inherited from class com.unboundid.ldap.sdk.ExtendedRequest
encodeProtocolOp, getLastMessageID, getOID, getOperationType, getProtocolOpType, getValue, hasValue, responseReceived, toCode, writeTo

Methods inherited from class com.unboundid.ldap.sdk.LDAPRequest
followReferrals, getControl, getControlList, getControls, getIntermediateResponseListener, getReferralConnector, getReferralConnectorInternal, getReferralDepth, getResponseTimeoutMillis, hasControl, hasControl, setFollowReferrals, setIntermediateResponseListener, setReferralConnector, setReferralDepth, setResponseTimeoutMillis, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - MULTI_UPDATE_REQUEST_OID
```
@NotNull
public static final java.lang.String MULTI_UPDATE_REQUEST_OID
```
    The OID (1.3.6.1.4.1.30221.2.6.17) for the multi-update extended request.
    
    See Also:
    
    Constant Field Values
- 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.
  - getErrorBehavior
```
@NotNull
public MultiUpdateErrorBehavior getErrorBehavior()
```
    Retrieves the behavior to exhibit if errors are encountered.
    
    Returns:
    
    The behavior to exhibit if errors are encountered.
  - getRequests
```
@NotNull
public java.util.List<LDAPRequest> getRequests()
```
    Retrieves the set of requests to be processed.
    
    Returns:
    
    The set of requests to be processed.
  - duplicate
```
@NotNull
public MultiUpdateExtendedRequest duplicate()
```
    Creates a new instance of this LDAP request that may be modified without impacting 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
    
    Returns:
    
    A new instance of this LDAP request that may be modified without impacting this request.
  - 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.
  - toString
```
public void toString(@NotNull
                     java.lang.StringBuilder buffer)
```
    Appends a string representation of this request to the provided buffer.
    
    Specified by:
    
    toString in interface ProtocolOp
    
    Specified by:
    
    toString in interface ReadOnlyLDAPRequest
    
    Overrides:
    
    toString in class ExtendedRequest
    
    Parameters:
    
    buffer - The buffer to which to append a string representation of this request.

Class MultiUpdateExtendedRequest

Example

Field Summary

Fields inherited from class com.unboundid.ldap.sdk.ExtendedRequest

Constructor Summary

Method Summary

Methods inherited from class com.unboundid.ldap.sdk.ExtendedRequest

Methods inherited from class com.unboundid.ldap.sdk.LDAPRequest

Methods inherited from class java.lang.Object

Field Detail

MULTI_UPDATE_REQUEST_OID

Constructor Detail

MultiUpdateExtendedRequest

MultiUpdateExtendedRequest

MultiUpdateExtendedRequest

MultiUpdateExtendedRequest

Method Detail

process

getErrorBehavior

getRequests

duplicate

duplicate

getExtendedRequestName

toString