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; 018 019import java.util.Collection; 020import java.util.Map; 021 022import org.apache.commons.configuration2.ConfigurationDecoder; 023import org.apache.commons.configuration2.io.ConfigurationLogger; 024import org.apache.commons.configuration2.beanutils.BeanHelper; 025import org.apache.commons.configuration2.convert.ConversionHandler; 026import org.apache.commons.configuration2.convert.ListDelimiterHandler; 027import org.apache.commons.configuration2.interpol.ConfigurationInterpolator; 028import org.apache.commons.configuration2.interpol.Lookup; 029import org.apache.commons.configuration2.sync.Synchronizer; 030 031/** 032 * <p> 033 * Definition of a properties interface for basic parameters which are supported 034 * by all {@link ConfigurationBuilder} implementations derived from 035 * {@link BasicConfigurationBuilder}. 036 * </p> 037 * <p> 038 * This interface defines the single properties supported by a parameters 039 * object. Properties can be set using a fluent API making it convenient for 040 * client code to specify concrete property values in a single statement. 041 * </p> 042 * <p> 043 * <strong>Important note:</strong> This interface is not intended to be 044 * implemented by client code! It defines a set of available properties and may 045 * be extended even in minor releases. 046 * </p> 047 * 048 * @version $Id: BasicBuilderProperties.java 1735895 2016-03-20 18:40:47Z oheger $ 049 * @since 2.0 050 * @param <T> the type of the result of all set methods for method chaining 051 */ 052public interface BasicBuilderProperties<T> 053{ 054 /** 055 * Sets the <em>logger</em> property. With this property a concrete 056 * {@code ConfigurationLogger} object can be set for the configuration. Thus 057 * logging behavior can be controlled. 058 * 059 * @param log the {@code Log} for the configuration produced by this builder 060 * @return a reference to this object for method chaining 061 */ 062 T setLogger(ConfigurationLogger log); 063 064 /** 065 * Sets the value of the <em>throwExceptionOnMissing</em> property. This 066 * property controls the configuration's behavior if missing properties are 067 * queried: a value of <b>true</b> causes the configuration to throw an 068 * exception, for a value of <b>false</b> it will return <b>null</b> values. 069 * (Note: Methods returning a primitive data type will always throw an 070 * exception if the property is not defined.) 071 * 072 * @param b the value of the property 073 * @return a reference to this object for method chaining 074 */ 075 T setThrowExceptionOnMissing(boolean b); 076 077 /** 078 * Sets the value of the <em>listDelimiterHandler</em> property. This 079 * property defines the object responsible for dealing with list delimiter 080 * and escaping characters. Note: 081 * {@link org.apache.commons.configuration2.AbstractConfiguration AbstractConfiguration} 082 * does not allow setting this property to <b>null</b>. If the default 083 * {@code ListDelimiterHandler} is to be used, do not call this method. 084 * 085 * @param handler the {@code ListDelimiterHandler} 086 * @return a reference to this object for method chaining 087 */ 088 T setListDelimiterHandler(ListDelimiterHandler handler); 089 090 /** 091 * Sets the {@code ConfigurationInterpolator} to be used for this 092 * configuration. Using this method a custom 093 * {@code ConfigurationInterpolator} can be set which can be freely 094 * configured. Alternatively, it is possible to add custom {@code Lookup} 095 * objects using other methods provided by this interface. 096 * 097 * @param ci the {@code ConfigurationInterpolator} for this configuration 098 * @return a reference to this object for method chaining 099 */ 100 T setInterpolator(ConfigurationInterpolator ci); 101 102 /** 103 * Sets additional {@code Lookup} objects for specific prefixes for this 104 * configuration object. All {@code Lookup} objects contained in the given 105 * map are added to the configuration's {@code ConfigurationInterpolator}. 106 * Note: This method only takes effect if no 107 * {@code ConfigurationInterpolator} is set using the 108 * {@link #setInterpolator(ConfigurationInterpolator)} method. 109 * 110 * @param lookups a map with {@code Lookup} objects and their associated 111 * prefixes 112 * @return a reference to this object for method chaining 113 * @see ConfigurationInterpolator#registerLookups(Map) 114 */ 115 T setPrefixLookups(Map<String, ? extends Lookup> lookups); 116 117 /** 118 * Adds additional default {@code Lookup} objects (i.e. lookups which are 119 * not associated with a specific prefix) to this configuration object. 120 * Note: This method only takes effect if no 121 * {@code ConfigurationInterpolator} is set using the 122 * {@link #setInterpolator(ConfigurationInterpolator)} method. 123 * 124 * @param lookups a collection with {@code Lookup} objects to be added as 125 * default lookups at the configuration's 126 * {@code ConfigurationInterpolator} 127 * @return a reference to this object for method chaining 128 * @see ConfigurationInterpolator#addDefaultLookups(Collection) 129 */ 130 T setDefaultLookups(Collection<? extends Lookup> lookups); 131 132 /** 133 * Sets the parent {@code ConfigurationInterpolator} for this 134 * configuration's {@code ConfigurationInterpolator}. Setting a parent 135 * {@code ConfigurationInterpolator} can be used for defining a default 136 * behavior for variables which cannot be resolved. 137 * 138 * @param parent the new parent {@code ConfigurationInterpolator} 139 * @return a reference to this object for method chaining 140 * @see ConfigurationInterpolator#setParentInterpolator(ConfigurationInterpolator) 141 */ 142 T setParentInterpolator(ConfigurationInterpolator parent); 143 144 /** 145 * Sets the {@code Synchronizer} object for this configuration. This object 146 * is used to protect this configuration instance against concurrent access. 147 * The concrete {@code Synchronizer} implementation used determines whether 148 * a configuration instance is thread-safe or not. 149 * 150 * @param sync the {@code Synchronizer} to be used (a value of <b>null</b> 151 * means that a default {@code Synchronizer} is used) 152 * @return a reference to this object for method chaining 153 */ 154 T setSynchronizer(Synchronizer sync); 155 156 /** 157 * Sets the {@code ConversionHandler} object for this configuration. This 158 * object is responsible for all data type conversions required for 159 * accessing configuration properties in a specific target type. If this 160 * property is not set, a default {@code ConversionHandler} is used. 161 * 162 * @param handler the {@code ConversionHandler} to be used 163 * @return a reference to this object for method chaining 164 */ 165 T setConversionHandler(ConversionHandler handler); 166 167 /** 168 * Sets the {@code ConfigurationDecoder} object for this configuration. This 169 * object is called when encoded properties are queried using the 170 * {@code getEncodedString()} method. 171 * 172 * @param decoder the {@code ConfigurationDecoder} to be used 173 * @return a reference to this object for method chaining 174 */ 175 T setConfigurationDecoder(ConfigurationDecoder decoder); 176 177 /** 178 * Sets a {@code BeanHelper} object to be used by the configuration builder. 179 * The {@code BeanHelper} is used to create the managed configuration 180 * instance dynamically. It is not a property of the configuration as most 181 * other properties defined by this interface. By setting an alternative 182 * {@code BeanHelper} the process of creating configuration instances via 183 * reflection can be adapted. (Some specialized configuration builder 184 * implementations also use a {@code BeanHelper} to create complex helper 185 * objects during construction of their result object. 186 * {@code CombinedConfigurationBuilder} for instance supports a complex 187 * configuration definition format which may contain several specialized 188 * bean declarations.) If no specific {@code BeanHelper} is set, the builder 189 * uses the default instance. 190 * 191 * @param beanHelper the {@code BeanHelper} to be used by the builder 192 * @return a reference to this object for method chaining 193 */ 194 T setBeanHelper(BeanHelper beanHelper); 195}