001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2006-2008 Sun Microsystems, Inc. 026 */ 027 package org.opends.server.api; 028 import org.opends.messages.Message; 029 030 031 032 import java.util.Collection; 033 import java.util.List; 034 035 import org.opends.server.admin.std.server.*; 036 import org.opends.server.config.ConfigException; 037 import org.opends.server.monitors.ConnectionHandlerMonitor; 038 import org.opends.server.types.HostPort; 039 import org.opends.server.types.InitializationException; 040 041 042 043 /** 044 * This class defines the set of methods and structures that must be 045 * implemented by a Directory Server connection handler. 046 * 047 * @param <T> 048 * The type of connection handler configuration handled by 049 * this connection handler implementation. 050 */ 051 @org.opends.server.types.PublicAPI( 052 stability=org.opends.server.types.StabilityLevel.VOLATILE, 053 mayInstantiate=false, 054 mayExtend=true, 055 mayInvoke=false) 056 public abstract class ConnectionHandler 057 <T extends ConnectionHandlerCfg> 058 extends DirectoryThread 059 { 060 // The monitor associated with this connection handler. 061 private ConnectionHandlerMonitor monitor; 062 063 064 065 /** 066 * Creates a new instance of this connection handler. This must be 067 * called by all connection handlers, and all connection handlers 068 * must provide default constructors (i.e., those that do not take 069 * any arguments) that invoke this constructor. 070 * 071 * @param threadName 072 * The name to use for this thread. 073 */ 074 protected ConnectionHandler(String threadName) { 075 super(threadName); 076 077 monitor = null; 078 } 079 080 081 082 /** 083 * Closes this connection handler so that it will no longer accept 084 * new client connections. It may or may not disconnect existing 085 * client connections based on the provided flag. Note, however, 086 * that some connection handler implementations may not have any way 087 * to continue processing requests from existing connections, in 088 * which case they should always be closed regardless of the value 089 * of the {@code closeConnections} flag. 090 * 091 * @param finalizeReason 092 * The reason that this connection handler should be 093 * finalized. 094 * @param closeConnections 095 * Indicates whether any established client connections 096 * associated with the connection handler should also be 097 * closed. 098 */ 099 public abstract void finalizeConnectionHandler( 100 Message finalizeReason, boolean closeConnections); 101 102 103 104 /** 105 * Retrieves a name that may be used to refer to this connection 106 * handler. Every connection handler instance (even handlers of the 107 * same type) must have a unique name. 108 * 109 * @return A unique name that may be used to refer to this 110 * connection handler. 111 */ 112 public abstract String getConnectionHandlerName(); 113 114 115 116 /** 117 * Retrieves the name of the protocol used to communicate with 118 * clients. It should take into account any special naming that may 119 * be needed to express any security mechanisms or other constraints 120 * in place (e.g., "LDAPS" for LDAP over SSL). 121 * 122 * @return The name of the protocol used to communicate with 123 * clients. 124 */ 125 public abstract String getProtocol(); 126 127 128 129 /** 130 * Retrieves information about the listener(s) that will be used to 131 * accept client connections. 132 * 133 * @return Information about the listener(s) that will be used to 134 * accept client connections, or an empty list if this 135 * connection handler does not accept connections from 136 * network clients. 137 */ 138 public abstract Collection<HostPort> getListeners(); 139 140 141 142 /** 143 * Retrieves the set of active client connections that have been 144 * established through this connection handler. 145 * 146 * @return The set of active client connections that have been 147 * established through this connection handler. 148 */ 149 public abstract Collection<ClientConnection> getClientConnections(); 150 151 152 153 /** 154 * Initializes this connection handler provider based on the 155 * information in the provided connection handler configuration. 156 * 157 * @param configuration 158 * The connection handler configuration that contains the 159 * information to use to initialize this connection 160 * handler. 161 * @throws ConfigException 162 * If an unrecoverable problem arises in the process of 163 * performing the initialization as a result of the server 164 * configuration. 165 * @throws InitializationException 166 * If a problem occurs during initialization that is not 167 * related to the server configuration. 168 */ 169 public abstract void initializeConnectionHandler(T configuration) 170 throws ConfigException, InitializationException; 171 172 173 174 /** 175 * Indicates whether the provided configuration is acceptable for 176 * this connection handler. It should be possible to call this 177 * method on an uninitialized connection handler instance in order 178 * to determine whether the connection handler would be able to use 179 * the provided configuration. 180 * <BR><BR> 181 * Note that implementations which use a subclass of the provided 182 * configuration class will likely need to cast the configuration 183 * to the appropriate subclass type. 184 * 185 * @param configuration The connection handler configuration 186 * for which to make the determination. 187 * @param unacceptableReasons A list that may be used to hold the 188 * reasons that the provided 189 * configuration is not acceptable. 190 * 191 * @return {@code true} if the provided configuration is acceptable 192 * for this connection handler, or {@code false} if not. 193 */ 194 public boolean isConfigurationAcceptable( 195 ConnectionHandlerCfg configuration, 196 List<Message> unacceptableReasons) 197 { 198 // This default implementation does not perform any special 199 // validation. It should be overridden by connection handler 200 // implementations that wish to perform more detailed validation. 201 return true; 202 } 203 204 205 206 /** 207 * Operates in a loop, accepting new connections and ensuring that 208 * requests on those connections are handled properly. 209 */ 210 public abstract void run(); 211 212 213 214 /** 215 * Retrieves the monitor instance for this connection handler. 216 * 217 * @return The monitor instance for this connection handler, or 218 * {@code null} if none has been provided. 219 */ 220 public final ConnectionHandlerMonitor getConnectionHandlerMonitor() 221 { 222 return monitor; 223 } 224 225 226 227 /** 228 * Sets the monitor instance for this connection handler. 229 * 230 * @param monitor The monitor instance for this connection 231 * handler. 232 */ 233 public final void setConnectionHandlerMonitor( 234 ConnectionHandlerMonitor monitor) 235 { 236 this.monitor = monitor; 237 } 238 239 240 241 /** 242 * Retrieves a string representation of this connection handler. 243 * 244 * @return A string representation of this connection handler. 245 */ 246 public String toString() { 247 StringBuilder buffer = new StringBuilder(); 248 toString(buffer); 249 return buffer.toString(); 250 } 251 252 253 254 /** 255 * Appends a string representation of this connection handler to the 256 * provided buffer. 257 * 258 * @param buffer 259 * The buffer to which the information should be appended. 260 */ 261 public abstract void toString(StringBuilder buffer); 262 }