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