001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2015-2016 ForgeRock AS. 015 */ 016package org.forgerock.opendj.ldap.spi; 017 018import java.io.Closeable; 019import java.util.List; 020 021import javax.net.ssl.SSLContext; 022 023import org.forgerock.opendj.ldap.ConnectionEventListener; 024import org.forgerock.opendj.ldap.IntermediateResponseHandler; 025import org.forgerock.opendj.ldap.LdapException; 026import org.forgerock.opendj.ldap.LdapPromise; 027import org.forgerock.opendj.ldap.SearchResultHandler; 028import org.forgerock.opendj.ldap.requests.AbandonRequest; 029import org.forgerock.opendj.ldap.requests.AddRequest; 030import org.forgerock.opendj.ldap.requests.BindRequest; 031import org.forgerock.opendj.ldap.requests.CompareRequest; 032import org.forgerock.opendj.ldap.requests.DeleteRequest; 033import org.forgerock.opendj.ldap.requests.ExtendedRequest; 034import org.forgerock.opendj.ldap.requests.ModifyDNRequest; 035import org.forgerock.opendj.ldap.requests.ModifyRequest; 036import org.forgerock.opendj.ldap.requests.SearchRequest; 037import org.forgerock.opendj.ldap.requests.UnbindRequest; 038import org.forgerock.opendj.ldap.responses.BindResult; 039import org.forgerock.opendj.ldap.responses.CompareResult; 040import org.forgerock.opendj.ldap.responses.ExtendedResult; 041import org.forgerock.opendj.ldap.responses.Result; 042import org.forgerock.util.promise.Promise; 043 044/** 045 * LDAP connection interface which implementations of {@link LDAPConnectionFactoryImpl} should implement. 046 */ 047public interface LDAPConnectionImpl extends Closeable { 048 049 /** 050 * Abandons the unfinished operation identified in the provided abandon request. 051 * 052 * @param request 053 * The request identifying the operation to be abandoned. 054 * @return A promise whose result is Void. 055 * @throws UnsupportedOperationException 056 * If this connection does not support abandon operations. 057 * @throws IllegalStateException 058 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 059 * @throws NullPointerException 060 * If {@code request} was {@code null}. 061 * @see org.forgerock.opendj.ldap.Connection#abandonAsync(AbandonRequest) 062 */ 063 LdapPromise<Void> abandonAsync(AbandonRequest request); 064 065 /** 066 * Asynchronously adds an entry to the Directory Server using the provided add request. 067 * 068 * @param request 069 * The add request. 070 * @param intermediateResponseHandler 071 * An intermediate response handler which can be used to process any intermediate responses as they are 072 * received, may be {@code null}. 073 * @return A promise representing the result of the operation. 074 * @throws UnsupportedOperationException 075 * If this connection does not support add operations. 076 * @throws IllegalStateException 077 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 078 * @throws NullPointerException 079 * If {@code request} was {@code null}. 080 * @see org.forgerock.opendj.ldap.Connection#addAsync(AddRequest, IntermediateResponseHandler) 081 */ 082 LdapPromise<Result> addAsync(AddRequest request, IntermediateResponseHandler intermediateResponseHandler); 083 084 /** 085 * Registers the provided connection event listener so that it will be notified when this connection is closed by 086 * the application, receives an unsolicited notification, or experiences a fatal error. 087 * 088 * @param listener 089 * The listener which wants to be notified when events occur on this connection. 090 * @throws IllegalStateException 091 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 092 * @throws NullPointerException 093 * If the {@code listener} was {@code null}. 094 * @see org.forgerock.opendj.ldap.Connection#addConnectionEventListener(ConnectionEventListener) 095 */ 096 void addConnectionEventListener(ConnectionEventListener listener); 097 098 /** 099 * Asynchronously authenticates to the Directory Server using the provided bind request. 100 * 101 * @param request 102 * The bind request. 103 * @param intermediateResponseHandler 104 * An intermediate response handler which can be used to process any intermediate responses as they are 105 * received, may be {@code null}. 106 * @return A promise representing the result of the operation. 107 * @throws UnsupportedOperationException 108 * If this connection does not support bind operations. 109 * @throws IllegalStateException 110 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 111 * @throws NullPointerException 112 * If {@code request} was {@code null}. 113 * @see org.forgerock.opendj.ldap.Connection#bindAsync(BindRequest, IntermediateResponseHandler) 114 */ 115 LdapPromise<BindResult> bindAsync(BindRequest request, IntermediateResponseHandler intermediateResponseHandler); 116 117 /** 118 * Releases any resources associated with this connection. 119 * <p/> 120 * Calling {@code close} on a connection that is already closed has no effect. 121 * @see org.forgerock.opendj.ldap.Connection#close() 122 */ 123 @Override 124 void close(); 125 126 /** 127 * Releases any resources associated with this connection. 128 * <p/> 129 * Calling {@code close} on a connection that is already closed has no effect. 130 * 131 * @param request 132 * The unbind request to use in the case where a physical connection is closed. 133 * @param reason 134 * A reason describing why the connection was closed. 135 * @throws NullPointerException 136 * If {@code request} was {@code null}. 137 * @see org.forgerock.opendj.ldap.Connection#close(UnbindRequest, String) 138 */ 139 void close(UnbindRequest request, String reason); 140 141 /** 142 * Asynchronously compares an entry in the Directory Server using the provided compare request. 143 * 144 * @param request 145 * The compare request. 146 * @param intermediateResponseHandler 147 * An intermediate response handler which can be used to process any intermediate responses as they are 148 * received, may be {@code null}. 149 * @return A promise representing the result of the operation. 150 * @throws UnsupportedOperationException 151 * If this connection does not support compare operations. 152 * @throws IllegalStateException 153 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 154 * @throws NullPointerException 155 * If {@code request} was {@code null}. 156 * @see org.forgerock.opendj.ldap.Connection#compareAsync(CompareRequest, IntermediateResponseHandler) 157 */ 158 LdapPromise<CompareResult> compareAsync( 159 CompareRequest request, IntermediateResponseHandler intermediateResponseHandler); 160 161 /** 162 * Asynchronously deletes an entry from the Directory Server using the provided delete request. 163 * 164 * @param request 165 * The delete request. 166 * @param intermediateResponseHandler 167 * An intermediate response handler which can be used to process any intermediate responses as they are 168 * received, may be {@code null}. 169 * @return A promise representing the result of the operation. 170 * @throws UnsupportedOperationException 171 * If this connection does not support delete operations. 172 * @throws IllegalStateException 173 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 174 * @throws NullPointerException 175 * If {@code request} was {@code null}. 176 * @see org.forgerock.opendj.ldap.Connection#deleteAsync(DeleteRequest, IntermediateResponseHandler) 177 */ 178 LdapPromise<Result> deleteAsync(DeleteRequest request, IntermediateResponseHandler intermediateResponseHandler); 179 180 /** 181 * Installs the TLS/SSL security layer on the underlying connection. The TLS/SSL security layer will be installed 182 * beneath any existing connection security layers and can only be installed at most once. 183 * 184 * @param sslContext 185 * The {@code SSLContext} which should be used to secure the 186 * @param protocols 187 * Names of all the protocols to enable or {@code null} to use the default protocols. 188 * @param suites 189 * Names of all the suites to enable or {@code null} to use the default cipher suites. 190 * @return A promise which will complete once the SSL handshake has completed. 191 * @throws IllegalStateException 192 * If the TLS/SSL security layer has already been installed. 193 */ 194 Promise<Void, LdapException> enableTLS(SSLContext sslContext, List<String> protocols, List<String> suites); 195 196 /** 197 * Asynchronously performs the provided extended request in the Directory Server. 198 * 199 * @param <R> 200 * The type of result returned by the extended request. 201 * @param request 202 * The extended request. 203 * @param intermediateResponseHandler 204 * An intermediate response handler which can be used to process any intermediate responses as they are 205 * received, may be {@code null}. 206 * @return A promise representing the result of the operation. 207 * @throws UnsupportedOperationException 208 * If this connection does not support extended operations. 209 * @throws IllegalStateException 210 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 211 * @throws NullPointerException 212 * If {@code request} was {@code null}. 213 * @see org.forgerock.opendj.ldap.Connection#extendedRequestAsync(ExtendedRequest, IntermediateResponseHandler) 214 */ 215 <R extends ExtendedResult> LdapPromise<R> extendedRequestAsync( 216 ExtendedRequest<R> request, IntermediateResponseHandler intermediateResponseHandler); 217 218 /** 219 * Indicates whether this connection has been explicitly closed by calling {@code close}. This method will 220 * not return {@code true} if a fatal error has occurred on the connection unless {@code close} has been called. 221 * 222 * @return {@code true} if this connection has been explicitly closed by calling {@code close}, or {@code false} 223 * otherwise. 224 * @see org.forgerock.opendj.ldap.Connection#isClosed() 225 */ 226 boolean isClosed(); 227 228 /** 229 * Returns {@code true} if this connection has not been closed and no fatal errors have been detected. This method 230 * is guaranteed to return {@code false} only when it is called after the method {@code close} has been called. 231 * 232 * @return {@code true} if this connection is valid, {@code false} otherwise. 233 * @see org.forgerock.opendj.ldap.Connection#isValid() 234 */ 235 boolean isValid(); 236 237 /** 238 * Asynchronously modifies an entry in the Directory Server using the provided modify request. 239 * 240 * @param request 241 * The modify request. 242 * @param intermediateResponseHandler 243 * An intermediate response handler which can be used to process any intermediate responses as they are 244 * received, may be {@code null}. 245 * @return A promise representing the result of the operation. 246 * @throws UnsupportedOperationException 247 * If this connection does not support modify operations. 248 * @throws IllegalStateException 249 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 250 * @throws NullPointerException 251 * If {@code request} was {@code null}. 252 * @see org.forgerock.opendj.ldap.Connection#modifyAsync(ModifyRequest, IntermediateResponseHandler) 253 */ 254 LdapPromise<Result> modifyAsync(ModifyRequest request, IntermediateResponseHandler intermediateResponseHandler); 255 256 /** 257 * Asynchronously renames an entry in the Directory Server using the provided modify DN request. 258 * 259 * @param request 260 * The modify DN request. 261 * @param intermediateResponseHandler 262 * An intermediate response handler which can be used to process any intermediate responses as they are 263 * received, may be {@code null}. 264 * @return A promise representing the result of the operation. 265 * @throws UnsupportedOperationException 266 * If this connection does not support modify DN operations. 267 * @throws IllegalStateException 268 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 269 * @throws NullPointerException 270 * If {@code request} was {@code null}. 271 * @see org.forgerock.opendj.ldap.Connection#modifyDNAsync(ModifyDNRequest, IntermediateResponseHandler) 272 */ 273 LdapPromise<Result> modifyDNAsync( 274 ModifyDNRequest request, IntermediateResponseHandler intermediateResponseHandler); 275 276 /** 277 * Removes the provided connection event listener from this connection so that it will no longer be notified when 278 * this connection is closed by the application, receives an unsolicited notification, or experiences a fatal 279 * error. 280 * 281 * @param listener 282 * The listener which no longer wants to be notified when events occur on this connection. 283 * @throws NullPointerException 284 * If the {@code listener} was {@code null}. 285 * @see org.forgerock.opendj.ldap.Connection#removeConnectionEventListener(ConnectionEventListener) 286 */ 287 void removeConnectionEventListener(ConnectionEventListener listener); 288 289 /** 290 * Asynchronously searches the Directory Server using the provided search request. 291 * 292 * @param request 293 * The search request. 294 * @param intermediateResponseHandler 295 * An intermediate response handler which can be used to process any intermediate responses as they are 296 * received, may be {@code null}. 297 * @param entryHandler 298 * A search result handler which can be used to asynchronously process the search result entries and 299 * references as they are received, may be {@code null}. 300 * @return A promise representing the result of the operation. 301 * @throws UnsupportedOperationException 302 * If this connection does not support search operations. 303 * @throws IllegalStateException 304 * If this connection has already been closed, i.e. if {@code isClosed() == true}. 305 * @throws NullPointerException 306 * If {@code request} was {@code null}. 307 * @see org.forgerock.opendj.ldap.Connection#searchAsync(SearchRequest, IntermediateResponseHandler, 308 * SearchResultHandler) 309 */ 310 LdapPromise<Result> searchAsync( 311 SearchRequest request, 312 IntermediateResponseHandler intermediateResponseHandler, 313 SearchResultHandler entryHandler); 314}