/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.daemon;
/**
* Provides support for native daemon invocation. Using
* a platform dependant helper program, classes that implement the
* <code>Daemon</code> interface can be initialized, started and
* stopped according to the conventions of the underlying operating
* system.
* <p>
* Implementors of this interface must also provide a public constructor
* with no arguments so that instances can be created in an automated
* fashion.
* </p>
* @author Pier Fumagalli
* @version $Id: Daemon.java 1204010 2011-11-19 16:15:23Z ggregory $
*/
public interface Daemon
{
/**
* Initializes this <code>Daemon</code> instance.
* <p>
* This method gets called once the JVM process is created and the
* <code>Daemon</code> instance is created thru its empty public
* constructor.
* </p>
* <p>
* Under certain operating systems (typically Unix based operating
* systems) and if the native invocation framework is configured to do
* so, this method might be called with <i>super-user</i> privileges.
* </p>
* <p>
* For example, it might be wise to create <code>ServerSocket</code>
* instances within the scope of this method, and perform all operations
* requiring <i>super-user</i> privileges in the underlying operating
* system.
* </p>
* <p>
* Apart from set up and allocation of native resources, this method
* must not start the actual operation of the <code>Daemon</code> (such
* as starting threads calling the <code>ServerSocket.accept()</code>
* method) as this would impose some serious security hazards. The
* start of operation must be performed in the <code>start()</code>
* method.
* </p>
*
* @param context A <code>DaemonContext</code> object used to
* communicate with the container.
* @exception DaemonInitException An exception that prevented
* initialization where you want to display a nice message to the user,
* rather than a stack trace.
* @exception Exception Any exception preventing a successful
* initialization.
*/
public void init(DaemonContext context)
throws DaemonInitException, Exception;
/**
* Starts the operation of this <code>Daemon</code> instance. This
* method is to be invoked by the environment after the init()
* method has been successfully invoked and possibly the security
* level of the JVM has been dropped. Implementors of this
* method are free to start any number of threads, but need to
* return control after having done that to enable invocation of
* the stop()-method.
*/
public void start()
throws Exception;
/**
* Stops the operation of this <code>Daemon</code> instance. Note
* that the proper place to free any allocated resources such as
* sockets or file descriptors is in the destroy method, as the
* container may restart the Daemon by calling start() after
* stop().
*/
public void stop()
throws Exception;
/**
* Frees any resources allocated by this daemon such as file
* descriptors or sockets. This method gets called by the container
* after stop() has been called, before the JVM exits. The Daemon
* can not be restarted after this method has been called without a
* new call to the init() method.
*/
public void destroy();
}