1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
/*
* Copyright (C) 2009 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.common.util.concurrent;
import com.google.common.annotations.Beta;
import java.util.concurrent.ExecutionException;
/**
* An object with an operational state, plus asynchronous {@link #start()} and
* {@link #stop()} lifecycle methods to transfer into and out of this state.
* Example services include webservers, RPC servers and timers. The normal
* lifecycle of a service is:
* <ul>
* <li>{@link State#NEW} -></li>
* <li>{@link State#STARTING} -></li>
* <li>{@link State#RUNNING} -></li>
* <li>{@link State#STOPPING} -></li>
* <li>{@link State#TERMINATED}</li>
* </ul>
*
* If the service fails while starting, running or stopping, its state will be
* {@link State#FAILED}, and its behavior is undefined. Such a service cannot be
* started nor stopped.
*
* <p>Implementors of this interface are strongly encouraged to extend one of
* the abstract classes in this package which implement this interface and
* make the threading and state management easier.
*
* @author Jesse Wilson
* @since 9.0 (in 1.0 as
* {@code com.google.common.base.Service})
*/
@Beta // TODO(kevinb): make abstract class?
public interface Service {
/**
* If the service state is {@link State#NEW}, this initiates service startup
* and returns immediately. If the service has already been started, this
* method returns immediately without taking action. A stopped service may not
* be restarted.
*
* @return a future for the startup result, regardless of whether this call
* initiated startup. Calling {@link ListenableFuture#get} will block
* until the service has finished starting, and returns one of {@link
* State#RUNNING}, {@link State#STOPPING} or {@link State#TERMINATED}. If
* the service fails to start, {@link ListenableFuture#get} will throw an
* {@link ExecutionException}, and the service's state will be {@link
* State#FAILED}. If it has already finished starting, {@link
* ListenableFuture#get} returns immediately. Cancelling this future has
* no effect on the service.
*/
ListenableFuture<State> start();
/**
* Initiates service startup (if necessary), returning once the service has
* finished starting. Unlike calling {@code start().get()}, this method throws
* no checked exceptions, and it cannot be {@linkplain Thread#interrupt
* interrupted}.
*
* @throws UncheckedExecutionException if startup failed
* @return the state of the service when startup finished.
*/
State startAndWait();
/**
* Returns {@code true} if this service is {@linkplain State#RUNNING running}.
*/
boolean isRunning();
/**
* Returns the lifecycle state of the service.
*/
State state();
/**
* If the service is {@linkplain State#STARTING starting} or {@linkplain
* State#RUNNING running}, this initiates service shutdown and returns
* immediately. If the service is {@linkplain State#NEW new}, it is
* {@linkplain State#TERMINATED terminated} without having been started nor
* stopped. If the service has already been stopped, this method returns
* immediately without taking action.
*
* @return a future for the shutdown result, regardless of whether this call
* initiated shutdown. Calling {@link ListenableFuture#get} will block
* until the service has finished shutting down, and either returns
* {@link State#TERMINATED} or throws an {@link ExecutionException}. If
* it has already finished stopping, {@link ListenableFuture#get} returns
* immediately. Cancelling this future has no effect on the service.
*/
ListenableFuture<State> stop();
/**
* Initiates service shutdown (if necessary), returning once the service has
* finished stopping. If this is {@link State#STARTING}, startup will be
* cancelled. If this is {@link State#NEW}, it is {@link State#TERMINATED
* terminated} without having been started nor stopped. Unlike calling {@code
* stop().get()}, this method throws no checked exceptions.
*
* @throws UncheckedExecutionException if shutdown failed
* @return the state of the service when shutdown finished.
*/
State stopAndWait();
/**
* The lifecycle states of a service.
*
* @since 9.0 (in 1.0 as
* {@code com.google.common.base.Service.State})
*/
@Beta // should come out of Beta when Service does
enum State {
/**
* A service in this state is inactive. It does minimal work and consumes
* minimal resources.
*/
NEW,
/**
* A service in this state is transitioning to {@link #RUNNING}.
*/
STARTING,
/**
* A service in this state is operational.
*/
RUNNING,
/**
* A service in this state is transitioning to {@link #TERMINATED}.
*/
STOPPING,
/**
* A service in this state has completed execution normally. It does minimal
* work and consumes minimal resources.
*/
TERMINATED,
/**
* A service in this state has encountered a problem and may not be
* operational. It cannot be started nor stopped.
*/
FAILED
}
}
|
