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}