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 */ 017 package org.apache.commons.beanutils.converters; 018 019 import org.apache.commons.beanutils.ConversionException; 020 021 /** 022 * {@link org.apache.commons.beanutils.Converter} implementaion that handles conversion 023 * to and from <b>Boolean</b> objects. 024 * {@link org.apache.commons.beanutils.Converter} implementaion that 025 * handles conversion to and from <b>java.lang.Boolean</b> objects. 026 * <p> 027 * Can be configured to either return a <i>default value</i> or throw a 028 * <code>ConversionException</code> if a conversion error occurs. 029 * <p> 030 * By default any object whose string representation is one of the values 031 * {"yes", "y", "true", "on", "1"} is converted to Boolean.TRUE, and 032 * string representations {"no", "n", "false", "off", "0"} are converted 033 * to Boolean.FALSE. The recognised true/false strings can be changed by: 034 * <pre> 035 * String[] trueStrings = {"oui", "o", "1"}; 036 * String[] falseStrings = {"non", "n", "0"}; 037 * Converter bc = new BooleanConverter(trueStrings, falseStrings); 038 * ConvertUtils.register(bc, Boolean.class); 039 * ConvertUtils.register(bc, Boolean.TYPE); 040 * </pre> 041 * In addition, it is recommended that the BooleanArrayConverter also be 042 * modified to recognise the same set of values: 043 * <pre> 044 * Converter bac = new BooleanArrayConverter(bc, BooleanArrayConverter.NO_DEFAULT); 045 * ConvertUtils.register(bac, bac.MODEL); 046 * </pre> 047 * </p> 048 * 049 * <p>Case is ignored when converting values to true or false.</p> 050 * 051 * @author Craig R. McClanahan 052 * @version $Revision: 640131 $ $Date: 2008-03-23 02:10:31 +0000 (Sun, 23 Mar 2008) $ 053 * @since 1.3 054 */ 055 public final class BooleanConverter extends AbstractConverter { 056 057 058 // ----------------------------------------------------------- Constructors 059 060 061 /** 062 * Create a {@link org.apache.commons.beanutils.Converter} that will throw a {@link ConversionException} 063 * if a conversion error occurs, ie the string value being converted is 064 * not one of the known true strings, nor one of the known false strings. 065 */ 066 public BooleanConverter() { 067 super(); 068 } 069 070 071 /** 072 * Create a {@link org.apache.commons.beanutils.Converter} that will return the specified default value 073 * if a conversion error occurs, ie the string value being converted is 074 * not one of the known true strings, nor one of the known false strings. 075 * 076 * @param defaultValue The default value to be returned if the value 077 * being converted is not recognised. This value may be null, in which 078 * case null will be returned on conversion failure. When non-null, it is 079 * expected that this value will be either Boolean.TRUE or Boolean.FALSE. 080 * The special value BooleanConverter.NO_DEFAULT can also be passed here, 081 * in which case this constructor acts like the no-argument one. 082 */ 083 public BooleanConverter(Object defaultValue) { 084 super(); 085 if (defaultValue != NO_DEFAULT) { 086 setDefaultValue(defaultValue); 087 } 088 } 089 090 /** 091 * Create a {@link org.apache.commons.beanutils.Converter} that will throw a {@link ConversionException} 092 * if a conversion error occurs, ie the string value being converted is 093 * not one of the known true strings, nor one of the known false strings. 094 * <p> 095 * The provided string arrays are copied, so that changes to the elements 096 * of the array after this call is made do not affect this object. 097 * 098 * @param trueStrings is the set of strings which should convert to the 099 * value Boolean.TRUE. The value null must not be present. Case is 100 * ignored. 101 * 102 * @param falseStrings is the set of strings which should convert to the 103 * value Boolean.TRUE. The value null must not be present. Case is 104 * ignored. 105 */ 106 public BooleanConverter(String[] trueStrings, String[] falseStrings) { 107 super(); 108 this.trueStrings = copyStrings(trueStrings); 109 this.falseStrings = copyStrings(falseStrings); 110 } 111 112 /** 113 * Create a {@link org.apache.commons.beanutils.Converter} that will return 114 * the specified default value if a conversion error occurs. 115 * <p> 116 * The provided string arrays are copied, so that changes to the elements 117 * of the array after this call is made do not affect this object. 118 * 119 * @param trueStrings is the set of strings which should convert to the 120 * value Boolean.TRUE. The value null must not be present. Case is 121 * ignored. 122 * 123 * @param falseStrings is the set of strings which should convert to the 124 * value Boolean.TRUE. The value null must not be present. Case is 125 * ignored. 126 * 127 * @param defaultValue The default value to be returned if the value 128 * being converted is not recognised. This value may be null, in which 129 * case null will be returned on conversion failure. When non-null, it is 130 * expected that this value will be either Boolean.TRUE or Boolean.FALSE. 131 * The special value BooleanConverter.NO_DEFAULT can also be passed here, 132 * in which case an exception will be thrown on conversion failure. 133 */ 134 public BooleanConverter(String[] trueStrings, String[] falseStrings, 135 Object defaultValue) { 136 super(); 137 this.trueStrings = copyStrings(trueStrings); 138 this.falseStrings = copyStrings(falseStrings); 139 if (defaultValue != NO_DEFAULT) { 140 setDefaultValue(defaultValue); 141 } 142 } 143 144 145 // ----------------------------------------------------- Static Variables 146 147 148 /** 149 * This is a special reference that can be passed as the "default object" 150 * to the constructor to indicate that no default is desired. Note that 151 * the value 'null' cannot be used for this purpose, as the caller may 152 * want a null to be returned as the default. 153 * @deprecated Use constructors without default value. 154 */ 155 public static final Object NO_DEFAULT = new Object(); 156 157 158 // ----------------------------------------------------- Instance Variables 159 160 /** 161 * The set of strings that are known to map to Boolean.TRUE. 162 */ 163 private String[] trueStrings = {"true", "yes", "y", "on", "1"}; 164 165 /** 166 * The set of strings that are known to map to Boolean.FALSE. 167 */ 168 private String[] falseStrings = {"false", "no", "n", "off", "0"}; 169 170 // --------------------------------------------------------- Protected Methods 171 172 /** 173 * Return the default type this <code>Converter</code> handles. 174 * 175 * @return The default type this <code>Converter</code> handles. 176 */ 177 protected Class getDefaultType() { 178 return Boolean.class; 179 } 180 181 /** 182 * Convert the specified input object into an output object of the 183 * specified type. 184 * 185 * @param type is the type to which this value should be converted. In the 186 * case of this BooleanConverter class, this value is ignored. 187 * 188 * @param value is the input value to be converted. The toString method 189 * shall be invoked on this object, and the result compared (ignoring 190 * case) against the known "true" and "false" string values. 191 * 192 * @return Boolean.TRUE if the value was a recognised "true" value, 193 * Boolean.FALSE if the value was a recognised "false" value, or 194 * the default value if the value was not recognised and the constructor 195 * was provided with a default value. 196 * 197 * @throws Throwable if an error occurs converting to the specified type 198 */ 199 protected Object convertToType(Class type, Object value) throws Throwable { 200 201 // All the values in the trueStrings and falseStrings arrays are 202 // guaranteed to be lower-case. By converting the input value 203 // to lowercase too, we can use the efficient String.equals method 204 // instead of the less-efficient String.equalsIgnoreCase method. 205 String stringValue = value.toString().toLowerCase(); 206 207 for(int i=0; i<trueStrings.length; ++i) { 208 if (trueStrings[i].equals(stringValue)) { 209 return Boolean.TRUE; 210 } 211 } 212 213 for(int i=0; i<falseStrings.length; ++i) { 214 if (falseStrings[i].equals(stringValue)) { 215 return Boolean.FALSE; 216 } 217 } 218 219 throw new ConversionException("Cna't convert value '" + value + "' to a Boolean"); 220 } 221 222 /** 223 * This method creates a copy of the provided array, and ensures that 224 * all the strings in the newly created array contain only lower-case 225 * letters. 226 * <p> 227 * Using this method to copy string arrays means that changes to the 228 * src array do not modify the dst array. 229 */ 230 private static String[] copyStrings(String[] src) { 231 String[] dst = new String[src.length]; 232 for(int i=0; i<src.length; ++i) { 233 dst[i] = src[i].toLowerCase(); 234 } 235 return dst; 236 } 237 }