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.builder.combined; 018 019import org.apache.commons.configuration2.HierarchicalConfiguration; 020import org.apache.commons.configuration2.builder.BuilderParameters; 021import org.apache.commons.configuration2.builder.ConfigurationBuilder; 022import org.apache.commons.configuration2.builder.DefaultParametersHandler; 023import org.apache.commons.configuration2.builder.DefaultParametersManager; 024 025/** 026 * <p> 027 * Definition of a properties interface for the parameters of a combined 028 * configuration builder. 029 * </p> 030 * <p> 031 * This interface defines a number of properties for adapting the construction 032 * of a combined configuration based on a definition configuration. Properties 033 * can be set in a fluent style. 034 * </p> 035 * <p> 036 * <strong>Important note:</strong> This interface is not intended to be 037 * implemented by client code! It defines a set of available properties and may 038 * be extended even in minor releases. 039 * </p> 040 * 041 * @since 2.0 042 * @param <T> the return type of all methods for allowing method chaining 043 */ 044public interface CombinedBuilderProperties<T> 045{ 046 /** 047 * Sets a flag whether the child configurations created by a 048 * {@code CombinedConfigurationBuilder} should inherit the settings defined 049 * for the builder. This is typically useful because for configurations 050 * coming from homogeneous sources often similar conventions are used. 051 * Therefore, this flag is <b>true</b> per default. 052 * 053 * @param f the flag whether settings should be inherited by child 054 * configurations 055 * @return a reference to this object for method chaining 056 */ 057 T setInheritSettings(boolean f); 058 059 /** 060 * Sets the {@code ConfigurationBuilder} for the definition configuration. 061 * This is the configuration which contains the configuration sources that 062 * form the combined configuration. 063 * 064 * @param builder the definition {@code ConfigurationBuilder} 065 * @return a reference to this object for method chaining 066 */ 067 T setDefinitionBuilder( 068 ConfigurationBuilder<? extends HierarchicalConfiguration<?>> builder); 069 070 /** 071 * Registers the given {@code ConfigurationBuilderProvider} for the 072 * specified tag name. This means that whenever this tag is encountered in a 073 * configuration definition file, the corresponding builder provider is 074 * invoked. 075 * 076 * @param tagName the name of the tag (must not be <b>null</b>) 077 * @param provider the {@code ConfigurationBuilderProvider} (must not be 078 * <b>null</b>) 079 * @return a reference to this object for method chaining 080 * @throws IllegalArgumentException if a required parameter is missing 081 */ 082 T registerProvider(String tagName, ConfigurationBuilderProvider provider); 083 084 /** 085 * Sets the base path for this combined configuration builder. Normally it 086 * it not necessary to set the base path explicitly. Per default, relative 087 * file names of configuration sources are resolved based on the location of 088 * the definition file. If this is not desired or if the definition 089 * configuration is loaded by a different means, the base path for relative 090 * file names can be specified using this method. 091 * 092 * @param path the base path for resolving relative file names 093 * @return a reference to this object for method chaining 094 */ 095 T setBasePath(String path); 096 097 /** 098 * Sets the parameters object for the definition configuration builder. This 099 * property is evaluated only if the definition configuration builder is not 100 * set explicitly (using the 101 * {@link #setDefinitionBuilder(ConfigurationBuilder)} method). In this 102 * case, a builder for an XML configuration is created and configured with 103 * this parameters object. 104 * 105 * @param params the parameters object for the definition configuration 106 * builder 107 * @return a reference to this object for method chaining 108 */ 109 T setDefinitionBuilderParameters(BuilderParameters params); 110 111 /** 112 * Sets a {@code DefaultParametersManager} object responsible for managing the default 113 * parameter handlers to be applied on child configuration sources. When creating 114 * builders for child configuration sources their parameters are initialized using 115 * this {@code DefaultParametersManager} instance. This way, meaningful defaults can 116 * be set. Note that calling this method overrides all 117 * {@code DefaultParametersHandler} objects previously set by one of the 118 * {@code registerChildDefaultsHandler()} methods! So either use this method if a 119 * pre-configured manager object is to be set or call the 120 * {@code registerChildDefaultHandler()} methods with the handlers to be registered 121 * (in the latter case, it is not necessary to set a {@code DefaultParametersManager} 122 * explicitly; a default one is created behind the scenes). 123 * 124 * @param manager the {@code DefaultParametersManager} 125 * @return a reference to this object for method chaining 126 */ 127 T setChildDefaultParametersManager(DefaultParametersManager manager); 128 129 /** 130 * Registers a {@code DefaultParametersHandler} for child configuration sources. With 131 * this method an arbitrary number of handler objects can be set. When creating 132 * builders for child configuration sources their parameters are initialized by 133 * invoking all matching {@code DefaultParametersHandler}s on them. So, basically the 134 * same mechanism is used for the initialization of parameters for child configuration 135 * sources as for normal parameter objects. 136 * 137 * @param <D> the type of the handler to be registered 138 * @param paramClass the parameter class supported by the handler 139 * @param handler the {@code DefaultParametersHandler} to be registered 140 * @return a reference to this object for method chaining 141 * @see DefaultParametersManager#registerDefaultsHandler(Class, 142 * DefaultParametersHandler) 143 */ 144 <D> T registerChildDefaultsHandler(Class<D> paramClass, 145 DefaultParametersHandler<? super D> handler); 146 147 /** 148 * Registers a {@code DefaultParametersHandler} for child configuration sources 149 * derived from the given start class. This method works like the overloaded variant, 150 * but limits the application of the defaults handler to specific child configuration 151 * sources. 152 * 153 * @param <D> the type of the handler to be registered 154 * @param paramClass the parameter class supported by the handler 155 * @param handler the {@code DefaultParametersHandler} to be registered 156 * @param startClass an optional start class in the hierarchy of parameter objects for 157 * which this handler should be applied 158 * @return a reference to this object for method chaining 159 * @see DefaultParametersManager#registerDefaultsHandler(Class, 160 * DefaultParametersHandler, Class) 161 */ 162 <D> T registerChildDefaultsHandler(Class<D> paramClass, 163 DefaultParametersHandler<? super D> handler, Class<?> startClass); 164}