001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt.  If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 *      Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 *      Copyright 2010-2021 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.proxy.types;
028
029
030
031import java.util.List;
032
033import com.unboundid.directory.sdk.common.types.ClientContext;
034import com.unboundid.directory.sdk.common.types.OperationContext;
035import com.unboundid.ldap.sdk.DN;
036import com.unboundid.ldap.sdk.Filter;
037import com.unboundid.ldap.sdk.LDAPException;
038import com.unboundid.ldap.sdk.SearchResultEntry;
039import com.unboundid.ldap.sdk.SearchScope;
040import com.unboundid.util.NotExtensible;
041import com.unboundid.util.ObjectPair;
042import com.unboundid.util.ThreadSafety;
043import com.unboundid.util.ThreadSafetyLevel;
044
045
046
047/**
048 * This interface defines a set of methods that may be used to obtain
049 * information about and interact with an entry-balancing request processor and
050 * its component backend sets and servers.
051 */
052@NotExtensible()
053@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
054public interface EntryBalancingRequestProcessor extends RequestProcessor
055{
056  /**
057   * Retrieves the base DN for the entry-balancing request processor.
058   *
059   * @return  The base DN for the entry-balancing request processor.
060   */
061  DN getRequestProcessorBaseDN();
062
063
064
065  /**
066   * Retrieves the DN of the balancing point for the entry-balancing request
067   * processor.
068   *
069   * @return  The DN of the balancing point for the entry-balancing request
070   *          processor.
071   */
072  DN getBalancingPointBaseDN();
073
074
075
076  /**
077   * Retrieves a list of the backend sets for this entry-balancing request
078   * processor.
079   *
080   * @return  A list of the backend sets for this entry-balancing request
081   *          processor.
082   */
083  List<BackendSet> getBackendSets();
084
085
086
087  /**
088   * Retrieves the backend set in which the entry-balancing global index
089   * believes the entry with the specified DN may exist.
090   *
091   * @param  dn  The DN of the entry for which to retrieve the global index
092   *             hint.
093   *
094   * @return  The backend set in which the entry-balancing global index believes
095   *          the entry with the specified DN may exist, or {@code null} if the
096   *          global index does not have any information that may help locate
097   *          the target entry, or if the provided DN is not below the balancing
098   *          point.
099   */
100  BackendSet getGlobalIndexHint(final DN dn);
101
102
103
104  /**
105   * Retrieves the backend set in which the entry-balancing global index
106   * believes the entry with the specified attribute value may exist.  The value
107   * is expected to be unique across the entire data set.
108   *
109   * @param  attributeType  The name or OID of the attribute type of the
110   *                        attribute for which to retrieve the global index
111   *                        hint.
112   * @param  value          The attribute value for which to retrieve the global
113   *                        index hint.
114   *
115   * @return  The backend set in which the entry-balancing global index believes
116   *          the entry with the specified attribute value may exist, or
117   *          {@code null} if the global index does not have any information
118   *          that may help locate the target entry.
119   */
120  BackendSet getGlobalIndexHint(final String attributeType, final String value);
121
122
123
124  /**
125   * Retrieves the backend set in which the entry-balancing global index
126   * believes the entry with the specified attribute value may exist.  The value
127   * is expected to be unique across the entire data set.
128   *
129   * @param  attributeType  The name or OID of the attribute type of the
130   *                        attribute for which to retrieve the global index
131   *                        hint.
132   * @param  value          The attribute value for which to retrieve the global
133   *                        index hint.
134   *
135   * @return  The backend set in which the entry-balancing global index believes
136   *          the entry with the specified attribute value may exist, or
137   *          {@code null} if the global index does not have any information
138   *          that may help locate the target entry.
139   */
140  BackendSet getGlobalIndexHint(final String attributeType, final byte[] value);
141
142
143
144  /**
145   * Retrieves the specified entry from this entry-balancing request processor.
146   * If a broadcast is needed to find the entry, it will be done in parallel.
147   *
148   * @param  op  Information about the operation currently being processed.
149   *             This must not be {@code null}.
150   * @param  dn  The DN of the entry to retrieve.  It must not be {@code null}.
151   *             If it is at or above the balancing point base DN, then the
152   *             backend set from which the entry will be retrieved is
153   *             undefined.
154   *
155   * @return  An object that pairs the requested entry with information about
156   *          the backend set from which it was retrieved, or {@code null} if
157   *          the specified entry was not found in any backend set.
158   *
159   * @throws  LDAPException  If a problem is encountered while making the
160   *                         determination.
161   */
162  ObjectPair<SearchResultEntry,BackendSet> getEntry(final OperationContext op,
163                                                    final String dn)
164       throws LDAPException;
165
166
167
168  /**
169   * Performs a search for all entries in this entry-balancing request processor
170   * that match the provided criteria.  The search will not be allowed to return
171   * more than 100 entries.
172   *
173   * @param  clientContext  The client context to use when performing the
174   *                        search.  If this is {@code null}, then an internal
175   *                        root user will be used to retrieve the entry.  If it
176   *                        is non-{@code null}, then its authorization identity
177   *                        will be used.
178   * @param  baseDN         The base DN to use for the search.
179   * @param  scope          The scope to use for the search.
180   * @param  filter         The filter to use for the search.
181   * @param  attributes     The set of attributes to request to be included in
182   *                        the entries that are returned.  If this is
183   *                        {@code null} or empty, then all user attributes will
184   *                        be requested.
185   *
186   * @return  A list containing each matching entry paired with the backend set
187   *          from which it was retrieved.
188   *
189   * @throws  LDAPException  If a problem is encountered while performing the
190   *                         search.
191   */
192  List<ObjectPair<SearchResultEntry,BackendSet>> search(
193           final ClientContext clientContext, final String baseDN,
194           final SearchScope scope, final Filter filter,
195           final String... attributes)
196       throws LDAPException;
197}