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.builder.combined;
18
19 import java.util.Map;
20
21 import org.apache.commons.configuration2.ConfigurationUtils;
22 import org.apache.commons.configuration2.builder.BasicBuilderParameters;
23 import org.apache.commons.configuration2.builder.BuilderParameters;
24
25 /**
26 * <p>
27 * A specialized parameters object for {@link MultiFileConfigurationBuilder}.
28 * </p>
29 * <p>
30 * A parameters object of this type is used by a configuration builder with manages multiple file-based configurations.
31 * Such a builder is a bit special because it does not create a configuration on its own, but delegates to a file-based
32 * builder for this purpose. Therefore, parameters inherited from the super class are treated differently:
33 * </p>
34 * <ul>
35 * <li>The {@link org.apache.commons.configuration2.interpol.ConfigurationInterpolator ConfigurationInterpolator} is
36 * needed by a {@code MultiFileConfigurationBuilder} to resolve the file pattern. It is expected to be set and will not
37 * be passed to sub configurations created by the builder.</li>
38 * <li>All other parameters are evaluated when creating sub configurations. However, it is preferred to use the
39 * {@link #setManagedBuilderParameters(BuilderParameters)} method to define all properties of sub configurations in a
40 * single place. If such a parameters object is set, its properties take precedence.</li>
41 * </ul>
42 * <p>
43 * This class is not thread-safe. It is intended that an instance is constructed and initialized by a single thread
44 * during configuration of a {@code ConfigurationBuilder}.
45 * </p>
46 *
47 * @since 2.0
48 */
49 public class MultiFileBuilderParametersImpl extends BasicBuilderParameters implements MultiFileBuilderProperties<MultiFileBuilderParametersImpl> {
50 /** Constant for the key in the parameters map used by this class. */
51 private static final String PARAM_KEY = RESERVED_PARAMETER_PREFIX + MultiFileBuilderParametersImpl.class.getName();
52
53 /** The parameters object for managed builders. */
54 private BuilderParameters managedBuilderParameters;
55
56 /** The file pattern. */
57 private String filePattern;
58
59 /**
60 * Obtains an instance of this class from the given map with parameters. If this map does not contain an instance,
61 * result is <b>null</b>. This is equivalent to {@code fromParameters(params, false)}.
62 *
63 * @param params the map with parameters (must not be <b>null</b>)
64 * @return an instance of this class fetched from the map or <b>null</b>
65 * @throws NullPointerException if the map with parameters is <b>null</b>
66 */
67 public static MultiFileBuilderParametersImpl fromParameters(final Map<String, Object> params) {
68 return fromParameters(params, false);
69 }
70
71 /**
72 * Obtains an instance of this class from the given map with parameters and creates a new object if such an instance
73 * cannot be found. This method can be used to obtain an instance from a map which has been created using the
74 * {@code getParameters()} method. If the map does not contain an instance under the expected key and the
75 * {@code createIfMissing} parameter is <b>true</b>, a new instance is created. Otherwise, result is <b>null</b>.
76 *
77 * @param params the map with parameters (must not be <b>null</b>)
78 * @param createIfMissing a flag whether a new instance should be created if necessary
79 * @return an instance of this class fetched from the map or <b>null</b>
80 * @throws NullPointerException if the map with parameters is <b>null</b>
81 */
82 public static MultiFileBuilderParametersImpl fromParameters(final Map<String, Object> params, final boolean createIfMissing) {
83 MultiFileBuilderParametersImpl instance = (MultiFileBuilderParametersImpl) params.get(PARAM_KEY);
84 if (instance == null && createIfMissing) {
85 instance = new MultiFileBuilderParametersImpl();
86 }
87 return instance;
88 }
89
90 /**
91 * Gets the pattern for determining file names for managed configurations.
92 *
93 * @return the file pattern
94 */
95 public String getFilePattern() {
96 return filePattern;
97 }
98
99 @Override
100 public MultiFileBuilderParametersImpl setFilePattern(final String p) {
101 filePattern = p;
102 return this;
103 }
104
105 /**
106 * Gets the parameters object for managed configuration builders.
107 *
108 * @return the parameters for sub configurations
109 */
110 public BuilderParameters getManagedBuilderParameters() {
111 return managedBuilderParameters;
112 }
113
114 @Override
115 public MultiFileBuilderParametersImpl setManagedBuilderParameters(final BuilderParameters p) {
116 managedBuilderParameters = p;
117 return this;
118 }
119
120 /**
121 * {@inheritDoc} This implementation puts a reference to this object under a reserved key in the resulting parameters
122 * map.
123 */
124 @Override
125 public Map<String, Object> getParameters() {
126 final Map<String, Object> params = super.getParameters();
127 params.put(PARAM_KEY, this);
128 return params;
129 }
130
131 /**
132 * {@inheritDoc} This implementation also tries to clone the parameters object for managed builders if possible.
133 */
134 @Override
135 public MultiFileBuilderParametersImpl clone() {
136 final MultiFileBuilderParametersImpl copy = (MultiFileBuilderParametersImpl) super.clone();
137 copy.setManagedBuilderParameters((BuilderParameters) ConfigurationUtils.cloneIfPossible(getManagedBuilderParameters()));
138 return copy;
139 }
140 }