View Javadoc
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 }