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 * https://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.configuration2.reloading;
18
19 import org.apache.commons.configuration2.event.Event;
20 import org.apache.commons.configuration2.event.EventListener;
21 import org.apache.commons.configuration2.event.EventListenerList;
22 import org.apache.commons.configuration2.event.EventSource;
23 import org.apache.commons.configuration2.event.EventType;
24
25 /**
26 * <p>
27 * A class for adding support for reload operations in a generic way.
28 * </p>
29 * <p>
30 * A {@code ReloadingController} monitors a specific source and triggers reloading events if necessary. So it does not
31 * perform reloading itself, but only sends out notifications when it thinks that this should be done. This allows for a
32 * very generic setup in which different components involved in reloading are loosely coupled via events.
33 * </p>
34 * <p>
35 * A typical usage scenario is as follows:
36 * </p>
37 * <ul>
38 * <li>A {@code ReloadingController} instance is created and initialized with a {@link ReloadingDetector} object.</li>
39 * <li>A number of {@link EventListener} objects for reloading events can be registered at the controller.</li>
40 * <li>Now the controller's {@code checkForReloading()} method is called whenever a check is to be performed. This could
41 * be done for instance by a timer in regular intervals or by any other means appropriate for a specific
42 * application.</li>
43 * <li>When a check reveals that a reload operation is necessary all registered event listeners are notified.</li>
44 * <li>Typically one of the listeners is responsible to perform the actual reload operation. (How this is done is not in
45 * the scope of the controller object.) After this has been done, the controller's {@code resetReloadingState()} method
46 * must be called. It tells the controller that the last notification has been processed and that new checks are
47 * possible again. It is important that this method is called. Otherwise, {@code checkForReloading()} will not do any
48 * new checks or send out event notifications any more.</li>
49 * </ul>
50 * <p>
51 * This class can be accessed from multiple threads concurrently. It shields the associated {@link ReloadingDetector}
52 * object for concurrent access, so that a concrete detector implementation does not have to be thread-safe.
53 * </p>
54 *
55 * @since 2.0
56 */
57 public class ReloadingController implements EventSource {
58
59 /** Stores a reference to the reloading detector. */
60 private final ReloadingDetector detector;
61
62 /** The helper object which manages the registered event listeners. */
63 private final EventListenerList listeners;
64
65 /** A flag whether this controller is in reloading state. */
66 private boolean reloadingState;
67
68 /**
69 * Creates a new instance of {@code ReloadingController} and associates it with the given {@code ReloadingDetector}
70 * object.
71 *
72 * @param detect the {@code ReloadingDetector} (must not be <strong>null</strong>)
73 * @throws IllegalArgumentException if the detector is undefined
74 */
75 public ReloadingController(final ReloadingDetector detect) {
76 if (detect == null) {
77 throw new IllegalArgumentException("ReloadingDetector must not be null.");
78 }
79
80 detector = detect;
81 listeners = new EventListenerList();
82 }
83
84 /**
85 * {@inheritDoc} This class generates events of type {@code ReloadingEvent}.
86 */
87 @Override
88 public <T extends Event> void addEventListener(final EventType<T> eventType, final EventListener<? super T> listener) {
89 listeners.addEventListener(eventType, listener);
90 }
91
92 /**
93 * Performs a check whether a reload operation is necessary. This method has to be called to trigger the generation of
94 * reloading events. It delegates to the associated {@link ReloadingDetector} and sends out notifications if necessary.
95 * The argument can be an arbitrary data object; it will be part of the event notification sent out when a reload
96 * operation should be performed. The return value indicates whether a change was detected and an event was sent. Once a
97 * need for a reload is detected, this controller is in <em>reloading state</em>. Until this state is reset (by calling
98 * {@link #resetReloadingState()}), no further reloading checks are performed by this method, and no events are fired;
99 * it then returns always <strong>true</strong>.
100 *
101 * @param data additional data for an event notification
102 * @return a flag whether a reload operation is necessary
103 */
104 public boolean checkForReloading(final Object data) {
105 boolean sendEvent = false;
106 synchronized (this) {
107 if (isInReloadingState()) {
108 return true;
109 }
110 if (getDetector().isReloadingRequired()) {
111 sendEvent = true;
112 reloadingState = true;
113 }
114 }
115
116 if (sendEvent) {
117 listeners.fire(new ReloadingEvent(this, data));
118 return true;
119 }
120 return false;
121 }
122
123 /**
124 * Gets the {@code ReloadingDetector} used by this controller.
125 *
126 * @return the {@code ReloadingDetector}
127 */
128 public ReloadingDetector getDetector() {
129 return detector;
130 }
131
132 /**
133 * Tests whether this controller is in <em>reloading state</em>. A return value of <strong>true</strong> means that a previous
134 * invocation of {@code checkForReloading()} has detected the necessity for a reload operation, but
135 * {@code resetReloadingState()} has not been called yet. In this state no further reloading checks are possible.
136 *
137 * @return a flag whether this controller is in reloading state
138 */
139 public synchronized boolean isInReloadingState() {
140 return reloadingState;
141 }
142
143 @Override
144 public <T extends Event> boolean removeEventListener(final EventType<T> eventType, final EventListener<? super T> listener) {
145 return listeners.removeEventListener(eventType, listener);
146 }
147
148 /**
149 * Resets the reloading state. This tells the controller that reloading has been performed and new checks are possible
150 * again. If this controller is not in reloading state, this method has no effect.
151 */
152 public synchronized void resetReloadingState() {
153 if (isInReloadingState()) {
154 getDetector().reloadingPerformed();
155 reloadingState = false;
156 }
157 }
158 }