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    }