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     * This interface 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 convensions 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 1.0 <i>(CVS $Revision: 557416 $)</i>
033     */
034    public interface Daemon {
035    
036        /**
037         * Initialize this <code>Daemon</code> instance.
038         * <p>
039         *   This method gets called once the JVM process is created and the
040         *   <code>Daemon</code> instance is created thru its empty public
041         *   constructor.
042         * </p>
043         * <p>
044         *   Under certain operating systems (typically Unix based operating
045         *   systems) and if the native invocation framework is configured to do
046         *   so, this method might be called with <i>super-user</i> privileges.
047         * </p>
048         * <p>
049         *   For example, it might be wise to create <code>ServerSocket</code>
050         *   instances within the scope of this method, and perform all operations
051         *   requiring <i>super-user</i> privileges in the underlying operating
052         *   system.
053         * </p>
054         * <p>
055         *   Apart from set up and allocation of native resources, this method
056         *   must not start the actual operation of the <code>Daemon</code> (such
057         *   as starting threads calling the <code>ServerSocket.accept()</code>
058         *   method) as this would impose some serious security hazards. The
059         *   start of operation must be performed in the <code>start()</code>
060         *   method.
061         * </p>
062         *
063         * @param context A <code>DaemonContext</code> object used to
064         * communicate with the container.
065         * 
066         * @exception Exception Any exception preventing a successful
067         *                      initialization.
068         */
069        public void init(DaemonContext context)
070        throws Exception;
071    
072        /**
073         * Start the operation of this <code>Daemon</code> instance. This
074         * method is to be invoked by the environment after the init()
075         * method has been successfully invoked and possibly the security
076         * level of the JVM has been dropped. Implementors of this
077         * method are free to start any number of threads, but need to
078         * return control after having done that to enable invocation of
079         * the stop()-method.
080         */
081        public void start()
082        throws Exception;
083    
084        /**
085         * Stop the operation of this <code>Daemon</code> instance. Note
086         * that the proper place to free any allocated resources such as
087         * sockets or file descriptors is in the destroy method, as the
088         * container may restart the Daemon by calling start() after
089         * stop().
090         */
091        public void stop()
092        throws Exception;
093    
094        /**
095         * Free any resources allocated by this daemon such as file
096         * descriptors or sockets. This method gets called by the container
097         * after stop() has been called, before the JVM exits. The Daemon
098         * can not be restarted after this method has been called without a
099         * new call to the init() method.
100         */
101        public void destroy();
102    }