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 legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2010 Sun Microsystems, Inc.
025 *      Portions copyright 2011-2014 ForgeRock AS.
026 */
027
028package org.forgerock.opendj.ldap;
029
030import org.forgerock.opendj.ldap.requests.AddRequest;
031import org.forgerock.opendj.ldap.requests.BindRequest;
032import org.forgerock.opendj.ldap.requests.CompareRequest;
033import org.forgerock.opendj.ldap.requests.DeleteRequest;
034import org.forgerock.opendj.ldap.requests.ExtendedRequest;
035import org.forgerock.opendj.ldap.requests.ModifyDNRequest;
036import org.forgerock.opendj.ldap.requests.ModifyRequest;
037import org.forgerock.opendj.ldap.requests.SearchRequest;
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;
042
043/**
044 * A handler interface for processing client requests.
045 * <p>
046 * Implementations must always return results using the provided
047 * {@link LdapResultHandler} unless explicitly permitted.
048 * <p>
049 * For example, an {@link LDAPListener} does not require {@code RequestHandler}
050 * implementations to return results, which may be useful when implementing
051 * abandon operation functionality. Conversely, an access logger implemented as
052 * a {@code RequestHandler} wrapper will require wrapped {@code RequestHandler}s
053 * to always return results, even abandoned results, in order for it to log the
054 * result status.
055 *
056 * @param <C>
057 *            The type of request context.
058 * @see ServerConnectionFactory
059 */
060public interface RequestHandler<C> {
061
062    /**
063     * Invoked when an add request is received from a client.
064     *
065     * @param requestContext
066     *            The request context.
067     * @param request
068     *            The add request.
069     * @param intermediateResponseHandler
070     *            The handler which should be used to send back any intermediate
071     *            responses to the client.
072     * @param resultHandler
073     *            The handler which should be used to send back the result to
074     *            the client.
075     * @throws UnsupportedOperationException
076     *             If this request handler does not handle add requests.
077     */
078    void handleAdd(C requestContext, AddRequest request,
079            IntermediateResponseHandler intermediateResponseHandler,
080            LdapResultHandler<Result> resultHandler);
081
082    /**
083     * Invoked when a bind request is received from a client.
084     *
085     * @param requestContext
086     *            The request context.
087     * @param version
088     *            The protocol version included with the bind request.
089     * @param request
090     *            The bind request.
091     * @param intermediateResponseHandler
092     *            The handler which should be used to send back any intermediate
093     *            responses to the client.
094     * @param resultHandler
095     *            The handler which should be used to send back the result to
096     *            the client.
097     * @throws UnsupportedOperationException
098     *             If this request handler does not handle bind requests.
099     */
100    void handleBind(C requestContext, int version, BindRequest request,
101            IntermediateResponseHandler intermediateResponseHandler,
102            LdapResultHandler<BindResult> resultHandler);
103
104    /**
105     * Invoked when a compare request is received from a client.
106     *
107     * @param requestContext
108     *            The request context.
109     * @param request
110     *            The compare request.
111     * @param intermediateResponseHandler
112     *            The handler which should be used to send back any intermediate
113     *            responses to the client.
114     * @param resultHandler
115     *            The handler which should be used to send back the result to
116     *            the client.
117     * @throws UnsupportedOperationException
118     *             If this request handler does not handle compare requests.
119     */
120    void handleCompare(C requestContext, CompareRequest request,
121            IntermediateResponseHandler intermediateResponseHandler,
122            LdapResultHandler<CompareResult> resultHandler);
123
124    /**
125     * Invoked when a delete request is received from a client.
126     *
127     * @param requestContext
128     *            The request context.
129     * @param request
130     *            The delete request.
131     * @param intermediateResponseHandler
132     *            The handler which should be used to send back any intermediate
133     *            responses to the client.
134     * @param resultHandler
135     *            The handler which should be used to send back the result to
136     *            the client.
137     * @throws UnsupportedOperationException
138     *             If this request handler does not handle delete requests.
139     */
140    void handleDelete(C requestContext, DeleteRequest request,
141            IntermediateResponseHandler intermediateResponseHandler,
142            LdapResultHandler<Result> resultHandler);
143
144    /**
145     * Invoked when an extended request is received from a client.
146     *
147     * @param <R>
148     *            The type of result returned by the extended request.
149     * @param requestContext
150     *            The request context.
151     * @param request
152     *            The extended request.
153     * @param intermediateResponseHandler
154     *            The handler which should be used to send back any intermediate
155     *            responses to the client.
156     * @param resultHandler
157     *            The handler which should be used to send back the result to
158     *            the client.
159     * @throws UnsupportedOperationException
160     *             If this request handler does not handle extended requests.
161     */
162    <R extends ExtendedResult> void handleExtendedRequest(C requestContext,
163            ExtendedRequest<R> request, IntermediateResponseHandler intermediateResponseHandler,
164            LdapResultHandler<R> resultHandler);
165
166    /**
167     * Invoked when a modify request is received from a client.
168     *
169     * @param requestContext
170     *            The request context.
171     * @param request
172     *            The modify request.
173     * @param intermediateResponseHandler
174     *            The handler which should be used to send back any intermediate
175     *            responses to the client.
176     * @param resultHandler
177     *            The handler which should be used to send back the result to
178     *            the client.
179     * @throws UnsupportedOperationException
180     *             If this request handler does not handle modify requests.
181     */
182    void handleModify(C requestContext, ModifyRequest request,
183            IntermediateResponseHandler intermediateResponseHandler,
184            LdapResultHandler<Result> resultHandler);
185
186    /**
187     * Invoked when a modify DN request is received from a client.
188     *
189     * @param requestContext
190     *            The request context.
191     * @param request
192     *            The modify DN request.
193     * @param intermediateResponseHandler
194     *            The handler which should be used to send back any intermediate
195     *            responses to the client.
196     * @param resultHandler
197     *            The handler which should be used to send back the result to
198     *            the client.
199     * @throws UnsupportedOperationException
200     *             If this request handler does not handle modify DN requests.
201     */
202    void handleModifyDN(C requestContext, ModifyDNRequest request,
203            IntermediateResponseHandler intermediateResponseHandler,
204            LdapResultHandler<Result> resultHandler);
205
206    /**
207     * Invoked when a search request is received from a client.
208     *
209     * @param requestContext
210     *            The request context.
211     * @param request
212     *            The search request.
213     * @param intermediateResponseHandler
214     *            The handler which should be used to send back any intermediate
215     *            responses to the client.
216     * @param entryHandler
217     *            The entry handler which should be used to send back the search
218     *            entries results to the client.
219     * @param resultHandler
220     *            The handler which should be used to send back the result to
221     *            the client.
222     * @throws UnsupportedOperationException
223     *             If this request handler does not handle search requests.
224     */
225    void handleSearch(C requestContext, SearchRequest request,
226        IntermediateResponseHandler intermediateResponseHandler, SearchResultHandler entryHandler,
227        LdapResultHandler<Result> resultHandler);
228}