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