001/*
002 * Copyright 2010-2017 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2010-2017 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 */
021package com.unboundid.ldap.listener;
022
023
024
025import java.util.List;
026
027import com.unboundid.ldap.protocol.AbandonRequestProtocolOp;
028import com.unboundid.ldap.protocol.AddRequestProtocolOp;
029import com.unboundid.ldap.protocol.BindRequestProtocolOp;
030import com.unboundid.ldap.protocol.CompareRequestProtocolOp;
031import com.unboundid.ldap.protocol.DeleteRequestProtocolOp;
032import com.unboundid.ldap.protocol.ExtendedRequestProtocolOp;
033import com.unboundid.ldap.protocol.ModifyRequestProtocolOp;
034import com.unboundid.ldap.protocol.ModifyDNRequestProtocolOp;
035import com.unboundid.ldap.protocol.SearchRequestProtocolOp;
036import com.unboundid.ldap.protocol.UnbindRequestProtocolOp;
037import com.unboundid.ldap.protocol.LDAPMessage;
038import com.unboundid.ldap.sdk.Control;
039import com.unboundid.ldap.sdk.LDAPException;
040import com.unboundid.util.Extensible;
041import com.unboundid.util.ThreadSafety;
042import 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)
054public 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}