com.unboundid.ldap.sdk.unboundidds.controls
Class RouteToBackendSetRequestControl

java.lang.Object
  extended by com.unboundid.ldap.sdk.Control
      extended by com.unboundid.ldap.sdk.unboundidds.controls.RouteToBackendSetRequestControl
All Implemented Interfaces:
java.io.Serializable

@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class RouteToBackendSetRequestControl
extends Control

NOTE: This class is part of the Commercial Edition of the UnboundID LDAP SDK for Java. It is not available for use in applications that include only the Standard Edition of the LDAP SDK, and is not supported for use in conjunction with non-UnboundID products.
This class provides a request control which may be used to request that the Directory Proxy Server forward the associated operation to a specific backend set associated with an entry-balancing request processor. It may be either an absolute routing request, indicating that the target backend set(s) are the only ones that may be used to process the operation, or it may be used to provide a routing hint in lieu of accessing the global index.

This control may be used for a number of different kinds of requests, as follows:

The OID for a route to backend set request control is "1.3.6.1.4.1.30221.2.5.35", and the criticality may be either true or false. It must have a value with the following encoding:
   RouteToBackendSetRequest ::= SEQUENCE {
        entryBalancingRequestProcessorID     OCTET STRING,
        backendSets                          CHOICE {
             absoluteRoutingRequest     [0] SET OF OCTET STRING,
             routingHint                [1] SEQUENCE {
                  firstGuessSetIDs     SET OF OCTET STRING,
                  fallbackSetIDs       SET OF OCTET STRING OPTIONAL }
             ... }
        ... }
 
The use of the route to backend set request control will also cause the server to behave as if the get backend set ID request control had been included, so that the get backend set ID response control may be included in operation result and search result entry messages as appropriate.

See Also:
Serialized Form

Field Summary
static java.lang.String ROUTE_TO_BACKEND_SET_REQUEST_OID
          The OID (1.3.6.1.4.1.30221.2.5.35) for the route to server request control.
 
Constructor Summary
RouteToBackendSetRequestControl(Control control)
          Creates a new route to backend set request control that is decoded from the provided generic control.
 
Method Summary
static RouteToBackendSetRequestControl createAbsoluteRoutingRequest(boolean isCritical, java.lang.String entryBalancingRequestProcessorID, java.util.Collection<java.lang.String> backendSetIDs)
          Creates a new route to backend set request control that may be used for absolute routing to the specified collection of backend sets.
static RouteToBackendSetRequestControl createAbsoluteRoutingRequest(boolean isCritical, java.lang.String entryBalancingRequestProcessorID, java.lang.String backendSetID)
          Creates a new route to backend set request control that may be used for absolute routing to the specified backend set.
static RouteToBackendSetRequestControl createRoutingHintRequest(boolean isCritical, java.lang.String entryBalancingRequestProcessorID, java.util.Collection<java.lang.String> firstGuessSetIDs, java.util.Collection<java.lang.String> fallbackSetIDs)
          Creates a new route to backend set request control that may be used to provide a hint as to the backend set(s) to which the operation should be forwarded, and an optional specification of fallback sets.
static RouteToBackendSetRequestControl createRoutingHintRequest(boolean isCritical, java.lang.String entryBalancingRequestProcessorID, java.lang.String firstGuessSetID, java.util.Collection<java.lang.String> fallbackSetIDs)
          Creates a new route to backend set request control that may be used to provide a hint as to the backend set to which the operation should be forwarded, and an optional specification of fallback sets.
 java.util.Set<java.lang.String> getAbsoluteBackendSetIDs()
          Retrieves the collection of backend set IDs for the backend sets to which the request should be forwarded if the control uses absolute routing.
 java.lang.String getControlName()
          Retrieves the user-friendly name for this control, if available.
 java.lang.String getEntryBalancingRequestProcessorID()
          Retrieves the identifier for the entry-balancing request processor with which the backend set IDs are associated.
 java.util.Set<java.lang.String> getRoutingHintFallbackSetIDs()
          Retrieves the collection of backend set IDs to which the request should be forwarded if the control uses a routing hint and an explicit group of fallback sets was specified.
 java.util.Set<java.lang.String> getRoutingHintFirstGuessSetIDs()
          Retrieves the collection of backend set IDs for the first guess of backend sets to which the request should be forwarded if the control uses a routing hint.
 RouteToBackendSetRoutingType getRoutingType()
          Retrieves the type of routing requested by this control.
 void toString(java.lang.StringBuilder buffer)
          Appends a string representation of this LDAP control to the provided buffer.
 
Methods inherited from class com.unboundid.ldap.sdk.Control
decode, decode, decodeControls, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, toString, writeTo
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ROUTE_TO_BACKEND_SET_REQUEST_OID

public static final java.lang.String ROUTE_TO_BACKEND_SET_REQUEST_OID
The OID (1.3.6.1.4.1.30221.2.5.35) for the route to server request control.

See Also:
Constant Field Values
Constructor Detail

RouteToBackendSetRequestControl

public RouteToBackendSetRequestControl(Control control)
                                throws LDAPException
Creates a new route to backend set request control that is decoded from the provided generic control.

Parameters:
control - The control to decode as a route to backend set request control.
Throws:
LDAPException - If the provided control cannot be decoded as a route to backend set request control.
Method Detail

createAbsoluteRoutingRequest

public static RouteToBackendSetRequestControl createAbsoluteRoutingRequest(boolean isCritical,
                                                                           java.lang.String entryBalancingRequestProcessorID,
                                                                           java.lang.String backendSetID)
Creates a new route to backend set request control that may be used for absolute routing to the specified backend set.

Parameters:
isCritical - Indicates whether the control should be marked critical.
entryBalancingRequestProcessorID - The identifier for the entry-balancing request processor with which the backend set ID is associated. It must not be null.
backendSetID - The backend set ID for the backend set to which the request should be forwarded. It must not be null.
Returns:
The route to backend set request control created from the provided information.

createAbsoluteRoutingRequest

public static RouteToBackendSetRequestControl createAbsoluteRoutingRequest(boolean isCritical,
                                                                           java.lang.String entryBalancingRequestProcessorID,
                                                                           java.util.Collection<java.lang.String> backendSetIDs)
Creates a new route to backend set request control that may be used for absolute routing to the specified collection of backend sets.

Parameters:
isCritical - Indicates whether the control should be marked critical.
entryBalancingRequestProcessorID - The identifier for the entry-balancing request processor with which the backend set IDs are associated. It must not be null.
backendSetIDs - The backend set IDs for the backend sets to which the request should be forwarded. It must not be null or empty.
Returns:
The route to backend set request control created from the provided information.

createRoutingHintRequest

public static RouteToBackendSetRequestControl createRoutingHintRequest(boolean isCritical,
                                                                       java.lang.String entryBalancingRequestProcessorID,
                                                                       java.lang.String firstGuessSetID,
                                                                       java.util.Collection<java.lang.String> fallbackSetIDs)
Creates a new route to backend set request control that may be used to provide a hint as to the backend set to which the operation should be forwarded, and an optional specification of fallback sets.

Parameters:
isCritical - Indicates whether the control should be marked critical.
entryBalancingRequestProcessorID - The identifier for the entry-balancing request processor with which the backend set IDs are associated. It must not be null.
firstGuessSetID - The backend set ID for the backend set to try first. It must not be null.
fallbackSetIDs - The backend set ID(s) for the backend set(s) to use if none of the servers in the first guess set returns a success result. If this is null, then the server will use a default fallback set of all backend sets except for the first guess set. If this is not null, then it must also be non-empty.
Returns:
The route to backend set request control created from the provided information.

createRoutingHintRequest

public static RouteToBackendSetRequestControl createRoutingHintRequest(boolean isCritical,
                                                                       java.lang.String entryBalancingRequestProcessorID,
                                                                       java.util.Collection<java.lang.String> firstGuessSetIDs,
                                                                       java.util.Collection<java.lang.String> fallbackSetIDs)
Creates a new route to backend set request control that may be used to provide a hint as to the backend set(s) to which the operation should be forwarded, and an optional specification of fallback sets.

Parameters:
isCritical - Indicates whether the control should be marked critical.
entryBalancingRequestProcessorID - The identifier for the entry-balancing request processor with which the backend set IDs are associated. It must not be null.
firstGuessSetIDs - The backend set ID(s) for the backend set(s) to try first. It must not be null or empty.
fallbackSetIDs - The backend set ID(s) for the backend set(s) to use if none of the servers in the first guess set returns a success result. If this is null, then the server will use a default fallback set of all backend sets not included in the first guess. If this is not null, then it must also be non-empty.
Returns:
The route to backend set request control created from the provided information.

getEntryBalancingRequestProcessorID

public java.lang.String getEntryBalancingRequestProcessorID()
Retrieves the identifier for the entry-balancing request processor with which the backend set IDs are associated.

Returns:
The identifier for the entry-balancing request processor with which the backend set IDs are associated.

getRoutingType

public RouteToBackendSetRoutingType getRoutingType()
Retrieves the type of routing requested by this control.

Returns:
The type of routing requested by this control.

getAbsoluteBackendSetIDs

public java.util.Set<java.lang.String> getAbsoluteBackendSetIDs()
Retrieves the collection of backend set IDs for the backend sets to which the request should be forwarded if the control uses absolute routing.

Returns:
The collection of backend set IDs for the backend sets to which the request should be forwarded if the control uses absolute routing, or null if the control uses a routing hint.

getRoutingHintFirstGuessSetIDs

public java.util.Set<java.lang.String> getRoutingHintFirstGuessSetIDs()
Retrieves the collection of backend set IDs for the first guess of backend sets to which the request should be forwarded if the control uses a routing hint.

Returns:
The collection of backend set IDs for the first guess of backend sets to which the request should be forwarded if the control uses a routing hint, or null if the control uses absolute routing.

getRoutingHintFallbackSetIDs

public java.util.Set<java.lang.String> getRoutingHintFallbackSetIDs()
Retrieves the collection of backend set IDs to which the request should be forwarded if the control uses a routing hint and an explicit group of fallback sets was specified.

Returns:
The collection of backend set IDs to which the request should be forwarded if the control uses a routing hint and an explicit group of fallback sets was specified, or null if the control uses absolute routing or if a default group of fallback sets (all sets not included in the first guess) should be used.

getControlName

public java.lang.String getControlName()
Retrieves the user-friendly name for this control, if available. If no user-friendly name has been defined, then the OID will be returned.

Overrides:
getControlName in class Control
Returns:
The user-friendly name for this control, or the OID if no user-friendly name is available.

toString

public void toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP control to the provided buffer.

Overrides:
toString in class Control
Parameters:
buffer - The buffer to which to append the string representation of this buffer.