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 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 1.0 <i>(CVS $Revision: 925054 $)</i>
033 */
034 public interface Daemon
035 {
036
037 /**
038 * Initialize 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 *
067 * @exception Exception Any exception preventing a successful
068 * initialization.
069 */
070 public void init(DaemonContext context)
071 throws Exception;
072
073 /**
074 * Start the operation of this <code>Daemon</code> instance. This
075 * method is to be invoked by the environment after the init()
076 * method has been successfully invoked and possibly the security
077 * level of the JVM has been dropped. Implementors of this
078 * method are free to start any number of threads, but need to
079 * return control after having done that to enable invocation of
080 * the stop()-method.
081 */
082 public void start()
083 throws Exception;
084
085 /**
086 * Stop the operation of this <code>Daemon</code> instance. Note
087 * that the proper place to free any allocated resources such as
088 * sockets or file descriptors is in the destroy method, as the
089 * container may restart the Daemon by calling start() after
090 * stop().
091 */
092 public void stop()
093 throws Exception;
094
095 /**
096 * Free any resources allocated by this daemon such as file
097 * descriptors or sockets. This method gets called by the container
098 * after stop() has been called, before the JVM exits. The Daemon
099 * can not be restarted after this method has been called without a
100 * new call to the init() method.
101 */
102 public void destroy();
103 }
104