Package com.unboundid.ldap.sdk.unboundidds.controls

Class JoinRequestControl

java.lang.Object
com.unboundid.ldap.sdk.Control
com.unboundid.ldap.sdk.unboundidds.controls.JoinRequestControl
All Implemented Interfaces:
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 the JoinRequestValue 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:

  • Field Details

  • Constructor Details

    • 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 Details

    • 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 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.

    • 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, the oid 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 the value-base64 and value-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 the value-base64 and value-json fields must be present, and if the value-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 the base-dn-type value was "use-custom-base-dn". This field must be present if the base-dn-type value was "use-custom-base-dn", and it must be absent for other base-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", or derefAlways". 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-level value-json field (optionally including another nested-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 class Control
      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 be null.
      strict - Indicates whether to use strict mode when decoding the provided JSON object. If this is true, then this method will throw an exception if the provided JSON object contains any unrecognized fields. If this is false, 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.

    • toString

      public void toString(@NotNull 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.