001/* 002 * Copyright 2010-2024 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2010-2024 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-2024 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}