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-2012 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 }