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-2013 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.proxy.types;
028
029
030
031 import com.unboundid.directory.sdk.common.types.OperationType;
032 import com.unboundid.ldap.sdk.AddRequest;
033 import com.unboundid.ldap.sdk.CompareRequest;
034 import com.unboundid.ldap.sdk.CompareResult;
035 import com.unboundid.ldap.sdk.DeleteRequest;
036 import com.unboundid.ldap.sdk.LDAPConnection;
037 import com.unboundid.ldap.sdk.LDAPConnectionOptions;
038 import com.unboundid.ldap.sdk.LDAPException;
039 import com.unboundid.ldap.sdk.LDAPResult;
040 import com.unboundid.ldap.sdk.ModifyRequest;
041 import com.unboundid.ldap.sdk.ModifyDNRequest;
042 import com.unboundid.ldap.sdk.SearchRequest;
043 import com.unboundid.ldap.sdk.SearchResult;
044 import com.unboundid.util.NotExtensible;
045 import com.unboundid.util.ThreadSafety;
046 import com.unboundid.util.ThreadSafetyLevel;
047
048
049
050 /**
051 * This interface defines a set of methods that may be used to interact with an
052 * LDAP external server which acts as a backend server accessed through the
053 * Directory Proxy Server.
054 */
055 @NotExtensible()
056 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
057 public interface BackendServer
058 {
059 /**
060 * Retrieves the DN of the configuration entry in which this LDAP external
061 * server is defined.
062 *
063 * @return The DN of the configuration entry in which this LDAP external
064 * server is defined.
065 */
066 String getConfigEntryDN();
067
068
069
070 /**
071 * Creates a new connection to the associated directory server which is
072 * authenticated and/or secured in accordance with the LDAP external server
073 * configuration. The caller will be responsible for closing the connection
074 * when it is no longer needed.
075 *
076 * @param options The set of options to use for the connection. It may be
077 * {@code null} if a default set of connection options should
078 * be used.
079 * @param purpose A message with information about the purpose for this
080 * connection. This message will be included in the
081 * administrative operation control sent to the server (if
082 * the server supports that control) for any operations
083 * processed during the course of preparing the connection.
084 *
085 * @return The newly-created connection.
086 *
087 * @throws LDAPException If a problem is encountered while attempting to
088 * create the connection.
089 */
090 LDAPConnection createNewConnection(final LDAPConnectionOptions options,
091 final String purpose)
092 throws LDAPException;
093
094
095
096 /**
097 * Retrieves the location assigned to this LDAP external server, if any.
098 *
099 * @return The location assigned to this LDAP external server, or
100 * {@code null} if no location has been assigned.
101 */
102 Location getLocation();
103
104
105
106 /**
107 * Retrieves the address for this LDAP external server.
108 *
109 * @return The address for this LDAP external server.
110 */
111 String getServerAddress();
112
113
114
115 /**
116 * Retrieves the port for this LDAP external server.
117 *
118 * @return The port for this LDAP external server.
119 */
120 int getServerPort();
121
122
123
124 /**
125 * Indicates whether this LDAP external server is in the same location as the
126 * Directory Proxy Server that is referencing it.
127 *
128 * @return {@code true} if this LDAP external server is in the same location
129 * as the Directory Proxy Server that is referencing it, or
130 * {@code false} if it is in a different location or no location has
131 * been assigned.
132 */
133 boolean isLocal();
134
135
136
137 /**
138 * Retrieves the number of operations which are currently being processed
139 * against the LDAP external server through the local Directory Proxy Server
140 * instance. Note that this value will not include operations processed
141 * against the server from other Directory Proxy Server instances or any other
142 * kind of client, nor will it include any operations which may be in progress
143 * on connections created from the {@link #createNewConnection} method.
144 *
145 * @return The number of operations which are currently being processed
146 * against the LDAP external server through the local Directory Proxy
147 * Server instance.
148 */
149 int getActiveOperations();
150
151
152
153 /**
154 * Retrieves the health check result currently assigned to this LDAP external
155 * server.
156 *
157 * @return The health check result currently assigned to this LDAP external
158 * server.
159 */
160 HealthCheckResult getHealthCheckResult();
161
162
163
164 /**
165 * Indicates whether this LDAP external server currently has a health check
166 * state of AVAILABLE.
167 *
168 * @return {@code true} if this LDAP external server currently has a health
169 * check state of AVAILABLE, or {@code false} if not.
170 */
171 boolean isAvailable();
172
173
174
175 /**
176 * Indicates whether this LDAP external server may be used to process
177 * operations of the specified type.
178 *
179 * @param t The operation type for which to make the determination.
180 *
181 * @return {@code true} if this LDAP external server may be used to process
182 * operations of the specified type, or {@code false} if not.
183 */
184 boolean supportsOperation(final OperationType t);
185
186
187
188 /**
189 * Sends the provided add request to the backend server without altering the
190 * request or result in any way. It will use a pooled connection
191 * authenticated as the proxy user, and the provided request must not alter
192 * the state of the connection in any way.
193 *
194 * @param addRequest The add request to be processed.
195 *
196 * @return The result of processing the add operation.
197 *
198 * @throws LDAPException If an error occurred while processing the add
199 * request.
200 */
201 LDAPResult addUnaltered(final AddRequest addRequest)
202 throws LDAPException;
203
204
205
206 /**
207 * Sends the provided compare request to the backend server without altering
208 * the request or result in any way. It will use a pooled connection
209 * authenticated as the proxy user, and the provided request must not alter
210 * the state of the connection in any way.
211 *
212 * @param compareRequest The compare request to be processed.
213 *
214 * @return The result of processing the compare operation.
215 *
216 * @throws LDAPException If an error occurred while processing the compare
217 * request.
218 */
219 CompareResult compareUnaltered(final CompareRequest compareRequest)
220 throws LDAPException;
221
222
223
224 /**
225 * Sends the provided delete request to the backend server without altering
226 * the request or result in any way. It will use a pooled connection
227 * authenticated as the proxy user, and the provided request must not alter
228 * the state of the connection in any way.
229 *
230 * @param deleteRequest The delete request to be processed.
231 *
232 * @return The result of processing the delete operation.
233 *
234 * @throws LDAPException If an error occurred while processing the delete
235 * request.
236 */
237 LDAPResult deleteUnaltered(final DeleteRequest deleteRequest)
238 throws LDAPException;
239
240
241
242 /**
243 * Sends the provided modify request to the backend server without altering
244 * the request or result in any way. It will use a pooled connection
245 * authenticated as the proxy user, and the provided request must not alter
246 * the state of the connection in any way.
247 *
248 * @param modifyRequest The modify request to be processed.
249 *
250 * @return The result of processing the modify operation.
251 *
252 * @throws LDAPException If an error occurred while processing the modify
253 * request.
254 */
255 LDAPResult modifyUnaltered(final ModifyRequest modifyRequest)
256 throws LDAPException;
257
258
259
260 /**
261 * Sends the provided modify DN request to the backend server without altering
262 * the request or result in any way. It will use a pooled connection
263 * authenticated as the proxy user, and the provided request must not alter
264 * the state of the connection in any way.
265 *
266 * @param modifyDNRequest The modify DN request to be processed.
267 *
268 * @return The result of processing the modify DN operation.
269 *
270 * @throws LDAPException If an error occurred while processing the modify DN
271 * request.
272 */
273 LDAPResult modifyDNUnaltered(final ModifyDNRequest modifyDNRequest)
274 throws LDAPException;
275
276
277
278 /**
279 * Sends the provided search request to the backend server without altering
280 * the request or result in any way. It will use a pooled connection
281 * authenticated as the proxy user, and the provided request must not alter
282 * the state of the connection in any way.
283 *
284 * @param searchRequest The search request to be processed.
285 *
286 * @return The result of processing the search operation.
287 *
288 * @throws LDAPException If an error occurred while processing the search
289 * request.
290 */
291 SearchResult searchUnaltered(final SearchRequest searchRequest)
292 throws LDAPException;
293 }