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}