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}