org.apache.commons.configuration2.reloading.ReloadingController Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of commons-configuration2 Show documentation
Tools to assist in the reading of configuration/preferences files in various formats
There is a newer version: 2.10.1
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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 org.apache.commons.configuration2.reloading;

import org.apache.commons.configuration2.event.Event;
import org.apache.commons.configuration2.event.EventListener;
import org.apache.commons.configuration2.event.EventListenerList;
import org.apache.commons.configuration2.event.EventSource;
import org.apache.commons.configuration2.event.EventType;

/**
 * 
 * A class for adding support for reload operations in a generic way.
 * 
 * 
 * A {@code ReloadingController} monitors a specific source and triggers
 * reloading events if necessary. So it does not perform reloading itself, but
 * only sends out notifications when it thinks that this should be done. This
 * allows for a very generic setup in which different components involved in
 * reloading are loosely coupled via events.
 * 
 * 
 * A typical usage scenario is as follows:
 * 
 * 
 * A {@code ReloadingController} instance is created and initialized with a
 * {@link ReloadingDetector} object.
 * A number of {@link EventListener} objects for reloading events can be
 * registered at the controller.
 * Now the controller's {@code checkForReloading()} method is called
 * whenever a check is to be performed. This could be done for instance by a
 * timer in regular intervals or by any other means appropriate for a specific
 * application.
 * When a check reveals that a reload operation is necessary all registered
 * event listeners are notified.
 * Typically one of the listeners is responsible to perform the actual
 * reload operation. (How this is done is not in the scope of the controller
 * object.) After this has been done, the controller's
 * {@code resetReloadingState()} method must be called. It tells the controller
 * that the last notification has been processed and that new checks are
 * possible again. It is important that this method is called. Otherwise,
 * {@code checkForReloading()} will not do any new checks or send out event
 * notifications any more.
 * 
 * 
 * This class can be accessed from multiple threads concurrently. It shields the
 * associated {@link ReloadingDetector} object for concurrent access, so that a
 * concrete detector implementation does not have to be thread-safe.
 * 
 *
 * @version $Id: ReloadingController.java 1679751 2015-05-16 17:33:15Z oheger $
 * @since 2.0
 */
public class ReloadingController implements EventSource
{
    /** Stores a reference to the reloading detector. */
    private final ReloadingDetector detector;

    /** The helper object which manages the registered event listeners. */
    private final EventListenerList listeners;

    /** A flag whether this controller is in reloading state. */
    private boolean reloadingState;

    /**
     * Creates a new instance of {@code ReloadingController} and associates it
     * with the given {@code ReloadingDetector} object.
     *
     * @param detect the {@code ReloadingDetector} (must not be null)
     * @throws IllegalArgumentException if the detector is undefined
     */
    public ReloadingController(ReloadingDetector detect)
    {
        if (detect == null)
        {
            throw new IllegalArgumentException(
                    "ReloadingDetector must not be null!");
        }

        detector = detect;
        listeners = new EventListenerList();
    }

    /**
     * Returns the {@code ReloadingDetector} used by this controller.
     *
     * @return the {@code ReloadingDetector}
     */
    public ReloadingDetector getDetector()
    {
        return detector;
    }

    /**
     * {@inheritDoc} This class generates events of type {@code ReloadingEvent}.
     */
    @Override
    public  void addEventListener(
            EventType eventType, EventListener listener)
    {
        listeners.addEventListener(eventType, listener);
    }

    @Override
    public  boolean removeEventListener(
            EventType eventType, EventListener listener)
    {
        return listeners.removeEventListener(eventType, listener);
    }

    /**
     * Tests whether this controller is in reloading state. A return
     * value of true means that a previous invocation of
     * {@code checkForReloading()} has detected the necessity for a reload
     * operation, but {@code resetReloadingState()} has not been called yet. In
     * this state no further reloading checks are possible.
     *
     * @return a flag whether this controller is in reloading state
     */
    public synchronized boolean isInReloadingState()
    {
        return reloadingState;
    }

    /**
     * Performs a check whether a reload operation is necessary. This method has
     * to be called to trigger the generation of reloading events. It delegates
     * to the associated {@link ReloadingDetector} and sends out notifications
     * if necessary. The argument can be an arbitrary data object; it will be
     * part of the event notification sent out when a reload operation should be
     * performed. The return value indicates whether a change was detected and
     * an event was sent. Once a need for a reload is detected, this controller
     * is in reloading state. Until this state is reset (by calling
     * {@link #resetReloadingState()}), no further reloading checks are
     * performed by this method, and no events are fired; it then returns always
     * true.
     *
     * @param data additional data for an event notification
     * @return a flag whether a reload operation is necessary
     */
    public boolean checkForReloading(Object data)
    {
        boolean sendEvent = false;
        synchronized (this)
        {
            if (isInReloadingState())
            {
                return true;
            }
            if (getDetector().isReloadingRequired())
            {
                sendEvent = true;
                reloadingState = true;
            }
        }

        if (sendEvent)
        {
            listeners.fire(new ReloadingEvent(this, data));
            return true;
        }
        return false;
    }

    /**
     * Resets the reloading state. This tells the controller that reloading has
     * been performed and new checks are possible again. If this controller is
     * not in reloading state, this method has no effect.
     */
    public synchronized void resetReloadingState()
    {
        if (isInReloadingState())
        {
            getDetector().reloadingPerformed();
            reloadingState = false;
        }
    }
}