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
018package 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 */
034public 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