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 java.util.concurrent.Executors; 020import java.util.concurrent.ScheduledExecutorService; 021import java.util.concurrent.ScheduledFuture; 022import java.util.concurrent.ThreadFactory; 023import java.util.concurrent.TimeUnit; 024 025import org.apache.commons.lang3.concurrent.BasicThreadFactory; 026 027/** 028 * <p> 029 * A timer-based trigger for reloading checks. 030 * </p> 031 * <p> 032 * An instance of this class is constructed with a reference to a 033 * {@link ReloadingController} and a period. After calling the {@code start()} 034 * method a periodic task is started which calls 035 * {@link ReloadingController#checkForReloading(Object)} on the associated 036 * reloading controller. This way changes on a configuration source can be 037 * detected without client code having to poll actively. The 038 * {@code ReloadingController} will perform its checks and generates events if 039 * it detects the need for a reloading operation. 040 * </p> 041 * <p> 042 * Triggering of the controller can be disabled by calling the {@code stop()} 043 * method and later be resumed by calling {@code start()} again. When the 044 * trigger is no more needed its {@code shutdown()} method should be called. 045 * </p> 046 * <p> 047 * When creating an instance a {@code ScheduledExecutorService} can be provided 048 * which is then used by the object. Otherwise, a default executor service is 049 * created and used. When shutting down this object it can be specified whether 050 * the {@code ScheduledExecutorService} should be shut down, too. 051 * </p> 052 * 053 * @since 2.0 054 * @see ReloadingController 055 */ 056public class PeriodicReloadingTrigger 057{ 058 /** The executor service used by this trigger. */ 059 private final ScheduledExecutorService executorService; 060 061 /** The associated reloading controller. */ 062 private final ReloadingController controller; 063 064 /** The parameter to be passed to the controller. */ 065 private final Object controllerParam; 066 067 /** The period. */ 068 private final long period; 069 070 /** The time unit. */ 071 private final TimeUnit timeUnit; 072 073 /** Stores the future object for the current trigger task. */ 074 private ScheduledFuture<?> triggerTask; 075 076 /** 077 * Creates a new instance of {@code PeriodicReloadingTrigger} and sets all 078 * parameters. 079 * 080 * @param ctrl the {@code ReloadingController} (must not be <b>null</b>) 081 * @param ctrlParam the optional parameter to be passed to the controller 082 * when doing reloading checks 083 * @param triggerPeriod the period in which the controller is triggered 084 * @param unit the time unit for the period 085 * @param exec the executor service to use (can be <b>null</b>, then a 086 * default executor service is created 087 * @throws IllegalArgumentException if a required argument is missing 088 */ 089 public PeriodicReloadingTrigger(final ReloadingController ctrl, final Object ctrlParam, 090 final long triggerPeriod, final TimeUnit unit, final ScheduledExecutorService exec) 091 { 092 if (ctrl == null) 093 { 094 throw new IllegalArgumentException( 095 "ReloadingController must not be null!"); 096 } 097 098 controller = ctrl; 099 controllerParam = ctrlParam; 100 period = triggerPeriod; 101 timeUnit = unit; 102 executorService = 103 exec != null ? exec : createDefaultExecutorService(); 104 } 105 106 /** 107 * Creates a new instance of {@code PeriodicReloadingTrigger} with a default 108 * executor service. 109 * 110 * @param ctrl the {@code ReloadingController} (must not be <b>null</b>) 111 * @param ctrlParam the optional parameter to be passed to the controller 112 * when doing reloading checks 113 * @param triggerPeriod the period in which the controller is triggered 114 * @param unit the time unit for the period 115 * @throws IllegalArgumentException if a required argument is missing 116 */ 117 public PeriodicReloadingTrigger(final ReloadingController ctrl, final Object ctrlParam, 118 final long triggerPeriod, final TimeUnit unit) 119 { 120 this(ctrl, ctrlParam, triggerPeriod, unit, null); 121 } 122 123 /** 124 * Starts this trigger. The associated {@code ReloadingController} will be 125 * triggered according to the specified period. The first triggering happens 126 * after a period. If this trigger is already started, this invocation has 127 * no effect. 128 */ 129 public synchronized void start() 130 { 131 if (!isRunning()) 132 { 133 triggerTask = 134 getExecutorService().scheduleAtFixedRate( 135 createTriggerTaskCommand(), period, period, 136 timeUnit); 137 } 138 } 139 140 /** 141 * Stops this trigger. The associated {@code ReloadingController} is no more 142 * triggered. If this trigger is already stopped, this invocation has no 143 * effect. 144 */ 145 public synchronized void stop() 146 { 147 if (isRunning()) 148 { 149 triggerTask.cancel(false); 150 triggerTask = null; 151 } 152 } 153 154 /** 155 * Returns a flag whether this trigger is currently active. 156 * 157 * @return a flag whether this trigger is running 158 */ 159 public synchronized boolean isRunning() 160 { 161 return triggerTask != null; 162 } 163 164 /** 165 * Shuts down this trigger and optionally shuts down the 166 * {@code ScheduledExecutorService} used by this object. This method should 167 * be called if this trigger is no more needed. It ensures that the trigger 168 * is stopped. If the parameter is <b>true</b>, the executor service is also 169 * shut down. This should be done if this trigger is the only user of this 170 * executor service. 171 * 172 * @param shutdownExecutor a flag whether the associated 173 * {@code ScheduledExecutorService} is to be shut down 174 */ 175 public void shutdown(final boolean shutdownExecutor) 176 { 177 stop(); 178 if (shutdownExecutor) 179 { 180 getExecutorService().shutdown(); 181 } 182 } 183 184 /** 185 * Shuts down this trigger and its {@code ScheduledExecutorService}. This is 186 * a shortcut for {@code shutdown(true)}. 187 * 188 * @see #shutdown(boolean) 189 */ 190 public void shutdown() 191 { 192 shutdown(true); 193 } 194 195 /** 196 * Returns the {@code ScheduledExecutorService} used by this object. 197 * 198 * @return the associated {@code ScheduledExecutorService} 199 */ 200 ScheduledExecutorService getExecutorService() 201 { 202 return executorService; 203 } 204 205 /** 206 * Creates the task which triggers the reloading controller. 207 * 208 * @return the newly created trigger task 209 */ 210 private Runnable createTriggerTaskCommand() 211 { 212 return () -> controller.checkForReloading(controllerParam); 213 } 214 215 /** 216 * Creates a default executor service. This method is called if no executor 217 * has been passed to the constructor. 218 * 219 * @return the default executor service 220 */ 221 private static ScheduledExecutorService createDefaultExecutorService() 222 { 223 final ThreadFactory factory = 224 new BasicThreadFactory.Builder() 225 .namingPattern("ReloadingTrigger-%s").daemon(true) 226 .build(); 227 return Executors.newScheduledThreadPool(1, factory); 228 } 229}