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 (for example 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 /** 52 * A specialized implementation of the {@code ReloadingDetector} interface which operates on a collection of 53 * {@code ReloadingController} objects. The methods defined by the {@code ReloadingDetector} interface are delegated to 54 * the managed controllers. 55 */ 56 private static final class MultiReloadingControllerDetector implements ReloadingDetector { 57 /** A reference to the owning combined reloading controller. */ 58 private final CombinedReloadingController owner; 59 60 /** 61 * Creates a new instance of {@code MultiReloadingControllerDetector}. 62 * 63 * @param owner the owner 64 */ 65 public MultiReloadingControllerDetector(final CombinedReloadingController owner) { 66 this.owner = owner; 67 } 68 69 /** 70 * {@inheritDoc} This implementation delegates to the managed controllers. For all of them the 71 * {@code checkForReloading()} method is called, giving them the chance to trigger a reload if necessary. If one of 72 * these calls returns <strong>true</strong>, the result of this method is <strong>true</strong>, otherwise <strong>false</strong>. 73 */ 74 @Override 75 public boolean isReloadingRequired() { 76 return owner.getSubControllers().stream().reduce(false, (b, rc) -> b | rc.checkForReloading(null), (t, u) -> t | u); 77 } 78 79 /** 80 * {@inheritDoc} This implementation resets the reloading state on all managed controllers. 81 */ 82 @Override 83 public void reloadingPerformed() { 84 owner.getSubControllers().forEach(ReloadingController::resetReloadingState); 85 } 86 } 87 88 /** Constant for a dummy reloading detector. */ 89 private static final ReloadingDetector DUMMY = new MultiReloadingControllerDetector(null); 90 91 /** 92 * Checks the collection with the passed in sub controllers and creates a defensive copy. 93 * 94 * @param subCtrls the collection with sub controllers 95 * @return a copy of the collection to be stored in the newly created instance 96 * @throws IllegalArgumentException if the passed in collection is <strong>null</strong> or contains <strong>null</strong> entries 97 */ 98 private static Collection<ReloadingController> checkManagedControllers(final Collection<? extends ReloadingController> subCtrls) { 99 if (subCtrls == null) { 100 throw new IllegalArgumentException("Collection with sub controllers must not be null!"); 101 } 102 final Collection<ReloadingController> ctrls = new ArrayList<>(subCtrls); 103 if (ctrls.stream().anyMatch(Objects::isNull)) { 104 throw new IllegalArgumentException("Collection with sub controllers contains a null entry!"); 105 } 106 107 return Collections.unmodifiableCollection(ctrls); 108 } 109 110 /** The collection with managed reloading controllers. */ 111 private final Collection<ReloadingController> controllers; 112 113 /** The reloading detector used by this instance. */ 114 private final ReloadingDetector detector; 115 116 /** 117 * Creates a new instance of {@code CombinedReloadingController} and initializes it with the {@code ReloadingController} 118 * objects to be managed. 119 * 120 * @param subCtrls the collection with sub {@code ReloadingController}s (must not be <strong>null</strong> or contain <strong>null</strong> 121 * entries) 122 * @throws IllegalArgumentException if the passed in collection is <strong>null</strong> or contains <strong>null</strong> entries 123 */ 124 public CombinedReloadingController(final Collection<? extends ReloadingController> subCtrls) { 125 super(DUMMY); 126 controllers = checkManagedControllers(subCtrls); 127 detector = new MultiReloadingControllerDetector(this); 128 } 129 130 /** 131 * {@inheritDoc} This implementation returns a special reloading detector which operates on all managed controllers. 132 */ 133 @Override 134 public ReloadingDetector getDetector() { 135 return detector; 136 } 137 138 /** 139 * Gets a (unmodifiable) collection with the sub controllers managed by this combined controller. 140 * 141 * @return a collection with sub controllers 142 */ 143 public Collection<ReloadingController> getSubControllers() { 144 return controllers; 145 } 146 147 /** 148 * Resets the reloading state of all managed sub controllers unconditionally. This method is intended to be called after 149 * the creation of an instance. It may be the case that some of the sub controllers are already in reloading state, so 150 * their state is out of sync with this controller's global reloading state. This method ensures that the reloading 151 * state of all sub controllers is reset. 152 */ 153 public void resetInitialReloadingState() { 154 getDetector().reloadingPerformed(); 155 } 156 }