001 /*
002 * JBoss, Home of Professional Open Source.
003 * Copyright 2008, Red Hat Middleware LLC, and individual contributors
004 * as indicated by the @author tags. See the copyright.txt file in the
005 * distribution for a full listing of individual contributors.
006 *
007 * This is free software; you can redistribute it and/or modify it
008 * under the terms of the GNU Lesser General Public License as
009 * published by the Free Software Foundation; either version 2.1 of
010 * the License, or (at your option) any later version.
011 *
012 * This software is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this software; if not, write to the Free
019 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021 */
022 package org.jboss.dna.repository.services;
023
024 import java.util.concurrent.TimeUnit;
025 import net.jcip.annotations.ThreadSafe;
026
027 /**
028 * Contract defining an administrative interface for controlling the running state of a service.
029 *
030 * @author Randall Hauch
031 */
032 @ThreadSafe
033 public interface ServiceAdministrator {
034
035 /**
036 * The available states.
037 *
038 * @author Randall Hauch
039 */
040 public static enum State {
041 STARTED,
042 PAUSED,
043 SHUTDOWN,
044 TERMINATED;
045 }
046
047 /**
048 * Return the current state of this system.
049 *
050 * @return the current state
051 */
052 public State getState();
053
054 /**
055 * Set the state of the system. This method does nothing if the desired state matches the current state.
056 *
057 * @param state the desired state
058 * @return this object for method chaining purposes
059 * @see #setState(String)
060 * @see #start()
061 * @see #pause()
062 * @see #shutdown()
063 */
064 public ServiceAdministrator setState( State state );
065
066 /**
067 * Set the state of the system. This method does nothing if the desired state matches the current state.
068 *
069 * @param state the desired state in string form
070 * @return this object for method chaining purposes
071 * @throws IllegalArgumentException if the specified state string is null or does not match one of the predefined
072 * {@link State predefined enumerated values}
073 * @see #setState(State)
074 * @see #start()
075 * @see #pause()
076 * @see #shutdown()
077 */
078 public ServiceAdministrator setState( String state );
079
080 /**
081 * Start monitoring and sequence the events. This method can be called multiple times, including after the system is
082 * {@link #pause() paused}. However, once the system is {@link #shutdown() shutdown}, it cannot be started or paused.
083 *
084 * @return this object for method chaining purposes
085 * @throws IllegalStateException if called when the system has been {@link #shutdown() shutdown}.
086 * @see #pause()
087 * @see #shutdown()
088 * @see #isStarted()
089 */
090 public ServiceAdministrator start();
091
092 /**
093 * Temporarily stop monitoring and sequencing events. This method can be called multiple times, including after the system is
094 * {@link #start() started}. However, once the system is {@link #shutdown() shutdown}, it cannot be started or paused.
095 *
096 * @return this object for method chaining purposes
097 * @throws IllegalStateException if called when the system has been {@link #shutdown() shutdown}.
098 * @see #start()
099 * @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
122 * down completely
123 * @throws InterruptedException if interrupted while waiting
124 */
125 boolean awaitTermination( long timeout, TimeUnit unit ) throws InterruptedException;
126
127 /**
128 * Return whether this system has been started and is currently running.
129 *
130 * @return true if started and currently running, or false otherwise
131 * @see #start()
132 * @see #pause()
133 * @see #isPaused()
134 * @see #isShutdown()
135 * @see #isTerminated()
136 */
137 public boolean isStarted();
138
139 /**
140 * Return whether this system is currently paused.
141 *
142 * @return true if currently paused, or false otherwise
143 * @see #pause()
144 * @see #start()
145 * @see #isStarted()
146 * @see #isShutdown()
147 * @see #isTerminated()
148 */
149 public boolean isPaused();
150
151 /**
152 * Return whether this system has been shut down.
153 *
154 * @return true if this service has been shut down, or false otherwise
155 * @see #shutdown()
156 * @see #isPaused()
157 * @see #isStarted()
158 * @see #isTerminated()
159 */
160 public boolean isShutdown();
161
162 /**
163 * Return whether this system has finished {@link #shutdown() shutting down}. Note that <code>isTerminated</code> is never
164 * <code>true</code> unless either {@link #shutdown()} was called first.
165 *
166 * @return true if the system has finished shutting down, or false otherwise
167 * @see #shutdown()
168 * @see #isPaused()
169 * @see #isStarted()
170 * @see #isShutdown()
171 */
172 public boolean isTerminated();
173
174 }