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 * http://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 java.util.ArrayList; 20 import java.util.Collection; 21 import java.util.Collections; 22 import java.util.Objects; 23 24 /** 25 * <p> 26 * A specialized {@code ReloadingController} implementation which manages an arbitrary number of other 27 * {@code ReloadingController} objects. 28 * </p> 29 * <p> 30 * This class can be used to handle multiple simple controllers for reload operations as a single object. As a usage 31 * example consider a combined configuration containing a number of configuration sources of which some support 32 * reloading. In this scenario all {@code ReloadingController} instances for the reloading-enabled sources can be added 33 * to a {@code CombinedReloadingController}. Then by triggering the combined controller a reload check is performed on 34 * all child sources. 35 * </p> 36 * <p> 37 * This class is a typical implementation of the <em>composite pattern</em>. An instance is constructed with a 38 * collection of sub {@code ReloadingController} objects. Its operations are implemented by delegating to all child 39 * controllers. 40 * </p> 41 * <p> 42 * This class expects the managed controller objects to be passed to the constructor. From this list a defensive copy is 43 * created so that it cannot be changed later on. Derived classes can override the {@link #getSubControllers()} method 44 * if they need another way to handle child controllers (e.g. a more dynamic way). However, they are then responsible to 45 * ensure a safe access to this list in a multi-threaded environment. 46 * </p> 47 * 48 * @since 2.0 49 */ 50 public class CombinedReloadingController extends ReloadingController { 51 /** Constant for a dummy reloading detector. */ 52 private static final ReloadingDetector DUMMY = new MultiReloadingControllerDetector(null); 53 54 /** The collection with managed reloading controllers. */ 55 private final Collection<ReloadingController> controllers; 56 57 /** The reloading detector used by this instance. */ 58 private final ReloadingDetector detector; 59 60 /** 61 * Creates a new instance of {@code CombinedReloadingController} and initializes it with the {@code ReloadingController} 62 * objects to be managed. 63 * 64 * @param subCtrls the collection with sub {@code ReloadingController}s (must not be <b>null</b> or contain <b>null</b> 65 * entries) 66 * @throws IllegalArgumentException if the passed in collection is <b>null</b> or contains <b>null</b> entries 67 */ 68 public CombinedReloadingController(final Collection<? extends ReloadingController> subCtrls) { 69 super(DUMMY); 70 controllers = checkManagedControllers(subCtrls); 71 detector = new MultiReloadingControllerDetector(this); 72 } 73 74 /** 75 * Gets a (unmodifiable) collection with the sub controllers managed by this combined controller. 76 * 77 * @return a collection with sub controllers 78 */ 79 public Collection<ReloadingController> getSubControllers() { 80 return controllers; 81 } 82 83 /** 84 * {@inheritDoc} This implementation returns a special reloading detector which operates on all managed controllers. 85 */ 86 @Override 87 public ReloadingDetector getDetector() { 88 return detector; 89 } 90 91 /** 92 * Resets the reloading state of all managed sub controllers unconditionally. This method is intended to be called after 93 * the creation of an instance. It may be the case that some of the sub controllers are already in reloading state, so 94 * their state is out of sync with this controller's global reloading state. This method ensures that the reloading 95 * state of all sub controllers is reset. 96 */ 97 public void resetInitialReloadingState() { 98 getDetector().reloadingPerformed(); 99 } 100 101 /** 102 * Checks the collection with the passed in sub controllers and creates a defensive copy. 103 * 104 * @param subCtrls the collection with sub controllers 105 * @return a copy of the collection to be stored in the newly created instance 106 * @throws IllegalArgumentException if the passed in collection is <b>null</b> or contains <b>null</b> entries 107 */ 108 private static Collection<ReloadingController> checkManagedControllers(final Collection<? extends ReloadingController> subCtrls) { 109 if (subCtrls == null) { 110 throw new IllegalArgumentException("Collection with sub controllers must not be null!"); 111 } 112 final Collection<ReloadingController> ctrls = new ArrayList<>(subCtrls); 113 if (ctrls.stream().anyMatch(Objects::isNull)) { 114 throw new IllegalArgumentException("Collection with sub controllers contains a null entry!"); 115 } 116 117 return Collections.unmodifiableCollection(ctrls); 118 } 119 120 /** 121 * A specialized implementation of the {@code ReloadingDetector} interface which operates on a collection of 122 * {@code ReloadingController} objects. The methods defined by the {@code ReloadingDetector} interface are delegated to 123 * the managed controllers. 124 */ 125 private static final class MultiReloadingControllerDetector implements ReloadingDetector { 126 /** A reference to the owning combined reloading controller. */ 127 private final CombinedReloadingController owner; 128 129 /** 130 * Creates a new instance of {@code MultiReloadingControllerDetector}. 131 * 132 * @param owner the owner 133 */ 134 public MultiReloadingControllerDetector(final CombinedReloadingController owner) { 135 this.owner = owner; 136 } 137 138 /** 139 * {@inheritDoc} This implementation delegates to the managed controllers. For all of them the 140 * {@code checkForReloading()} method is called, giving them the chance to trigger a reload if necessary. If one of 141 * these calls returns <b>true</b>, the result of this method is <b>true</b>, otherwise <b>false</b>. 142 */ 143 @Override 144 public boolean isReloadingRequired() { 145 return owner.getSubControllers().stream().reduce(false, (b, rc) -> b | rc.checkForReloading(null), (t, u) -> t | u); 146 } 147 148 /** 149 * {@inheritDoc} This implementation resets the reloading state on all managed controllers. 150 */ 151 @Override 152 public void reloadingPerformed() { 153 owner.getSubControllers().forEach(ReloadingController::resetReloadingState); 154 } 155 } 156 }