001/*
002 * Copyright 2010-2020 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2010-2020 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-2020 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.ThreadSafety;
057import com.unboundid.util.ThreadSafetyLevel;
058
059
060
061/**
062 * This class defines an API that may be used to process requests read from a
063 * client connection.  A separate instance of this class, obtained through the
064 * {@link #newInstance} method,  will be used for each connection created by an
065 * {@link LDAPListener}.
066 */
067@Extensible()
068@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
069public abstract class LDAPListenerRequestHandler
070{
071  /**
072   * Creates a new instance of this request handler that will be used to process
073   * requests read by the provided connection.
074   *
075   * @param  connection  The connection with which this request handler instance
076   *                     will be associated.
077   *
078   * @return  The request handler instance that will be used for the provided
079   *          connection.
080   *
081   * @throws  LDAPException  If the connection should not be accepted.
082   */
083  public abstract LDAPListenerRequestHandler newInstance(
084                       LDAPListenerClientConnection connection)
085         throws LDAPException;
086
087
088
089  /**
090   * Indicates that the client connection with which this request handler
091   * instance is associated is being closed and any resources associated with it
092   * should be released.
093   */
094  public void closeInstance()
095  {
096    // No implementation is needed by default.
097  }
098
099
100
101  /**
102   * Performs any processing necessary for the provided abandon request.
103   *
104   * @param  messageID  The message ID of the LDAP message containing the
105   *                    abandon request.
106   * @param  request    The abandon request that was included in the LDAP
107   *                    message that was received.
108   * @param  controls   The set of controls included in the LDAP message.  It
109   *                    may be empty if there were no controls, but will not be
110   *                    {@code null}.
111   */
112  public void processAbandonRequest(final int messageID,
113                                    final AbandonRequestProtocolOp request,
114                                    final List<Control> controls)
115  {
116    // No implementation provided by default.
117  }
118
119
120
121  /**
122   * Performs any processing necessary for the provided add request.
123   *
124   * @param  messageID  The message ID of the LDAP message containing the add
125   *                    request.
126   * @param  request    The add request that was included in the LDAP message
127   *                    that was received.
128   * @param  controls   The set of controls included in the LDAP message.  It
129   *                    may be empty if there were no controls, but will not be
130   *                    {@code null}.
131   *
132   * @return  The {@link LDAPMessage} containing the response to send to the
133   *          client.  The protocol op in the {@code LDAPMessage} must be an
134   *          {@code AddResponseProtocolOp}.
135   */
136  public abstract LDAPMessage processAddRequest(int messageID,
137                                   AddRequestProtocolOp request,
138                                   List<Control> controls);
139
140
141
142  /**
143   * Performs any processing necessary for the provided bind request.
144   *
145   * @param  messageID  The message ID of the LDAP message containing the bind
146   *                    request.
147   * @param  request    The bind request that was included in the LDAP message
148   *                    that was received.
149   * @param  controls   The set of controls included in the LDAP message.  It
150   *                    may be empty if there were no controls, but will not be
151   *                    {@code null}.
152   *
153   * @return  The {@link LDAPMessage} containing the response to send to the
154   *          client.  The protocol op in the {@code LDAPMessage} must be a
155   *          {@code BindResponseProtocolOp}.
156   */
157  public abstract LDAPMessage processBindRequest(int messageID,
158                                   BindRequestProtocolOp request,
159                                   List<Control> controls);
160
161
162
163  /**
164   * Performs any processing necessary for the provided compare request.
165   *
166   * @param  messageID  The message ID of the LDAP message containing the
167   *                    compare request.
168   * @param  request    The compare request that was included in the LDAP
169   *                    message that was received.
170   * @param  controls   The set of controls included in the LDAP message.  It
171   *                    may be empty if there were no controls, but will not be
172   *                    {@code null}.
173   *
174   * @return  The {@link LDAPMessage} containing the response to send to the
175   *          client.  The protocol op in the {@code LDAPMessage} must be a
176   *          {@code CompareResponseProtocolOp}.
177   */
178  public abstract LDAPMessage processCompareRequest(int messageID,
179                                   CompareRequestProtocolOp request,
180                                   List<Control> controls);
181
182
183
184  /**
185   * Performs any processing necessary for the provided delete request.
186   *
187   * @param  messageID  The message ID of the LDAP message containing the delete
188   *                    request.
189   * @param  request    The delete request that was included in the LDAP message
190   *                    that was received.
191   * @param  controls   The set of controls included in the LDAP message.  It
192   *                    may be empty if there were no controls, but will not be
193   *                    {@code null}.
194   *
195   * @return  The {@link LDAPMessage} containing the response to send to the
196   *          client.  The protocol op in the {@code LDAPMessage} must be a
197   *          {@code DeleteResponseProtocolOp}.
198   */
199  public abstract LDAPMessage processDeleteRequest(int messageID,
200                                   DeleteRequestProtocolOp request,
201                                   List<Control> controls);
202
203
204
205  /**
206   * Performs any processing necessary for the provided extended request.
207   *
208   * @param  messageID  The message ID of the LDAP message containing the
209   *                    extended request.
210   * @param  request    The extended request that was included in the LDAP
211   *                    message that was received.
212   * @param  controls   The set of controls included in the LDAP message.  It
213   *                    may be empty if there were no controls, but will not be
214   *                    {@code null}.
215   *
216   * @return  The {@link LDAPMessage} containing the response to send to the
217   *          client.  The protocol op in the {@code LDAPMessage} must be an
218   *          {@code ExtendedResponseProtocolOp}.
219   */
220  public abstract LDAPMessage processExtendedRequest(int messageID,
221                                   ExtendedRequestProtocolOp request,
222                                   List<Control> controls);
223
224
225
226  /**
227   * Performs any processing necessary for the provided modify request.
228   *
229   * @param  messageID  The message ID of the LDAP message containing the modify
230   *                    request.
231   * @param  request    The modify request that was included in the LDAP message
232   *                    that was received.
233   * @param  controls   The set of controls included in the LDAP message.  It
234   *                    may be empty if there were no controls, but will not be
235   *                    {@code null}.
236   *
237   * @return  The {@link LDAPMessage} containing the response to send to the
238   *          client.  The protocol op in the {@code LDAPMessage} must be an
239   *          {@code ModifyResponseProtocolOp}.
240   */
241  public abstract LDAPMessage processModifyRequest(int messageID,
242                                   ModifyRequestProtocolOp request,
243                                   List<Control> controls);
244
245
246
247  /**
248   * Performs any processing necessary for the provided modify DN request.
249   *
250   * @param  messageID  The message ID of the LDAP message containing the modify
251   *                    DN request.
252   * @param  request    The modify DN request that was included in the LDAP
253   *                    message that was received.
254   * @param  controls   The set of controls included in the LDAP message.  It
255   *                    may be empty if there were no controls, but will not be
256   *                    {@code null}.
257   *
258   * @return  The {@link LDAPMessage} containing the response to send to the
259   *          client.  The protocol op in the {@code LDAPMessage} must be an
260   *          {@code ModifyDNResponseProtocolOp}.
261   */
262  public abstract LDAPMessage processModifyDNRequest(int messageID,
263                                   ModifyDNRequestProtocolOp request,
264                                   List<Control> controls);
265
266
267
268  /**
269   * Performs any processing necessary for the provided search request.
270   *
271   * @param  messageID  The message ID of the LDAP message containing the search
272   *                    request.
273   * @param  request    The search request that was included in the LDAP message
274   *                    that was received.
275   * @param  controls   The set of controls included in the LDAP message.  It
276   *                    may be empty if there were no controls, but will not be
277   *                    {@code null}.
278   *
279   * @return  The {@link LDAPMessage} containing the response to send to the
280   *          client.  The protocol op in the {@code LDAPMessage} must be an
281   *          {@code SearchResultDoneProtocolOp}.
282   */
283  public abstract LDAPMessage processSearchRequest(int messageID,
284                                   SearchRequestProtocolOp request,
285                                   List<Control> controls);
286
287
288
289  /**
290   * Performs any processing necessary for the provided unbind request.
291   *
292   * @param  messageID  The message ID of the LDAP message containing the search
293   *                    request.
294   * @param  request    The search request that was included in the LDAP message
295   *                    that was received.
296   * @param  controls   The set of controls included in the LDAP message.  It
297   *                    may be empty if there were no controls, but will not be
298   *                    {@code null}.
299   */
300  public void processUnbindRequest(final int messageID,
301                                   final UnbindRequestProtocolOp request,
302                                   final List<Control> controls)
303  {
304    // No implementation provided by default.
305  }
306}