Class JoinRequestControl
- java.lang.Object
-
- com.unboundid.ldap.sdk.Control
-
- com.unboundid.ldap.sdk.unboundidds.controls.JoinRequestControl
-
- All Implemented Interfaces:
java.io.Serializable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class JoinRequestControl extends Control
This class provides an implementation of an LDAP control which can be included in a search request to indicate that search result entries should be returned along with related entries based on a given set of criteria, much like an SQL join in a relational database.
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.
This request control has an OID of 1.3.6.1.4.1.30221.2.5.9, and the criticality is generally true. It must have a value, and the format of that value is described in the class-level documentation for theJoinRequestValue
class.
Example
Consider the case in which user entries include an account number, but additional information about those accounts are available in separate entries. If you wish to retrieve both the user and account entries for a user given only a user ID, then you may accomplish that using the join request control as follows:SearchRequest searchRequest = new SearchRequest( "ou=People,dc=example,dc=com", SearchScope.SUB, Filter.createEqualityFilter("uid", userID)); searchRequest.addControl(new JoinRequestControl(new JoinRequestValue( JoinRule.createEqualityJoin("accountNumber", "accountNumber", false), JoinBaseDN.createUseCustomBaseDN("ou=Accounts,dc=example,dc=com"), SearchScope.SUB, DereferencePolicy.NEVER, null, Filter.createEqualityFilter("objectClass", "accountEntry"), new String[0], false, null))); SearchResult searchResult = connection.search(searchRequest); for (SearchResultEntry userEntry : searchResult.getSearchEntries()) { JoinResultControl c = JoinResultControl.get(userEntry); for (JoinedEntry accountEntry : c.getJoinResults()) { // User userEntry was joined with account accountEntry } }
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
JOIN_REQUEST_OID
The OID (1.3.6.1.4.1.30221.2.5.9) for the join request control.
-
Constructor Summary
Constructors Constructor Description JoinRequestControl(boolean isCritical, JoinRequestValue joinRequestValue)
Creates a new join request control with the provided join request value.JoinRequestControl(Control control)
Creates a new join request control which is decoded from the provided generic control.JoinRequestControl(JoinRequestValue joinRequestValue)
Creates a new join request control with the provided join request value.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static JoinRequestControl
decodeJSONControl(JSONObject controlObject, boolean strict)
Attempts to decode the provided object as a JSON representation of a join request control.java.lang.String
getControlName()
Retrieves the user-friendly name for this control, if available.JoinRequestValue
getJoinRequestValue()
Retrieves the join request value for this join request control.JSONObject
toJSONControl()
Retrieves a representation of this join request control as a JSON object.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, decodeJSONControl, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toString, writeTo
-
-
-
-
Field Detail
-
JOIN_REQUEST_OID
@NotNull public static final java.lang.String JOIN_REQUEST_OID
The OID (1.3.6.1.4.1.30221.2.5.9) for the join request control.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
JoinRequestControl
public JoinRequestControl(@NotNull JoinRequestValue joinRequestValue)
Creates a new join request control with the provided join request value.- Parameters:
joinRequestValue
- The join request value to use for this control.
-
JoinRequestControl
public JoinRequestControl(boolean isCritical, @NotNull JoinRequestValue joinRequestValue)
Creates a new join request control with the provided join request value.- Parameters:
isCritical
- Indicates whether this control should be considered critical.joinRequestValue
- The join request value to use for this control.
-
JoinRequestControl
public JoinRequestControl(@NotNull Control control) throws LDAPException
Creates a new join request control which is decoded from the provided generic control.- Parameters:
control
- The generic control to be decoded as a join request control.- Throws:
LDAPException
- If the provided control cannot be decoded as a virtual attributes only request control.
-
-
Method Detail
-
getJoinRequestValue
@NotNull public JoinRequestValue getJoinRequestValue()
Retrieves the join request value for this join request control.- Returns:
- The join request value for this join request control.
-
getControlName
@NotNull 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 classControl
- Returns:
- The user-friendly name for this control, or the OID if no user-friendly name is available.
-
toJSONControl
@NotNull public JSONObject toJSONControl()
Retrieves a representation of this join request control as a JSON object. The JSON object uses the following fields:-
oid
-- A mandatory string field whose value is the object identifier for this control. For the join request control, the OID is "1.3.6.1.4.1.30221.2.5.9". -
control-name
-- An optional string field whose value is a human-readable name for this control. This field is only intended for descriptive purposes, and when decoding a control, theoid
field should be used to identify the type of control. -
criticality
-- A mandatory Boolean field used to indicate whether this control is considered critical. -
value-base64
-- An optional string field whose value is a base64-encoded representation of the raw value for this join request control. Exactly one of thevalue-base64
andvalue-json
fields must be present. -
value-json
-- An optional JSON object field whose value is a user-friendly representation of the value for this join request control. Exactly one of thevalue-base64
andvalue-json
fields must be present, and if thevalue-json
field is used, then it will use the following fields:-
join-rule
-- A mandatory JSON object field that provides the primary criteria to use when selecting entries to be joined with search result entries. The format for join rule objects will be described in more detail below. -
base-dn-type
-- A mandatory string field that indicates who the server should determine the base DN to use for join processing. The value must be one of "use-search-base-dn
", "use-source-entry-dn
", or "use-custom-base-dn
". -
base-dn-value
-- An optional string field that provides the custom base DN value to use if thebase-dn-type
value was "use-custom-base-dn
". This field must be present if thebase-dn-type
value was "use-custom-base-dn
", and it must be absent for otherbase-dn-type
values. -
scope
-- An optional string field whose value specifies the scope to use for join processing. If present, the value must be one of "baseObject
", "singleLevel
", "wholeSubtree
", or "subordinateSubtree
". If this is not specified, the scope from the search request will be used. -
alias-dereferencing-behavior
-- An optional string field whose value specifies the behavior to use for dereferencing any aliases encountered during join processing. If present, the value must be one of "neverDerefAliases
", "derefInSearching
", "derefInFindingBaseObj
", orderefAlways
". If this is not specified, the dereferencing behavior from the search request will be used. -
size-limit
-- An optional integer field whose value specifies the maximum number of entries that may be joined with any single search result entry. -
filter
-- An optional string field whose value is the string representation of a filter that will be required to match an entry for it to be joined with a search result entry. -
attributes
-- An optional array field whose values are strings that are the names of attributes to include in joined entries. -
require-match
-- A mandatory Boolean field that indicates whether to suppress a search result entry from the set of results to the client if it is not joined with any other entries. -
nested-join
-- An optional JSON object field whose value represents the join criteria for a nested join operation. If present, the fields in this object are the same as the fields that may be used in the top-levelvalue-json
field (optionally including anothernested-jon
element if desired).
-
The following encodings may be used for different types of join rules:-
The fields that may be used for a DN join include:
-
type
-- A mandatory string field whose value must be "dn
". -
source-attribute
-- A mandatory string field whose value is the name of the attribute in the source entry that contains the DNs of the entries to be joined with that entry.
-
-
The fields that may be used for a reverse DN join include:
-
type
-- A mandatory string field whose value must be "reverse-dn
". -
target-attribute
-- A mandatory string field whose value is the name of the attribute in joined entries that contains a value that matches the DN of the source entry.
-
-
The fields that may be used for an equality join include:
-
type
-- A mandatory string field whose value must be "equality
". -
source-attribute
-- A mandatory string field whose value is the name of an attribute in the source entry whose values will be used to identify entries to be joined with that source entry. -
target-attribute
-- A mandatory string field whose value is the name of the attribute in joined entries that must contain at least one of the values from the source attribute in the source entry. -
match-all
-- A mandatory Boolean field that indicates whether to only join entries in which the target attribute contains all of the values of the source attribute.
-
-
The fields that may be used for a contains join include:
-
type
-- A mandatory string field whose value must be "contains
". -
source-attribute
-- A mandatory string field whose value is the name of an attribute in the source entry whose values will be used to identify entries to be joined with that source entry. -
target-attribute
-- A mandatory string field whose value is the name of the attribute in joined entries that must contain at least one value that includes the value of a source attribute as a substring. -
match-all
-- A mandatory Boolean field that indicates whether to only join entries in which the target attribute contains values that contain all of the values of the source attribute as substrings.
-
-
The fields that may be used for an AND join include:
-
type
-- A mandatory string field whose value must be "and
". -
rules
-- A mandatory, non-empty array field whose values are the JSON objects that represent the nested join rules that must all match an entry for it to be joined with the source entry.
-
-
The fields that may be used for an OR join include:
-
type
-- A mandatory string field whose value must be "or
". -
rules
-- A mandatory, non-empty array field whose values are the JSON objects that represent the nested join rules of which at least one must match an entry for it to be joined with the source entry.
-
- Overrides:
toJSONControl
in classControl
- Returns:
- A JSON object that contains a representation of this control.
-
-
decodeJSONControl
@NotNull public static JoinRequestControl decodeJSONControl(@NotNull JSONObject controlObject, boolean strict) throws LDAPException
Attempts to decode the provided object as a JSON representation of a join request control.- Parameters:
controlObject
- The JSON object to be decoded. It must not benull
.strict
- Indicates whether to use strict mode when decoding the provided JSON object. If this istrue
, then this method will throw an exception if the provided JSON object contains any unrecognized fields. If this isfalse
, then unrecognized fields will be ignored.- Returns:
- The join request control that was decoded from the provided JSON object.
- Throws:
LDAPException
- If the provided JSON object cannot be parsed as a valid join request control.
-
-