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 2009 Sun Microsystems, Inc.
015 * Portions copyright 2013 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.io;
019
020import java.io.IOException;
021
022import org.forgerock.opendj.ldap.ByteString;
023import org.forgerock.opendj.ldap.DecodeException;
024import org.forgerock.opendj.ldap.requests.AbandonRequest;
025import org.forgerock.opendj.ldap.requests.AddRequest;
026import org.forgerock.opendj.ldap.requests.CompareRequest;
027import org.forgerock.opendj.ldap.requests.DeleteRequest;
028import org.forgerock.opendj.ldap.requests.ExtendedRequest;
029import org.forgerock.opendj.ldap.requests.GenericBindRequest;
030import org.forgerock.opendj.ldap.requests.ModifyDNRequest;
031import org.forgerock.opendj.ldap.requests.ModifyRequest;
032import org.forgerock.opendj.ldap.requests.SearchRequest;
033import org.forgerock.opendj.ldap.requests.UnbindRequest;
034import org.forgerock.opendj.ldap.responses.BindResult;
035import org.forgerock.opendj.ldap.responses.CompareResult;
036import org.forgerock.opendj.ldap.responses.ExtendedResult;
037import org.forgerock.opendj.ldap.responses.IntermediateResponse;
038import org.forgerock.opendj.ldap.responses.Result;
039import org.forgerock.opendj.ldap.responses.SearchResultEntry;
040import org.forgerock.opendj.ldap.responses.SearchResultReference;
041
042/**
043 * An interface for handling LDAP messages decoded using an {@link LDAPReader}.
044 */
045public interface LDAPMessageHandler {
046
047    /**
048     * Handles an LDAP abandon request message.
049     *
050     * @param messageID
051     *            The LDAP message ID.
052     * @param request
053     *            The decoded abandon request.
054     * @throws DecodeException
055     *             If this handler does not support abandon requests.
056     * @throws IOException
057     *             If an unexpected IO error occurred while processing the
058     *             request.
059     */
060    void abandonRequest(int messageID, AbandonRequest request) throws DecodeException, IOException;
061
062    /**
063     * Handles an LDAP add request message.
064     *
065     * @param messageID
066     *            The LDAP message ID.
067     * @param request
068     *            The decoded add request.
069     * @throws DecodeException
070     *             If this handler does not support add requests.
071     * @throws IOException
072     *             If an unexpected IO error occurred while processing the
073     *             request.
074     */
075    void addRequest(int messageID, AddRequest request) throws DecodeException, IOException;
076
077    /**
078     * Handles an LDAP add result message.
079     *
080     * @param messageID
081     *            The LDAP message ID.
082     * @param result
083     *            The decoded add result.
084     * @throws DecodeException
085     *             If this handler does not support add results.
086     * @throws IOException
087     *             If an unexpected IO error occurred while processing the
088     *             response.
089     */
090    void addResult(int messageID, Result result) throws DecodeException, IOException;
091
092    /**
093     * Handles an LDAP bind request message.
094     *
095     * @param messageID
096     *            The LDAP message ID.
097     * @param version
098     *            The requested LDAP protocol version.
099     * @param request
100     *            The decoded bind request.
101     * @throws DecodeException
102     *             If this handler does not support bind requests.
103     * @throws IOException
104     *             If an unexpected IO error occurred while processing the
105     *             request.
106     */
107    void bindRequest(int messageID, int version, GenericBindRequest request)
108            throws DecodeException, IOException;
109
110    /**
111     * Handles an LDAP bind result message.
112     *
113     * @param messageID
114     *            The LDAP message ID.
115     * @param result
116     *            The decoded bind result.
117     * @throws DecodeException
118     *             If this handler does not support bind results.
119     * @throws IOException
120     *             If an unexpected IO error occurred while processing the
121     *             response.
122     */
123    void bindResult(int messageID, BindResult result) throws DecodeException, IOException;
124
125    /**
126     * Handles an LDAP compare request message.
127     *
128     * @param messageID
129     *            The LDAP message ID.
130     * @param request
131     *            The decoded compare request.
132     * @throws DecodeException
133     *             If this handler does not support compare requests.
134     * @throws IOException
135     *             If an unexpected IO error occurred while processing the
136     *             request.
137     */
138    void compareRequest(int messageID, CompareRequest request) throws DecodeException, IOException;
139
140    /**
141     * Handles an LDAP compare result message.
142     *
143     * @param messageID
144     *            The LDAP message ID.
145     * @param result
146     *            The decoded compare result.
147     * @throws DecodeException
148     *             If this handler does not support compare results.
149     * @throws IOException
150     *             If an unexpected IO error occurred while processing the
151     *             response.
152     */
153    void compareResult(int messageID, CompareResult result) throws DecodeException, IOException;
154
155    /**
156     * Handles an LDAP delete request message.
157     *
158     * @param messageID
159     *            The LDAP message ID.
160     * @param request
161     *            The decoded delete request.
162     * @throws DecodeException
163     *             If this handler does not support delete requests.
164     * @throws IOException
165     *             If an unexpected IO error occurred while processing the
166     *             request.
167     */
168    void deleteRequest(int messageID, DeleteRequest request) throws DecodeException, IOException;
169
170    /**
171     * Handles an LDAP delete result message.
172     *
173     * @param messageID
174     *            The LDAP message ID.
175     * @param result
176     *            The decoded delete result.
177     * @throws DecodeException
178     *             If this handler does not support delete results.
179     * @throws IOException
180     *             If an unexpected IO error occurred while processing the
181     *             response.
182     */
183    void deleteResult(int messageID, Result result) throws DecodeException, IOException;
184
185    /**
186     * Handles an LDAP extended request message.
187     *
188     * @param <R>
189     *            type of extended result
190     * @param messageID
191     *            The LDAP message ID.
192     * @param request
193     *            The decoded extended request.
194     * @throws DecodeException
195     *             If this handler does not support extended requests.
196     * @throws IOException
197     *             If an unexpected IO error occurred while processing the
198     *             request.
199     */
200    <R extends ExtendedResult> void extendedRequest(int messageID, ExtendedRequest<R> request)
201            throws DecodeException, IOException;
202
203    /**
204     * Handles an LDAP extended result message.
205     *
206     * @param messageID
207     *            The LDAP message ID.
208     * @param result
209     *            The decoded extended result.
210     * @throws DecodeException
211     *             If this handler does not support extended results.
212     * @throws IOException
213     *             If an unexpected IO error occurred while processing the
214     *             response.
215     */
216    void extendedResult(int messageID, ExtendedResult result) throws DecodeException, IOException;
217
218    /**
219     * Handles an LDAP intermediate response message.
220     *
221     * @param messageID
222     *            The LDAP message ID.
223     * @param response
224     *            The decoded intermediate response.
225     * @throws DecodeException
226     *             If this handler does not support intermediate responses.
227     * @throws IOException
228     *             If an unexpected IO error occurred while processing the
229     *             response.
230     */
231    void intermediateResponse(int messageID, IntermediateResponse response) throws DecodeException,
232            IOException;
233
234    /**
235     * Handles an LDAP modify DN request message.
236     *
237     * @param messageID
238     *            The LDAP message ID.
239     * @param request
240     *            The decoded modify DN request.
241     * @throws DecodeException
242     *             If this handler does not support modify DN requests.
243     * @throws IOException
244     *             If an unexpected IO error occurred while processing the
245     *             request.
246     */
247    void modifyDNRequest(int messageID, ModifyDNRequest request) throws DecodeException,
248            IOException;
249
250    /**
251     * Handles an LDAP modify DN result message.
252     *
253     * @param messageID
254     *            The LDAP message ID.
255     * @param result
256     *            The decoded modify DN result.
257     * @throws DecodeException
258     *             If this handler does not support modify DN results.
259     * @throws IOException
260     *             If an unexpected IO error occurred while processing the
261     *             response.
262     */
263    void modifyDNResult(int messageID, Result result) throws DecodeException, IOException;
264
265    /**
266     * Handles an LDAP modify request message.
267     *
268     * @param messageID
269     *            The LDAP message ID.
270     * @param request
271     *            The decoded modify request.
272     * @throws DecodeException
273     *             If this handler does not support modify requests.
274     * @throws IOException
275     *             If an unexpected IO error occurred while processing the
276     *             request.
277     */
278    void modifyRequest(int messageID, ModifyRequest request) throws DecodeException, IOException;
279
280    /**
281     * Handles an LDAP modify result message.
282     *
283     * @param messageID
284     *            The LDAP message ID.
285     * @param result
286     *            The decoded modify result.
287     * @throws DecodeException
288     *             If this handler does not support modify results.
289     * @throws IOException
290     *             If an unexpected IO error occurred while processing the
291     *             response.
292     */
293    void modifyResult(int messageID, Result result) throws DecodeException, IOException;
294
295    /**
296     * Handles an LDAP search request message.
297     *
298     * @param messageID
299     *            The LDAP message ID.
300     * @param request
301     *            The decoded search request.
302     * @throws DecodeException
303     *             If this handler does not support search requests.
304     * @throws IOException
305     *             If an unexpected IO error occurred while processing the
306     *             request.
307     */
308    void searchRequest(int messageID, SearchRequest request) throws DecodeException, IOException;
309
310    /**
311     * Handles an LDAP search result message.
312     *
313     * @param messageID
314     *            The LDAP message ID.
315     * @param result
316     *            The decoded search result.
317     * @throws DecodeException
318     *             If this handler does not support search results.
319     * @throws IOException
320     *             If an unexpected IO error occurred while processing the
321     *             response.
322     */
323    void searchResult(int messageID, Result result) throws DecodeException, IOException;
324
325    /**
326     * Handles an LDAP search result entry message.
327     *
328     * @param messageID
329     *            The LDAP message ID.
330     * @param entry
331     *            The decoded search result entry.
332     * @throws DecodeException
333     *             If this handler does not support search result entries.
334     * @throws IOException
335     *             If an unexpected IO error occurred while processing the
336     *             response.
337     */
338    void searchResultEntry(int messageID, SearchResultEntry entry) throws DecodeException,
339            IOException;
340
341    /**
342     * Handles an LDAP search result reference message.
343     *
344     * @param messageID
345     *            The LDAP message ID.
346     * @param reference
347     *            The decoded search result reference.
348     * @throws DecodeException
349     *             If this handler does not support search result references.
350     * @throws IOException
351     *             If an unexpected IO error occurred while processing the
352     *             response.
353     */
354    void searchResultReference(int messageID, SearchResultReference reference)
355            throws DecodeException, IOException;
356
357    /**
358     * Handles an LDAP unbind request message.
359     *
360     * @param messageID
361     *            The LDAP message ID.
362     * @param request
363     *            The decoded unbind request.
364     * @throws DecodeException
365     *             If this handler does not support unbind requests.
366     * @throws IOException
367     *             If an unexpected IO error occurred while processing the
368     *             request.
369     */
370    void unbindRequest(int messageID, UnbindRequest request) throws DecodeException, IOException;
371
372    /**
373     * Handles an unrecognized LDAP message.
374     *
375     * @param messageID
376     *            The LDAP message ID.
377     * @param messageTag
378     *            The LDAP message type.
379     * @param messageBytes
380     *            The contents of the LDAP message.
381     * @throws DecodeException
382     *             If this handler does not support the message type.
383     * @throws IOException
384     *             If an unexpected IO error occurred while processing the
385     *             message.
386     */
387    void unrecognizedMessage(int messageID, byte messageTag, ByteString messageBytes)
388            throws DecodeException, IOException;
389}