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