001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one or more
003     *  contributor license agreements.  See the NOTICE file distributed with
004     *  this work for additional information regarding copyright ownership.
005     *  The ASF licenses this file to You under the Apache License, Version 2.0
006     *  (the "License"); you may not use this file except in compliance with
007     *  the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     *  Unless required by applicable law or agreed to in writing, software
012     *  distributed under the License is distributed on an "AS IS" BASIS,
013     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     *  See the License for the specific language governing permissions and
015     *  limitations under the License.
016     */
017    
018    package org.apache.commons.daemon;
019    
020    /**
021     * Provides support for native daemon invocation. Using
022     * a platform dependant helper program, classes that implement the
023     * <code>Daemon</code> interface can be initialized, started and
024     * stopped according to the conventions of the underlying operating
025     * system.
026     * <p>
027     * Implementors of this interface must also provide a public constructor
028     * with no arguments so that instances can be created in an automated
029     * fashion.
030     * </p>
031     * @author Pier Fumagalli
032     * @version $Id: Daemon.java 1204010 2011-11-19 16:15:23Z ggregory $
033     */
034    public interface Daemon
035    {
036    
037        /**
038         * Initializes this <code>Daemon</code> instance.
039         * <p>
040         *   This method gets called once the JVM process is created and the
041         *   <code>Daemon</code> instance is created thru its empty public
042         *   constructor.
043         * </p>
044         * <p>
045         *   Under certain operating systems (typically Unix based operating
046         *   systems) and if the native invocation framework is configured to do
047         *   so, this method might be called with <i>super-user</i> privileges.
048         * </p>
049         * <p>
050         *   For example, it might be wise to create <code>ServerSocket</code>
051         *   instances within the scope of this method, and perform all operations
052         *   requiring <i>super-user</i> privileges in the underlying operating
053         *   system.
054         * </p>
055         * <p>
056         *   Apart from set up and allocation of native resources, this method
057         *   must not start the actual operation of the <code>Daemon</code> (such
058         *   as starting threads calling the <code>ServerSocket.accept()</code>
059         *   method) as this would impose some serious security hazards. The
060         *   start of operation must be performed in the <code>start()</code>
061         *   method.
062         * </p>
063         *
064         * @param context A <code>DaemonContext</code> object used to
065         * communicate with the container.
066         * @exception DaemonInitException An exception that prevented 
067         * initialization where you want to display a nice message to the user,
068         * rather than a stack trace.
069         * @exception Exception Any exception preventing a successful
070         *                      initialization.
071         */
072        public void init(DaemonContext context)
073            throws DaemonInitException, Exception;
074    
075        /**
076         * Starts the operation of this <code>Daemon</code> instance. This
077         * method is to be invoked by the environment after the init()
078         * method has been successfully invoked and possibly the security
079         * level of the JVM has been dropped. Implementors of this
080         * method are free to start any number of threads, but need to
081         * return control after having done that to enable invocation of
082         * the stop()-method.
083         */
084        public void start()
085            throws Exception;
086    
087        /**
088         * Stops the operation of this <code>Daemon</code> instance. Note
089         * that the proper place to free any allocated resources such as
090         * sockets or file descriptors is in the destroy method, as the
091         * container may restart the Daemon by calling start() after
092         * stop().
093         */
094        public void stop()
095            throws Exception;
096    
097        /**
098         * Frees any resources allocated by this daemon such as file
099         * descriptors or sockets. This method gets called by the container
100         * after stop() has been called, before the JVM exits. The Daemon
101         * can not be restarted after this method has been called without a
102         * new call to the init() method.
103         */
104        public void destroy();
105    }
106