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 }