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