1 /*
2 * ModeShape (http://www.modeshape.org)
3 * See the COPYRIGHT.txt file distributed with this work for information
4 * regarding copyright ownership. Some portions may be licensed
5 * to Red Hat, Inc. under one or more contributor license agreements.
6 * See the AUTHORS.txt file in the distribution for a full listing of
7 * individual contributors.
8 *
9 * ModeShape is free software. Unless otherwise indicated, all code in ModeShape
10 * is licensed to you under the terms of the GNU Lesser General Public License as
11 * published by the Free Software Foundation; either version 2.1 of
12 * the License, or (at your option) any later version.
13 *
14 * ModeShape is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this software; if not, write to the Free
21 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
23 */
24 package org.modeshape.repository.service;
25
26 import java.util.concurrent.TimeUnit;
27 import net.jcip.annotations.ThreadSafe;
28
29 /**
30 * Contract defining an administrative interface for controlling the running state of a service.
31 */
32 @ThreadSafe
33 public interface ServiceAdministrator {
34
35 /**
36 * The available states.
37 *
38 * @author Randall Hauch
39 */
40 public static enum State {
41 STARTED,
42 PAUSED,
43 SHUTDOWN,
44 TERMINATED;
45 }
46
47 /**
48 * Return the current state of this system.
49 *
50 * @return the current state
51 */
52 public State getState();
53
54 /**
55 * Set the state of the system. This method does nothing if the desired state matches the current state.
56 *
57 * @param state the desired state
58 * @return this object for method chaining purposes
59 * @see #setState(String)
60 * @see #start()
61 * @see #pause()
62 * @see #shutdown()
63 */
64 public ServiceAdministrator setState( State state );
65
66 /**
67 * Set the state of the system. This method does nothing if the desired state matches the current state.
68 *
69 * @param state the desired state in string form
70 * @return this object for method chaining purposes
71 * @throws IllegalArgumentException if the specified state string is null or does not match one of the predefined
72 * {@link State predefined enumerated values}
73 * @see #setState(State)
74 * @see #start()
75 * @see #pause()
76 * @see #shutdown()
77 */
78 public ServiceAdministrator setState( String state );
79
80 /**
81 * Start monitoring and sequence the events. This method can be called multiple times, including after the system is
82 * {@link #pause() paused}. However, once the system is {@link #shutdown() shutdown}, it cannot be started or paused.
83 *
84 * @return this object for method chaining purposes
85 * @throws IllegalStateException if called when the system has been {@link #shutdown() shutdown}.
86 * @see #pause()
87 * @see #shutdown()
88 * @see #isStarted()
89 */
90 public ServiceAdministrator start();
91
92 /**
93 * Temporarily stop monitoring and sequencing events. This method can be called multiple times, including after the system is
94 * {@link #start() started}. However, once the system is {@link #shutdown() shutdown}, it cannot be started or paused.
95 *
96 * @return this object for method chaining purposes
97 * @throws IllegalStateException if called when the system has been {@link #shutdown() shutdown}.
98 * @see #start()
99 * @see #shutdown()
100 * @see #isPaused()
101 */
102 public ServiceAdministrator pause();
103
104 /**
105 * Permanently stop monitoring and sequencing events. This method can be called multiple times, but only the first call has an
106 * effect. Once the system has been shutdown, it may not be {@link #start() restarted} or {@link #pause() paused}.
107 *
108 * @return this object for method chaining purposes
109 * @see #start()
110 * @see #pause()
111 * @see #isShutdown()
112 */
113 public ServiceAdministrator shutdown();
114
115 /**
116 * Blocks until the shutdown has completed, or the timeout occurs, or the current thread is interrupted, whichever happens
117 * first.
118 *
119 * @param timeout the maximum time to wait
120 * @param unit the time unit of the timeout argument
121 * @return <tt>true</tt> if this service complete shut down and <tt>false</tt> if the timeout elapsed before it was shut down
122 * completely
123 * @throws InterruptedException if interrupted while waiting
124 */
125 boolean awaitTermination( long timeout,
126 TimeUnit unit ) throws InterruptedException;
127
128 /**
129 * Return whether this system has been started and is currently running.
130 *
131 * @return true if started and currently running, or false otherwise
132 * @see #start()
133 * @see #pause()
134 * @see #isPaused()
135 * @see #isShutdown()
136 * @see #isTerminated()
137 */
138 public boolean isStarted();
139
140 /**
141 * Return whether this system is currently paused.
142 *
143 * @return true if currently paused, or false otherwise
144 * @see #pause()
145 * @see #start()
146 * @see #isStarted()
147 * @see #isShutdown()
148 * @see #isTerminated()
149 */
150 public boolean isPaused();
151
152 /**
153 * Return whether this system has been shut down.
154 *
155 * @return true if this service has been shut down, or false otherwise
156 * @see #shutdown()
157 * @see #isPaused()
158 * @see #isStarted()
159 * @see #isTerminated()
160 */
161 public boolean isShutdown();
162
163 /**
164 * Return whether this system has finished {@link #shutdown() shutting down}. Note that <code>isTerminated</code> is never
165 * <code>true</code> unless either {@link #shutdown()} was called first.
166 *
167 * @return true if the system has finished shutting down, or false otherwise
168 * @see #shutdown()
169 * @see #isPaused()
170 * @see #isStarted()
171 * @see #isShutdown()
172 */
173 public boolean isTerminated();
174
175 }