KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > daemon > Daemon


1 /*
2  * Copyright 2001-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.apache.commons.daemon;
18
19 /**
20  * This interface provides support for native daemon invocation. Using
21  * a platform dependant helper program classes that implement the
22  * <code>Daemon</code> interface can be initialized, started and
23  * stopped according to the convensions of the underlying operating
24  * system.
25  * <p>
26  * Implementors of this interface must also provide a public constructor
27  * with no arguments so that instances can be created in an automated
28  * fashion.
29  * </p>
30  * @author Pier Fumagalli
31  * @author Copyright &copy; 2000-2001 <a HREF="http://www.apache.org/">The
32  * Apache Software Foundation</a>. All rights reserved.
33  * @version 1.0 <i>(CVS $Revision: 155409 $)</i>
34  */
35 public interface Daemon {
36
37     /**
38      * Initialize this <code>Daemon</code> instance.
39      * <p>
40      * This method gets called once the JVM process is created and the
41      * <code>Daemon</code> instance is created thru its empty public
42      * constructor.
43      * </p>
44      * <p>
45      * Under certain operating systems (typically Unix based operating
46      * systems) and if the native invocation framework is configured to do
47      * so, this method might be called with <i>super-user</i> privileges.
48      * </p>
49      * <p>
50      * For example, it might be wise to create <code>ServerSocket</code>
51      * instances within the scope of this method, and perform all operations
52      * requiring <i>super-user</i> privileges in the underlying operating
53      * system.
54      * </p>
55      * <p>
56      * Apart from set up and allocation of native resources, this method
57      * must not start the actual operation of the <code>Daemon</code> (such
58      * as starting threads calling the <code>ServerSocket.accept()</code>
59      * method) as this would impose some serious security hazards. The
60      * start of operation must be performed in the <code>start()</code>
61      * method.
62      * </p>
63      *
64      * @param context A <code>DaemonContext</code> object used to
65      * communicate with the container.
66      *
67      * @exception Exception Any exception preventing a successful
68      * initialization.
69      */
70     public void init(DaemonContext context)
71     throws Exception JavaDoc;
72
73     /**
74      * Start the operation of this <code>Daemon</code> instance. This
75      * method is to be invoked by the environment after the init()
76      * method has been successfully invoked and possibly the security
77      * level of the JVM has been dropped. <code>Implementors of this
78      * method are free to start any number of threads, but need to
79      * return control avfter having done that to enable invocation of
80      * the stop()-method.
81      */
82     public void start()
83     throws Exception JavaDoc;
84
85     /**
86      * Stop the operation of this <code>Daemon</code> instance. Note
87      * that the proper place to free any allocated resources such as
88      * sockets or file descriptors is in the destroy method, as the
89      * container may restart the Daemon by calling start() after
90      * stop().
91      */
92     public void stop()
93     throws Exception JavaDoc;
94
95     /**
96      * Free any resources allocated by this daemon such as file
97      * descriptors or sockets. This method gets called by the container
98      * after stop() has been called, before the JVM exits. The Daemon
99      * 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
Popular Tags