1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.daemon;
19
20 /**
21 * Provides support for native daemon invocation. Using
22 * a platform dependant helper program, classes that implement the
23 * {@code Daemon} interface can be initialized, started and
24 * stopped according to the conventions of the underlying operating
25 * system.
26 * <p>
27 * Implementors of this interface must also provide a public constructor
28 * with no arguments so that instances can be created in an automated
29 * fashion.
30 * </p>
31 */
32 public interface Daemon
33 {
34
35 /**
36 * Initializes this {@code Daemon} instance.
37 * <p>
38 * This method gets called once the JVM process is created and the
39 * {@code Daemon} instance is created thru its empty public
40 * constructor.
41 * </p>
42 * <p>
43 * Under certain operating systems (typically Unix based operating
44 * systems) and if the native invocation framework is configured to do
45 * so, this method might be called with <i>super-user</i> privileges.
46 * </p>
47 * <p>
48 * For example, it might be wise to create {@code ServerSocket}
49 * instances within the scope of this method, and perform all operations
50 * requiring <i>super-user</i> privileges in the underlying operating
51 * system.
52 * </p>
53 * <p>
54 * Apart from set up and allocation of native resources, this method
55 * must not start the actual operation of the {@code Daemon} (such
56 * as starting threads calling the {@code ServerSocket.accept()}
57 * method) as this would impose some serious security hazards. The
58 * start of operation must be performed in the {@code start()}
59 * method.
60 * </p>
61 *
62 * @param context A {@code DaemonContext} object used to
63 * communicate with the container.
64 * @throws DaemonInitException An exception that prevented
65 * initialization where you want to display a nice message to the user,
66 * rather than a stack trace.
67 * @throws Exception Any exception preventing a successful
68 * initialization.
69 */
70 void init(DaemonContext context)
71 throws DaemonInitException, Exception;
72
73 /**
74 * Starts the operation of this {@code Daemon} 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. Implementors of this
78 * method are free to start any number of threads, but need to
79 * return control after having done that to enable invocation of
80 * the stop()-method.
81 *
82 * @throws Exception If the start was not successful
83 */
84 void start()
85 throws Exception;
86
87 /**
88 * Stops the operation of this {@code Daemon} instance. Note
89 * that the proper place to free any allocated resources such as
90 * sockets or file descriptors is in the destroy method, as the
91 * container may restart the Daemon by calling start() after
92 * stop().
93 *
94 * @throws Exception If the stop was not successful
95 */
96 void stop()
97 throws Exception;
98
99 /**
100 * Frees any resources allocated by this daemon such as file
101 * descriptors or sockets. This method gets called by the container
102 * after stop() has been called, before the JVM exits. The Daemon
103 * can not be restarted after this method has been called without a
104 * new call to the init() method.
105 */
106 void destroy();
107 }
108