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-2014 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.proxy.types;
028
029
030
031 import java.util.List;
032
033 import com.unboundid.directory.sdk.common.types.ClientContext;
034 import com.unboundid.directory.sdk.common.types.OperationContext;
035 import com.unboundid.ldap.sdk.DN;
036 import com.unboundid.ldap.sdk.Filter;
037 import com.unboundid.ldap.sdk.LDAPException;
038 import com.unboundid.ldap.sdk.SearchResultEntry;
039 import com.unboundid.ldap.sdk.SearchScope;
040 import com.unboundid.util.NotExtensible;
041 import com.unboundid.util.ObjectPair;
042 import com.unboundid.util.ThreadSafety;
043 import 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)
054 public interface EntryBalancingRequestProcessor
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 }