001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.configuration2.reloading; 018 019import org.apache.commons.configuration2.event.Event; 020import org.apache.commons.configuration2.event.EventListener; 021import org.apache.commons.configuration2.event.EventListenerList; 022import org.apache.commons.configuration2.event.EventSource; 023import org.apache.commons.configuration2.event.EventType; 024 025/** 026 * <p> 027 * A class for adding support for reload operations in a generic way. 028 * </p> 029 * <p> 030 * A {@code ReloadingController} monitors a specific source and triggers 031 * reloading events if necessary. So it does not perform reloading itself, but 032 * only sends out notifications when it thinks that this should be done. This 033 * allows for a very generic setup in which different components involved in 034 * reloading are loosely coupled via events. 035 * </p> 036 * <p> 037 * A typical usage scenario is as follows: 038 * </p> 039 * <ul> 040 * <li>A {@code ReloadingController} instance is created and initialized with a 041 * {@link ReloadingDetector} object.</li> 042 * <li>A number of {@link EventListener} objects for reloading events can be 043 * registered at the controller.</li> 044 * <li>Now the controller's {@code checkForReloading()} method is called 045 * whenever a check is to be performed. This could be done for instance by a 046 * timer in regular intervals or by any other means appropriate for a specific 047 * application.</li> 048 * <li>When a check reveals that a reload operation is necessary all registered 049 * event listeners are notified.</li> 050 * <li>Typically one of the listeners is responsible to perform the actual 051 * reload operation. (How this is done is not in the scope of the controller 052 * object.) After this has been done, the controller's 053 * {@code resetReloadingState()} method must be called. It tells the controller 054 * that the last notification has been processed and that new checks are 055 * possible again. It is important that this method is called. Otherwise, 056 * {@code checkForReloading()} will not do any new checks or send out event 057 * notifications any more.</li> 058 * </ul> 059 * <p> 060 * This class can be accessed from multiple threads concurrently. It shields the 061 * associated {@link ReloadingDetector} object for concurrent access, so that a 062 * concrete detector implementation does not have to be thread-safe. 063 * </p> 064 * 065 * @version $Id: ReloadingController.java 1842194 2018-09-27 22:24:23Z ggregory $ 066 * @since 2.0 067 */ 068public class ReloadingController implements EventSource 069{ 070 /** Stores a reference to the reloading detector. */ 071 private final ReloadingDetector detector; 072 073 /** The helper object which manages the registered event listeners. */ 074 private final EventListenerList listeners; 075 076 /** A flag whether this controller is in reloading state. */ 077 private boolean reloadingState; 078 079 /** 080 * Creates a new instance of {@code ReloadingController} and associates it 081 * with the given {@code ReloadingDetector} object. 082 * 083 * @param detect the {@code ReloadingDetector} (must not be <b>null</b>) 084 * @throws IllegalArgumentException if the detector is undefined 085 */ 086 public ReloadingController(final ReloadingDetector detect) 087 { 088 if (detect == null) 089 { 090 throw new IllegalArgumentException( 091 "ReloadingDetector must not be null!"); 092 } 093 094 detector = detect; 095 listeners = new EventListenerList(); 096 } 097 098 /** 099 * Returns the {@code ReloadingDetector} used by this controller. 100 * 101 * @return the {@code ReloadingDetector} 102 */ 103 public ReloadingDetector getDetector() 104 { 105 return detector; 106 } 107 108 /** 109 * {@inheritDoc} This class generates events of type {@code ReloadingEvent}. 110 */ 111 @Override 112 public <T extends Event> void addEventListener( 113 final EventType<T> eventType, final EventListener<? super T> listener) 114 { 115 listeners.addEventListener(eventType, listener); 116 } 117 118 @Override 119 public <T extends Event> boolean removeEventListener( 120 final EventType<T> eventType, final EventListener<? super T> listener) 121 { 122 return listeners.removeEventListener(eventType, listener); 123 } 124 125 /** 126 * Tests whether this controller is in <em>reloading state</em>. A return 127 * value of <b>true</b> means that a previous invocation of 128 * {@code checkForReloading()} has detected the necessity for a reload 129 * operation, but {@code resetReloadingState()} has not been called yet. In 130 * this state no further reloading checks are possible. 131 * 132 * @return a flag whether this controller is in reloading state 133 */ 134 public synchronized boolean isInReloadingState() 135 { 136 return reloadingState; 137 } 138 139 /** 140 * Performs a check whether a reload operation is necessary. This method has 141 * to be called to trigger the generation of reloading events. It delegates 142 * to the associated {@link ReloadingDetector} and sends out notifications 143 * if necessary. The argument can be an arbitrary data object; it will be 144 * part of the event notification sent out when a reload operation should be 145 * performed. The return value indicates whether a change was detected and 146 * an event was sent. Once a need for a reload is detected, this controller 147 * is in <em>reloading state</em>. Until this state is reset (by calling 148 * {@link #resetReloadingState()}), no further reloading checks are 149 * performed by this method, and no events are fired; it then returns always 150 * <b>true</b>. 151 * 152 * @param data additional data for an event notification 153 * @return a flag whether a reload operation is necessary 154 */ 155 public boolean checkForReloading(final Object data) 156 { 157 boolean sendEvent = false; 158 synchronized (this) 159 { 160 if (isInReloadingState()) 161 { 162 return true; 163 } 164 if (getDetector().isReloadingRequired()) 165 { 166 sendEvent = true; 167 reloadingState = true; 168 } 169 } 170 171 if (sendEvent) 172 { 173 listeners.fire(new ReloadingEvent(this, data)); 174 return true; 175 } 176 return false; 177 } 178 179 /** 180 * Resets the reloading state. This tells the controller that reloading has 181 * been performed and new checks are possible again. If this controller is 182 * not in reloading state, this method has no effect. 183 */ 184 public synchronized void resetReloadingState() 185 { 186 if (isInReloadingState()) 187 { 188 getDetector().reloadingPerformed(); 189 reloadingState = false; 190 } 191 } 192}