com.unboundid.ldap.sdk.unboundidds.controls
Class RouteToBackendSetRequestControl
java.lang.Object
com.unboundid.ldap.sdk.Control
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:
- For an add request that uses absolute routing, exactly one target
backend set ID must be specified, and the request will be sent only to
that backend set.
WARNING: The use of absolute routing for an add
operation bypasses the check to ensure that no entry already exists
with the same DN as the new entry, so it is possible that an add
performed immediately below the balancing point could result in
creating an entry in one backend set with the same DN as another entry
in a different backend set. Similarly, if the entry-balancing request
processor is configured to broadcast add operations outside the
balancing point rather than relying on those adds to be replicated,
then it is strongly recommended that absolute routing not be used for
add operations outside the balancing point because that will cause the
entry to be added to only one backend set rather than to all backend
sets.
- For an add request that uses a routing hint, exactly one target backend
set ID must be specified for the first guess, although any number of
fallback set IDs may be specified. For entries immediately below the
balancing point, the routing hint will be used instead of a placement
algorithm in order to select which backend set should hold the entry
(and the fallback sets will not be used). For entries more than one
level below the balancing point, the routing hint will be used in lieu
of the global index as an attempt to determine where the parent entry
exists, and the fallback sets may be used if the parent entry doesn't
exist in the first guess set. For entries outside the balancing point,
if the entry-balancing request processor is configured to add entries
to one set and allow them to be replicated to other sets, then the
first guess hint will be used to select the set to which the entry will
be added (and the fallback sets will not be used). An add operation
with a routing hint cannot be used to create multiple entries with the
same DN in different backend sets, nor can it cause an entry outside
the balancing point to exist in only one backend set.
- For a simple bind request that uses absolute routing, exactly one
target backend set ID must be specified, and the request will be sent
only to that backend set. If the bind fails in that set, even if the
failure is because the target entry does not exist in that backend set,
then the failure will be returned to the client rather than attempting
the operation in a different backend set.
- For a simple bind request that uses a routing hint, exactly one target
backend set ID must be specified for the first guess, although any
number of fallback set IDs may be specified. If the bind fails in the
first guess set, it may be re-attempted in the fallback sets.
- For a compare request that uses absolute routing, exactly one target
backend set ID must be specified, and the request will be sent only to
that backend set. If the compare fails in that set, even if the
failure is because the target entry does not exist in that set, then
the failure will be returned to the client rather than attempting the
operation in a different backend set.
- For a compare request that uses a routing hint, exactly one target
backend set ID must be specified for the first guess, although any
number of fallback set IDs may be specified. If the compare operation
fails in the first guess set in a way that suggests the target entry
does not exist in that backend set, then it will be re-attempted in the
fallback sets.
- For a delete request that uses absolute routing, exactly one target
backend set ID must be specified, and the request will be sent only to
that backend set. If the delete fails in that set, even if the failure
is because the target entry does not exist in that set, then the
failure will be returned to the client rather than attempting the
operation in a different backend set.
WARNING: If the entry-balancing request processor is configured
to broadcast delete operations outside the balancing point rather than
relying on those deletes to be replicated, then it is strongly
recommended that absolute routing not be used for delete operations
outside the balancing point because that will cause the entry to be
deleted in only one backend set and will remain in all other backend
sets.
- For a delete request that uses a routing hint, exactly one target
backend set ID must be specified for the first guess, although any
number of fallback set IDs may be specified. For entries below the
balancing point, the routing hint will be used in lieu of the global
index in order to determine which backend set contains the target
entry. If the delete fails in the first guess set in a way that
suggests that the target entry does not exist in that backend set, then
it will be re-attempted in the fallback sets.
For entries outside the balancing point, if the entry-balancing request
processor is configured to delete entries from only one backend set
and allow that delete to be replicated to all other sets, then the
routing hint may be used to select the set from which that entry will
be deleted. A delete operation with a routing hint cannot be used to
cause an entry outside the balancing point to be removed from only one
backend set while leaving it in the remaining sets.
- For an atomic multi-update extended request, only absolute routing is
supported, and the route to backend set request control must be
attached to the extended operation itself and not to any of the
requests contained inside the multi-update. Exactly one backend set ID
must be specified, and the multi-update request will be sent only to
that backend set.
- For a non-atomic multi-update extended request, the extended operation
must not include a route to backend set request control. However, any
or all of the requests inside the multi-update request may include a
route to backend set request control, and in that case it will be
treated in the same way as for a request of the same type not
included in multi-update request (e.g., if a multi-update extended
operation includes an add request with a route to backend set request
control, then that route control will have the same effect as for the
same add request with the same control processed outside a multi-update
operation).
- For an extended request that will be processed by a proxied extended
operation handler, the request may include a route to backend set
request control and that control will be used to select the target
backend sets instead of the proxied extended operation handler's
selectBackendSets
method.
- For a modify request that uses absolute routing, exactly one target
backend set ID must be specified, and the request will be sent only to
that backend set. If the modify fails in that set, even if the failure
is because the target entry does not exist in that set, then the
failure will be returned to the client rather than attempting the
operation in a different backend set.
WARNING: When processing a modify operation against the
balancing point entry itself, the Directory Proxy Server will typically
send that modify request to all backend sets to ensure that it is
properly applied everywhere. However, with an absolute routing
request, the modify operation will be sent only to one backend set,
which will cause the entry in that set to be out of sync with the entry
in all other sets. It is therefore strongly recommended that absolute
routing not be used for modify operations that target the balancing
point entry. Similarly, if the entry-balancing request processor is
configured to broadcast modify operations targeting entries outside the
balancing point to all backend sets rather than having those modify
operations replicated to the other backend sets, it is strongly
recommended that absolute routing not be used for those operations
because the request will be sent to only one set, causing the entry in
that set to be out of sync with the corresponding entry in other
backend sets.
- For a modify request that uses a routing hint, exactly one target
backend set ID must be specified for the first guess, although any
number of fallback set IDs may be specified. For entries below the
balancing point, the routing hint will be used in lieu of the global
index in order to determine which backend set contains the target
entry. If the modify attempt fails in the first guess set in a way
that suggests the target entry does not exist in that backend set, then
it will be re-attempted in the fallback sets.
For modify operations that target the balancing point entry itself, the
entry-balancing request processor will send the request to all backend
sets, and the routing hint will not be used. Similarly, for entries
outside the balancing point, if the entry-balancing request processor
is configured to modify entries in only one backend set and allow that
modify operation to be replicated to all other sets, then the routing
hint may be used to select the set in which that entry will be
modified. A modify operation with a routing hint cannot be used to
cause an entry at or outside the balancing point to be updated in only
one backend set, leaving it out of sync with the corresponding entry in
the remaining sets.
- For a modify DN request that uses absolute routing, exactly one target
backend set ID must be specified, and the request wil be sent only to
that backend set. If the modify DN operation fails in that set, even
if the failure is because the target entry does not exist in that set,
then the failure will be returned to the client rather than attempting
the operation in a different backend set.
WARNING: Processing a modify DN operation with absolute routing
bypasses the check to ensure that the new DN for the target entry does
not conflict with the DN for an entry that exists in any other backend
set. As a result, you are strongly discouraged from using absolute
routing for any modify DN operation that would cause the new DN for the
entry to be exactly one level below the balancing point. Further, for
entries that exist outside the balancing point, if the entry-balancing
request processor is configured to broadcast modify DN operations
rather than expecting them to be replicated to the other backend sets,
a modify DN operation with absolute routing would cause the change to
be applied only in one backend set, leaving it out of sync with the
other sets.
- For a modify DN request that uses a routing hint, exactly one target
backend set ID must be specified for the first guess, although any
number of fallback set IDs may be specified. For entries below the
balancing point, the routing hint will be used in lieu of the global
index in order to determine which backend set contains the target
entry. If the modify attempt fails in the first guess set in a way
that suggests the target entry does not exist in that backend set, then
it will be re-attempted in the fallback sets.
For entries outside the balancing point, if the entry-balancing request
processor is configured to process modify DN operations in one backend
set and allow them to be replicated to other backend sets, then the
routing hint will be used to select which backend set should receive
the modify DN request. A modify DN operation with a routing hint
cannot be used to create a conflict in which the same DN exists in
multiple backend sets, or a case in which a modify DN operation outside
the balancing point leaves one backend set out of sync with the other
sets.
- For a search request that uses absolute routing, there may be multiple
target backend set IDs only if the scope of the search may include
data from multiple backend sets (i.e., the base DN is at or above the
balancing point, and the scope include entries at least one level below
the balancing point entry). If the base and scope of the search allow
it to match only entries at or above the balancing point or only
entries within one backend set, then the absolute routing request must
target exactly one backend set.
- For a search request that uses a routing hint, exactly one target
backend set ID must be specified for the first guess, although any
number of fallback set IDs may be specified. The routing hint will
only be used for cases in which the entire scope of the search is
contained entirely within a backend set (i.e., the entire scope is
at or above the balancing point, or the entire scope is at least one
level below the balancing point).
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
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 |
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
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.
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.