001    /*
002     * Copyright 2010-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2010-2016 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.ldap.listener;
022    
023    
024    
025    import java.util.List;
026    
027    import com.unboundid.ldap.protocol.AbandonRequestProtocolOp;
028    import com.unboundid.ldap.protocol.AddRequestProtocolOp;
029    import com.unboundid.ldap.protocol.BindRequestProtocolOp;
030    import com.unboundid.ldap.protocol.CompareRequestProtocolOp;
031    import com.unboundid.ldap.protocol.DeleteRequestProtocolOp;
032    import com.unboundid.ldap.protocol.ExtendedRequestProtocolOp;
033    import com.unboundid.ldap.protocol.ModifyRequestProtocolOp;
034    import com.unboundid.ldap.protocol.ModifyDNRequestProtocolOp;
035    import com.unboundid.ldap.protocol.SearchRequestProtocolOp;
036    import com.unboundid.ldap.protocol.UnbindRequestProtocolOp;
037    import com.unboundid.ldap.protocol.LDAPMessage;
038    import com.unboundid.ldap.sdk.Control;
039    import com.unboundid.ldap.sdk.LDAPException;
040    import com.unboundid.util.Extensible;
041    import com.unboundid.util.ThreadSafety;
042    import com.unboundid.util.ThreadSafetyLevel;
043    
044    
045    
046    /**
047     * This class defines an API that may be used to process requests read from a
048     * client connection.  A separate instance of this class, obtained through the
049     * {@link #newInstance} method,  will be used for each connection created by an
050     * {@link LDAPListener}.
051     */
052    @Extensible()
053    @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
054    public abstract class LDAPListenerRequestHandler
055    {
056      /**
057       * Creates a new instance of this request handler that will be used to process
058       * requests read by the provided connection.
059       *
060       * @param  connection  The connection with which this request handler instance
061       *                     will be associated.
062       *
063       * @return  The request handler instance that will be used for the provided
064       *          connection.
065       *
066       * @throws  LDAPException  If the connection should not be accepted.
067       */
068      public abstract LDAPListenerRequestHandler newInstance(
069                           final LDAPListenerClientConnection connection)
070             throws LDAPException;
071    
072    
073    
074      /**
075       * Indicates that the client connection with which this request handler
076       * instance is associated is being closed and any resources associated with it
077       * should be released.
078       */
079      public void closeInstance()
080      {
081        // No implementation is needed by default.
082      }
083    
084    
085    
086      /**
087       * Performs any processing necessary for the provided abandon request.
088       *
089       * @param  messageID  The message ID of the LDAP message containing the
090       *                    abandon request.
091       * @param  request    The abandon request that was included in the LDAP
092       *                    message that was received.
093       * @param  controls   The set of controls included in the LDAP message.  It
094       *                    may be empty if there were no controls, but will not be
095       *                    {@code null}.
096       */
097      public void processAbandonRequest(final int messageID,
098                                        final AbandonRequestProtocolOp request,
099                                        final List<Control> controls)
100      {
101        // No implementation provided by default.
102      }
103    
104    
105    
106      /**
107       * Performs any processing necessary for the provided add request.
108       *
109       * @param  messageID  The message ID of the LDAP message containing the add
110       *                    request.
111       * @param  request    The add request that was included in the LDAP message
112       *                    that was received.
113       * @param  controls   The set of controls included in the LDAP message.  It
114       *                    may be empty if there were no controls, but will not be
115       *                    {@code null}.
116       *
117       * @return  The {@link LDAPMessage} containing the response to send to the
118       *          client.  The protocol op in the {@code LDAPMessage} must be an
119       *          {@code AddResponseProtocolOp}.
120       */
121      public abstract LDAPMessage processAddRequest(final int messageID,
122                                       final AddRequestProtocolOp request,
123                                       final List<Control> controls);
124    
125    
126    
127      /**
128       * Performs any processing necessary for the provided bind request.
129       *
130       * @param  messageID  The message ID of the LDAP message containing the bind
131       *                    request.
132       * @param  request    The bind request that was included in the LDAP message
133       *                    that was received.
134       * @param  controls   The set of controls included in the LDAP message.  It
135       *                    may be empty if there were no controls, but will not be
136       *                    {@code null}.
137       *
138       * @return  The {@link LDAPMessage} containing the response to send to the
139       *          client.  The protocol op in the {@code LDAPMessage} must be a
140       *          {@code BindResponseProtocolOp}.
141       */
142      public abstract LDAPMessage processBindRequest(final int messageID,
143                                       final BindRequestProtocolOp request,
144                                       final List<Control> controls);
145    
146    
147    
148      /**
149       * Performs any processing necessary for the provided compare request.
150       *
151       * @param  messageID  The message ID of the LDAP message containing the
152       *                    compare request.
153       * @param  request    The compare request that was included in the LDAP
154       *                    message that was received.
155       * @param  controls   The set of controls included in the LDAP message.  It
156       *                    may be empty if there were no controls, but will not be
157       *                    {@code null}.
158       *
159       * @return  The {@link LDAPMessage} containing the response to send to the
160       *          client.  The protocol op in the {@code LDAPMessage} must be a
161       *          {@code CompareResponseProtocolOp}.
162       */
163      public abstract LDAPMessage processCompareRequest(final int messageID,
164                                       final CompareRequestProtocolOp request,
165                                       final List<Control> controls);
166    
167    
168    
169      /**
170       * Performs any processing necessary for the provided delete request.
171       *
172       * @param  messageID  The message ID of the LDAP message containing the delete
173       *                    request.
174       * @param  request    The delete request that was included in the LDAP message
175       *                    that was received.
176       * @param  controls   The set of controls included in the LDAP message.  It
177       *                    may be empty if there were no controls, but will not be
178       *                    {@code null}.
179       *
180       * @return  The {@link LDAPMessage} containing the response to send to the
181       *          client.  The protocol op in the {@code LDAPMessage} must be a
182       *          {@code DeleteResponseProtocolOp}.
183       */
184      public abstract LDAPMessage processDeleteRequest(final int messageID,
185                                       final DeleteRequestProtocolOp request,
186                                       final List<Control> controls);
187    
188    
189    
190      /**
191       * Performs any processing necessary for the provided extended request.
192       *
193       * @param  messageID  The message ID of the LDAP message containing the
194       *                    extended request.
195       * @param  request    The extended request that was included in the LDAP
196       *                    message that was received.
197       * @param  controls   The set of controls included in the LDAP message.  It
198       *                    may be empty if there were no controls, but will not be
199       *                    {@code null}.
200       *
201       * @return  The {@link LDAPMessage} containing the response to send to the
202       *          client.  The protocol op in the {@code LDAPMessage} must be an
203       *          {@code ExtendedResponseProtocolOp}.
204       */
205      public abstract LDAPMessage processExtendedRequest(final int messageID,
206                                       final ExtendedRequestProtocolOp request,
207                                       final List<Control> controls);
208    
209    
210    
211      /**
212       * Performs any processing necessary for the provided modify request.
213       *
214       * @param  messageID  The message ID of the LDAP message containing the modify
215       *                    request.
216       * @param  request    The modify request that was included in the LDAP message
217       *                    that was received.
218       * @param  controls   The set of controls included in the LDAP message.  It
219       *                    may be empty if there were no controls, but will not be
220       *                    {@code null}.
221       *
222       * @return  The {@link LDAPMessage} containing the response to send to the
223       *          client.  The protocol op in the {@code LDAPMessage} must be an
224       *          {@code ModifyResponseProtocolOp}.
225       */
226      public abstract LDAPMessage processModifyRequest(final int messageID,
227                                       final ModifyRequestProtocolOp request,
228                                       final List<Control> controls);
229    
230    
231    
232      /**
233       * Performs any processing necessary for the provided modify DN request.
234       *
235       * @param  messageID  The message ID of the LDAP message containing the modify
236       *                    DN request.
237       * @param  request    The modify DN request that was included in the LDAP
238       *                    message that was received.
239       * @param  controls   The set of controls included in the LDAP message.  It
240       *                    may be empty if there were no controls, but will not be
241       *                    {@code null}.
242       *
243       * @return  The {@link LDAPMessage} containing the response to send to the
244       *          client.  The protocol op in the {@code LDAPMessage} must be an
245       *          {@code ModifyDNResponseProtocolOp}.
246       */
247      public abstract LDAPMessage processModifyDNRequest(final int messageID,
248                                       final ModifyDNRequestProtocolOp request,
249                                       final List<Control> controls);
250    
251    
252    
253      /**
254       * Performs any processing necessary for the provided search request.
255       *
256       * @param  messageID  The message ID of the LDAP message containing the search
257       *                    request.
258       * @param  request    The search request that was included in the LDAP message
259       *                    that was received.
260       * @param  controls   The set of controls included in the LDAP message.  It
261       *                    may be empty if there were no controls, but will not be
262       *                    {@code null}.
263       *
264       * @return  The {@link LDAPMessage} containing the response to send to the
265       *          client.  The protocol op in the {@code LDAPMessage} must be an
266       *          {@code SearchResultDoneProtocolOp}.
267       */
268      public abstract LDAPMessage processSearchRequest(final int messageID,
269                                       final SearchRequestProtocolOp request,
270                                       final List<Control> controls);
271    
272    
273    
274      /**
275       * Performs any processing necessary for the provided unbind request.
276       *
277       * @param  messageID  The message ID of the LDAP message containing the search
278       *                    request.
279       * @param  request    The search request that was included in the LDAP message
280       *                    that was received.
281       * @param  controls   The set of controls included in the LDAP message.  It
282       *                    may be empty if there were no controls, but will not be
283       *                    {@code null}.
284       */
285      public void processUnbindRequest(final int messageID,
286                                       final UnbindRequestProtocolOp request,
287                                       final List<Control> controls)
288      {
289        // No implementation provided by default.
290      }
291    }