View Javadoc

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   * &lt;tools&gt;
43   *   &lt;toolbox scope="application"&gt;
44   *     &lt;tool class="org.apache.velocity.tools.generic.MathTool"/&gt;
45   *   &lt;/toolbox&gt;
46   * &lt;/tools&gt;
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 }