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