1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang3.concurrent;
18
19 /**
20 * An interface describing a <a
21 * href="https://martinfowler.com/bliki/CircuitBreaker.html">Circuit Breaker</a> component.
22 *
23 * <p>
24 * A <em>circuit breaker</em> can be used to protect an application against unreliable
25 * services or unexpected load. It typically monitors a specific resource. As long as this
26 * resource works as expected, it stays in state <em>closed</em>, meaning that the
27 * resource can be used. If problems are encountered when using the resource, the circuit
28 * breaker can switch into state <em>open</em>; then access to this resource is
29 * prohibited. Depending on a concrete implementation, it is possible that the circuit
30 * breaker switches back to state <em>closed</em> when the resource becomes available
31 * again.
32 * </p>
33 * <p>
34 * This interface defines a generic protocol of a circuit breaker component. It should be
35 * sufficiently generic to be applied to multiple different use cases.
36 * </p>
37 *
38 * @param <T> the type of the value monitored by this circuit breaker
39 * @since 3.5
40 */
41 public interface CircuitBreaker<T> {
42
43 /**
44 * Checks the state of this circuit breaker and changes it if necessary. The return
45 * value indicates whether the circuit breaker is now in state <em>closed</em>; a value
46 * of <strong>true</strong> typically means that the current operation can continue.
47 *
48 * @return <strong>true</strong> if the circuit breaker is now closed;
49 * <strong>false</strong> otherwise.
50 */
51 boolean checkState();
52
53 /**
54 * Closes this circuit breaker. Its state is changed to closed. If this circuit
55 * breaker is already closed, this method has no effect.
56 */
57 void close();
58
59 /**
60 * Increments the monitored value and performs a check of the current state of this
61 * circuit breaker. This method works like {@link #checkState()}, but the monitored
62 * value is incremented before the state check is performed.
63 *
64 * @param increment value to increment in the monitored value of the circuit breaker
65 * @return <strong>true</strong> if the circuit breaker is now closed;
66 * <strong>false</strong> otherwise
67 */
68 boolean incrementAndCheckState(T increment);
69
70 /**
71 * Tests the current closed state of this circuit breaker. A return value of
72 * <strong>true</strong> means that the circuit breaker is currently closed. This
73 * means that everything is okay with the monitored subsystem.
74 *
75 * @return the current closed state of this circuit breaker.
76 */
77 boolean isClosed();
78
79 /**
80 * Tests the current open state of this circuit breaker. A return value of
81 * <strong>true</strong> means that the circuit breaker is currently open indicating a
82 * problem in the monitored subsystem.
83 *
84 * @return the current open state of this circuit breaker.
85 */
86 boolean isOpen();
87
88 /**
89 * Opens this circuit breaker. Its state is changed to open. Depending on a concrete
90 * implementation, it may close itself again if the monitored subsystem becomes
91 * available. If this circuit breaker is already open, this method has no effect.
92 */
93 void open();
94 }