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.protocols.internal;
028    import org.opends.messages.Message;
029    
030    
031    
032    import java.util.Collection;
033    import java.util.LinkedList;
034    
035    import org.opends.server.admin.std.server.*;
036    import org.opends.server.api.ClientConnection;
037    import org.opends.server.api.ConnectionHandler;
038    import org.opends.server.config.ConfigException;
039    import org.opends.server.types.InitializationException;
040    import org.opends.server.types.HostPort;
041    
042    
043    
044    /**
045     * This class defines a Directory Server connection handler that will
046     * handle internal "connections".
047     */
048    @org.opends.server.types.PublicAPI(
049         stability=org.opends.server.types.StabilityLevel.PRIVATE,
050         mayInstantiate=false,
051         mayExtend=false,
052         mayInvoke=false)
053    public final class InternalConnectionHandler
054           extends ConnectionHandler
055    {
056      // The singleton instance of this internal connection handler.
057      private static InternalConnectionHandler handlerInstance =
058           new InternalConnectionHandler();
059    
060      // The list of "connections" associated with this connection
061      // handler.
062      private LinkedList<ClientConnection> connectionList;
063    
064      // The list of listeners associated with this connection handler.
065      private LinkedList<HostPort> listeners;
066    
067      // The name of the protocol for this connection handler.
068      private String protocol;
069    
070    
071    
072      /**
073       * Creates a new instance of this connection handler.  All
074       * initialization should be done in the
075       * <CODE>initializeConnectionHandler</CODE> method.
076       */
077      private InternalConnectionHandler()
078      {
079        super("Internal Connection Handler Thread");
080    
081    
082        // Since we can't guarantee that the initializeConnectionHandler
083        // method will always be called for this method, we'll do the
084        // necessary "initialization" here.
085        protocol       = "internal";
086        connectionList = new LinkedList<ClientConnection>();
087        listeners      = new LinkedList<HostPort>();
088      }
089    
090    
091    
092      /**
093       * Retrieves the static instance of this internal connection
094       * handler.
095       *
096       * @return  The static instance of this internal connection handler.
097       */
098      public static InternalConnectionHandler getInstance()
099      {
100        return handlerInstance;
101      }
102    
103    
104    
105      /**
106       * Initializes this connection handler provider based on the
107       * information in the provided connection handler configuration.
108       *
109       * @param  configuration  The connection handler configuration that
110       *                        contains the information to use to
111       *                        initialize this connection handler.
112       *
113       * @throws  ConfigException  If an unrecoverable problem arises in
114       *                           the process of performing the
115       *                           initialization as a result of the
116       *                           server configuration.
117       *
118       * @throws  InitializationException  If a problem occurs during
119       *                                   initialization that is not
120       *                                   related to the server
121       *                                   configuration.
122       */
123      public void initializeConnectionHandler(
124                       ConnectionHandlerCfg configuration)
125          throws ConfigException, InitializationException
126      {
127        // No implementation required.
128      }
129    
130    
131    
132      /**
133       * Closes this connection handler so that it will no longer accept
134       * new client connections.  It may or may not disconnect existing
135       * client connections based on the provided flag.  Note, however,
136       * that some connection handler implementations may not have any way
137       * to continue processing requests from existing connections, in
138       * which case they should always be closed regardless of the value
139       * of the <CODE>closeConnections</CODE> flag.
140       *
141       * @param  finalizeReason    The reason that this connection handler
142       *                           should be finalized.
143       * @param  closeConnections  Indicates whether any established
144       *                           client connections associated with the
145       *                           connection handler should also be
146       *                           closed.
147       */
148      @Override()
149      public void finalizeConnectionHandler(Message finalizeReason,
150                                            boolean closeConnections)
151      {
152        // No implementation is required.
153      }
154    
155    
156    
157      /**
158       * Retrieves a name that may be used to refer to this connection
159       * handler.  Every connection handler instance (even handlers of the
160       * same type) must have a unique name.
161       *
162       * @return  A unique name that may be used to refer to this
163       *          connection handler.
164       */
165      @Override()
166      public String getConnectionHandlerName()
167      {
168        return "Internal Connection Handler";
169      }
170    
171    
172    
173      /**
174       * Retrieves the name of the protocol used to communicate with
175       * clients.  It should take into account any special naming that may
176       * be needed to express any security mechanisms or other constraints
177       * in place (e.g., "LDAPS" for LDAP over SSL).
178       *
179       * @return  The name of the protocol used to communicate with
180       *          clients.
181       */
182      @Override()
183      public String getProtocol()
184      {
185        return protocol;
186      }
187    
188    
189    
190      /**
191       * Retrieves information about the listener(s) that will be used to
192       * accept client connections.
193       *
194       * @return  Information about the listener(s) that will be used to
195       *          accept client connections, or an empty list if this
196       *          connection handler does not accept connections from
197       *          network clients.
198       */
199      @Override()
200      public Collection<HostPort> getListeners()
201      {
202        return listeners;
203      }
204    
205    
206    
207      /**
208       * Retrieves the set of active client connections that have been
209       * established through this connection handler.
210       *
211       * @return  The set of active client connections that have been
212       *          established through this connection handler.
213       */
214      @Override()
215      public Collection<ClientConnection> getClientConnections()
216      {
217        return connectionList;
218      }
219    
220    
221    
222      /**
223       * Operates in a loop, accepting new connections and ensuring that
224       * requests on those connections are handled properly.
225       */
226      @Override()
227      public void run()
228      {
229        // No implementation is required since this connection handler
230        // won't actually accept connections.
231        return;
232      }
233    
234    
235    
236      /**
237       * Retrieves a string representation of this connection handler.
238       *
239       * @return  A string representation of this connection handler.
240       */
241      @Override()
242      public String toString()
243      {
244        return "Internal Connection Handler";
245      }
246    
247    
248    
249      /**
250       * Appends a string representation of this connection handler to the
251       * provided buffer.
252       *
253       * @param  buffer  The buffer to which the information should be
254       *                 appended.
255       */
256      @Override()
257      public void toString(StringBuilder buffer)
258      {
259        buffer.append("Internal Connection Handler");
260      }
261    
262      /**
263       * Called near the end of server shutdown.  This ensures that a new
264       * InternalClientConnection is created if the server is immediately
265       * restarted as part of an in-core restart.
266       */
267      public static void clearRootClientConnectionAtShutdown()
268      {
269        InternalClientConnection.clearRootClientConnectionAtShutdown();
270      }
271    
272    }
273