1 package org.apache.velocity.tools.generic; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import java.text.NumberFormat; 23 import java.util.Locale; 24 import org.apache.velocity.tools.ConversionUtils; 25 import org.apache.velocity.tools.ToolContext; 26 import org.apache.velocity.tools.config.DefaultKey; 27 28 /** 29 * Tool for working with {@link Number} in Velocity templates. 30 * It is useful for accessing and 31 * formatting arbitrary {@link Number} objects. Also 32 * the tool can be used to retrieve {@link NumberFormat} instances 33 * or make conversions to and from various number types. 34 * <p><pre> 35 * Example uses: 36 * $myNumber -> 13.55 37 * $number.format($myNumber) -> 13.6 38 * $number.currency($myNumber) -> $13.55 39 * $number.integer($myNumber) -> 13 40 * 41 * Example tools.xml config (if you want to use this with VelocityView): 42 * <tools> 43 * <toolbox scope="application"> 44 * <tool class="org.apache.velocity.tools.generic.MathTool"/> 45 * </toolbox> 46 * </tools> 47 * </pre></p> 48 * 49 * <p>This tool is entirely threadsafe, and has no instance members. 50 * It may be used in any scope (request, session, or application). 51 * As such, the methods are highly interconnected, and overriding 52 * key methods provides an easy way to create subclasses that use 53 * a non-default format or locale.</p> 54 * 55 * @author Nathan Bubna 56 * @author <a href="mailto:mkienenb@alaska.net">Mike Kienenberger</a> 57 * @since VelocityTools 1.2 58 * @version $Id: NumberTool.java 671008 2008-06-24 03:37:33Z nbubna $ 59 */ 60 @DefaultKey("number") 61 public class NumberTool extends FormatConfig 62 { 63 @Deprecated 64 public static final String DEFAULT_FORMAT_KEY = FORMAT_KEY; 65 66 @Deprecated 67 public static final String DEFAULT_LOCALE_KEY = ToolContext.LOCALE_KEY; 68 69 70 // ------------------------- formatting methods --------------------------- 71 72 /** 73 * Converts the specified object to a number and formats it according to 74 * the pattern or style returned by {@link #getFormat()}. 75 * 76 * @param obj the number object to be formatted 77 * @return the specified number formatted as a string 78 * @see #format(String format, Object obj, Locale locale) 79 */ 80 public String format(Object obj) 81 { 82 return format(getFormat(), obj); 83 } 84 85 /** 86 * Convenience method equivalent to $number.format("currency", $foo). 87 * @since VelocityTools 1.3 88 */ 89 public String currency(Object obj) 90 { 91 return format("currency", obj); 92 } 93 94 /** 95 * Convenience method equivalent to $number.format("integer", $foo). 96 * @since VelocityTools 1.3 97 */ 98 public String integer(Object obj) 99 { 100 return format("integer", obj); 101 } 102 103 /** 104 * Convenience method equivalent to $number.format("number", $foo). 105 * @since VelocityTools 1.3 106 */ 107 public String number(Object obj) 108 { 109 return format("number", obj); 110 } 111 112 /** 113 * Convenience method equivalent to $number.format("percent", $foo). 114 * @since VelocityTools 1.3 115 */ 116 public String percent(Object obj) 117 { 118 return format("percent", obj); 119 } 120 121 /** 122 * Converts the specified object to a number and returns 123 * a formatted string representing that number in the locale 124 * returned by {@link #getLocale()}. 125 * 126 * @param format the formatting instructions 127 * @param obj the number object to be formatted 128 * @return a formatted string for this locale representing the specified 129 * number or <code>null</code> if the parameters are invalid 130 * @see #format(String format, Object obj, Locale locale) 131 */ 132 public String format(String format, Object obj) 133 { 134 return format(format, obj, getLocale()); 135 } 136 137 /** 138 * Converts the specified object to a number and returns 139 * a formatted string representing that number in the specified 140 * {@link Locale}. 141 * 142 * @param format the custom or standard pattern to be used 143 * @param obj the number object to be formatted 144 * @param locale the {@link Locale} to be used when formatting 145 * @return a formatted string representing the specified number or 146 * <code>null</code> if the parameters are invalid 147 */ 148 public String format(String format, Object obj, Locale locale) 149 { 150 Number number = toNumber(obj); 151 NumberFormat nf = getNumberFormat(format, locale); 152 if (number == null || nf == null) 153 { 154 return null; 155 } 156 return nf.format(number); 157 } 158 159 // -------------------------- NumberFormat creation methods -------------- 160 161 /** 162 * Returns a {@link NumberFormat} instance for the specified 163 * format and {@link Locale}. If the format specified is a standard 164 * style pattern, then a number instance 165 * will be returned with the number style set to the 166 * specified style. If it is a custom format, then a customized 167 * {@link NumberFormat} will be returned. 168 * 169 * @param format the custom or standard formatting pattern to be used 170 * @param locale the {@link Locale} to be used 171 * @return an instance of {@link NumberFormat} 172 * @see NumberFormat 173 */ 174 public NumberFormat getNumberFormat(String format, Locale locale) 175 { 176 return ConversionUtils.getNumberFormat(format, locale); 177 } 178 179 /** 180 * Returns a {@link NumberFormat} instance for the specified 181 * number style and {@link Locale}. 182 * 183 * @param numberStyle the number style (number will be ignored if this is 184 * less than zero or the number style is not recognized) 185 * @param locale the {@link Locale} to be used 186 * @return an instance of {@link NumberFormat} or <code>null</code> 187 * if an instance cannot be constructed with the given 188 * parameters 189 */ 190 @Deprecated 191 protected NumberFormat getNumberFormat(int numberStyle, Locale locale) 192 { 193 return ConversionUtils.getNumberFormat(numberStyle, locale); 194 } 195 196 /** 197 * Checks a string to see if it matches one of the standard 198 * NumberFormat style patterns: 199 * NUMBER, CURRENCY, PERCENT, INTEGER, or DEFAULT. 200 * if it does it will return the integer constant for that pattern. 201 * if not, it will return -1. 202 * 203 * @see NumberFormat 204 * @param style the string to be checked 205 * @return the int identifying the style pattern 206 */ 207 @Deprecated 208 protected int getStyleAsInt(String style) 209 { 210 return ConversionUtils.getNumberStyleAsInt(style); 211 } 212 213 214 // ------------------------- number conversion methods --------------- 215 216 /** 217 * Converts an object to an instance of {@link Number} using the 218 * format returned by {@link #getFormat()} and the {@link Locale} 219 * returned by {@link #getLocale()} if the object is not already 220 * an instance of Number. 221 * 222 * @param obj the number to convert 223 * @return the object as a {@link Number} or <code>null</code> if no 224 * conversion is possible 225 */ 226 public Number toNumber(Object obj) 227 { 228 return toNumber(getFormat(), obj, getLocale()); 229 } 230 231 /** 232 * Converts an object to an instance of {@link Number} using the 233 * specified format and the {@link Locale} returned by 234 * {@link #getLocale()} if the object is not already an instance 235 * of Number. 236 * 237 * @param format - the format the number is in 238 * @param obj - the number to convert 239 * @return the object as a {@link Number} or <code>null</code> if no 240 * conversion is possible 241 * @see #toNumber(String format, Object obj, Locale locale) 242 */ 243 public Number toNumber(String format, Object obj) 244 { 245 return toNumber(format, obj, getLocale()); 246 } 247 248 /** 249 * Converts an object to an instance of {@link Number} using the 250 * specified format and {@link Locale}if the object is not already 251 * an instance of Number. 252 * 253 * @param format - the format the number is in 254 * @param obj - the number to convert 255 * @param locale - the {@link Locale} 256 * @return the object as a {@link Number} or <code>null</code> if no 257 * conversion is possible 258 * @see NumberFormat#parse 259 */ 260 public Number toNumber(String format, Object obj, Locale locale) 261 { 262 return ConversionUtils.toNumber(obj, format, locale); 263 } 264 265 }