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 reloading events if necessary. So it does not 031 * perform reloading itself, but only sends out notifications when it thinks that this should be done. This allows for a 032 * very generic setup in which different components involved in reloading are loosely coupled via events. 033 * </p> 034 * <p> 035 * A typical usage scenario is as follows: 036 * </p> 037 * <ul> 038 * <li>A {@code ReloadingController} instance is created and initialized with a {@link ReloadingDetector} object.</li> 039 * <li>A number of {@link EventListener} objects for reloading events can be registered at the controller.</li> 040 * <li>Now the controller's {@code checkForReloading()} method is called whenever a check is to be performed. This could 041 * be done for instance by a timer in regular intervals or by any other means appropriate for a specific 042 * application.</li> 043 * <li>When a check reveals that a reload operation is necessary all registered event listeners are notified.</li> 044 * <li>Typically one of the listeners is responsible to perform the actual reload operation. (How this is done is not in 045 * the scope of the controller object.) After this has been done, the controller's {@code resetReloadingState()} method 046 * must be called. It tells the controller that the last notification has been processed and that new checks are 047 * possible again. It is important that this method is called. Otherwise, {@code checkForReloading()} will not do any 048 * new checks or send out event notifications any more.</li> 049 * </ul> 050 * <p> 051 * This class can be accessed from multiple threads concurrently. It shields the associated {@link ReloadingDetector} 052 * object for concurrent access, so that a concrete detector implementation does not have to be thread-safe. 053 * </p> 054 * 055 * @since 2.0 056 */ 057public class ReloadingController implements EventSource { 058 /** Stores a reference to the reloading detector. */ 059 private final ReloadingDetector detector; 060 061 /** The helper object which manages the registered event listeners. */ 062 private final EventListenerList listeners; 063 064 /** A flag whether this controller is in reloading state. */ 065 private boolean reloadingState; 066 067 /** 068 * Creates a new instance of {@code ReloadingController} and associates it with the given {@code ReloadingDetector} 069 * object. 070 * 071 * @param detect the {@code ReloadingDetector} (must not be <b>null</b>) 072 * @throws IllegalArgumentException if the detector is undefined 073 */ 074 public ReloadingController(final ReloadingDetector detect) { 075 if (detect == null) { 076 throw new IllegalArgumentException("ReloadingDetector must not be null!"); 077 } 078 079 detector = detect; 080 listeners = new EventListenerList(); 081 } 082 083 /** 084 * Gets the {@code ReloadingDetector} used by this controller. 085 * 086 * @return the {@code ReloadingDetector} 087 */ 088 public ReloadingDetector getDetector() { 089 return detector; 090 } 091 092 /** 093 * {@inheritDoc} This class generates events of type {@code ReloadingEvent}. 094 */ 095 @Override 096 public <T extends Event> void addEventListener(final EventType<T> eventType, final EventListener<? super T> listener) { 097 listeners.addEventListener(eventType, listener); 098 } 099 100 @Override 101 public <T extends Event> boolean removeEventListener(final EventType<T> eventType, final EventListener<? super T> listener) { 102 return listeners.removeEventListener(eventType, listener); 103 } 104 105 /** 106 * Tests whether this controller is in <em>reloading state</em>. A return value of <b>true</b> means that a previous 107 * invocation of {@code checkForReloading()} has detected the necessity for a reload operation, but 108 * {@code resetReloadingState()} has not been called yet. In this state no further reloading checks are possible. 109 * 110 * @return a flag whether this controller is in reloading state 111 */ 112 public synchronized boolean isInReloadingState() { 113 return reloadingState; 114 } 115 116 /** 117 * Performs a check whether a reload operation is necessary. This method has to be called to trigger the generation of 118 * reloading events. It delegates to the associated {@link ReloadingDetector} and sends out notifications if necessary. 119 * The argument can be an arbitrary data object; it will be part of the event notification sent out when a reload 120 * operation should be performed. The return value indicates whether a change was detected and an event was sent. Once a 121 * need for a reload is detected, this controller is in <em>reloading state</em>. Until this state is reset (by calling 122 * {@link #resetReloadingState()}), no further reloading checks are performed by this method, and no events are fired; 123 * it then returns always <b>true</b>. 124 * 125 * @param data additional data for an event notification 126 * @return a flag whether a reload operation is necessary 127 */ 128 public boolean checkForReloading(final Object data) { 129 boolean sendEvent = false; 130 synchronized (this) { 131 if (isInReloadingState()) { 132 return true; 133 } 134 if (getDetector().isReloadingRequired()) { 135 sendEvent = true; 136 reloadingState = true; 137 } 138 } 139 140 if (sendEvent) { 141 listeners.fire(new ReloadingEvent(this, data)); 142 return true; 143 } 144 return false; 145 } 146 147 /** 148 * Resets the reloading state. This tells the controller that reloading has been performed and new checks are possible 149 * again. If this controller is not in reloading state, this method has no effect. 150 */ 151 public synchronized void resetReloadingState() { 152 if (isInReloadingState()) { 153 getDetector().reloadingPerformed(); 154 reloadingState = false; 155 } 156 } 157}