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