001 /*
002 * Copyright 2010-2013 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2010-2013 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 }