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