001: /*
002: * Copyright 2001-2004 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.commons.daemon;
018:
019: /**
020: * This interface provides support for native daemon invocation. Using
021: * a platform dependant helper program classes that implement the
022: * <code>Daemon</code> interface can be initialized, started and
023: * stopped according to the convensions of the underlying operating
024: * system.
025: * <p>
026: * Implementors of this interface must also provide a public constructor
027: * with no arguments so that instances can be created in an automated
028: * fashion.
029: * </p>
030: * @author Pier Fumagalli
031: * @author Copyright © 2000-2001 <a href="http://www.apache.org/">The
032: * Apache Software Foundation</a>. All rights reserved.
033: * @version 1.0 <i>(CVS $Revision: 155409 $)</i>
034: */
035: public interface Daemon {
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) 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. <code>Implementors of this
077: * method are free to start any number of threads, but need to
078: * return control avfter having done that to enable invocation of
079: * the stop()-method.
080: */
081: public void start() throws Exception;
082:
083: /**
084: * Stop the operation of this <code>Daemon</code> instance. Note
085: * that the proper place to free any allocated resources such as
086: * sockets or file descriptors is in the destroy method, as the
087: * container may restart the Daemon by calling start() after
088: * stop().
089: */
090: public void stop() throws Exception;
091:
092: /**
093: * Free any resources allocated by this daemon such as file
094: * descriptors or sockets. This method gets called by the container
095: * after stop() has been called, before the JVM exits. The Daemon
096: * can not be restarted after this method has been called without a
097: * new call to the init() method.
098: */
099: public void destroy();
100: }
|