ListTool


1   /*
2    * Copyright 2003-2005 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.velocity.tools.generic;
18  
19  import java.lang.reflect.Array  ;
20  import java.util.List  ;
21  
22  /**
23   * Tool for working with Lists and arrays in Velocity templates.
24   * It provides a method to get and set specified elements.
25   * Also provides methods to perform the following actions to Lists and arrays:
26   * <ul>
27   * <li>Check if it is empty.</li>
28   * <li>Check if it contains a certain element.</li>
29   * </ul>
30   * <p/>
31   * <p><pre>
32   * Example uses:
33   *  $primes                    -> new int[] {2, 3, 5, 7}
34   *  $list.size($primes)        -> 4
35   *  $list.get($primes, 2)      -> 5
36   *  $list.set($primes, 2, 1)   -> (primes[2] becomes 1)
37   *  $list.get($primes, 2)      -> 1
38   *  $list.isEmpty($primes)     -> false
39   *  $list.contains($primes, 7) -> true
40   * <p/>
41   * Example toolbox.xml config (if you want to use this with VelocityView):
42   * &lt;tool&gt;
43   *   &lt;key&gt;list&lt;/key&gt;
44   *   &lt;scope&gt;application&lt;/scope&gt;
45   *   &lt;class&gt;org.apache.velocity.tools.generic.ListTool&lt;/class&gt;
46   * &lt;/tool&gt;
47   * </pre></p>
48   * <p/>
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   * </p>
52   *
53   * @author <a HREF="mailto:shinobu@ieee.org">Shinobu Kawai</a>
54   * @version $Id: ListTool.java,v 1.1 2006/03/23 06:36:11 czarneckid Exp $
55   */
56  public class ListTool {
57  
58      /**
59       * Default constructor.
60       */
61      public ListTool() {
62      }
63  
64      /**
65       * Gets the specified element of a List/array.
66       * It will return null under the following conditions:
67       * <ul>
68       * <li><code>list</code> is null.</li>
69       * <li><code>list</code> is not a List/array.</li>
70       * <li><code>list</code> doesn't have an <code>index</code>th value.</li>
71       * </ul>
72       *
73       * @param list  the List/array object.
74       * @param index the index of the List/array to get.
75       * @return the specified element of the List/array.
76       */
77      public Object   get(Object   list, int index) {
78          if (this.isArray(list)) {
79              return this.getFromArray(list, index);
80          }
81          if (!this.isList(list)) {
82              return null;
83          }
84  
85          try {
86              return ((List  ) list).get(index);
87          }
88          catch (IndexOutOfBoundsException   e) {
89              // The index was wrong.
90              return null;
91          }
92      }
93  
94      /**
95       * Gets the specified element of an array.
96       *
97       * @param array the array object.
98       * @param index the index of the array to get.
99       * @return the specified element of the array.
100      */
101     private Object   getFromArray(Object   array, int index) {
102         try {
103             return Array.get(array, index);
104         }
105         catch (IndexOutOfBoundsException   e) {
106             // The index was wrong.
107             return null;
108         }
109     }
110 
111     /**
112      * Sets the specified element of a List/array.
113      * It will return null under the following conditions:
114      * <ul>
115      * <li><code>list</code> is null.</li>
116      * <li><code>list</code> is not a List/array.</li>
117      * <li><code>list</code> doesn't have an <code>index</code>th value.</li>
118      * </ul>
119      *
120      * @param list  the List/array object.
121      * @param index the index of the List/array to set.
122      * @param value the element to set.
123      * @return blank if set, null if not set.
124      */
125     public Object   set(Object   list, int index, Object   value) {
126         if (this.isArray(list)) {
127             return this.setToArray(list, index, value);
128         }
129         if (!this.isList(list)) {
130             return null;
131         }
132 
133         try {
134             ((List  ) list).set(index, value);
135             return "";
136         }
137         catch (IndexOutOfBoundsException   e) {
138             // The index was wrong.
139             return null;
140         }
141     }
142 
143     /**
144      * Sets the specified element of an array.
145      *
146      * @param array the array object.
147      * @param index the index of the array to set.
148      * @param value the element to set.
149      * @return blank if set, null if not set.
150      */
151     private Object   setToArray(Object   array, int index, Object   value) {
152         try {
153             Array.set(array, index, value);
154             return "";
155         }
156         catch (IndexOutOfBoundsException   e) {
157             // The index was wrong.
158             return null;
159         }
160     }
161 
162     /**
163      * Gets the size of a List/array.
164      * It will return null under the following conditions:
165      * <ul>
166      * <li><code>list</code> is null.</li>
167      * <li><code>list</code> is not a List/array.</li>
168      * </ul>
169      * The result will be same as the {@link #length(Object)} method.
170      *
171      * @param list the List object.
172      * @return the size of the List.
173      * @see #length(Object)
174      */
175     public Integer   size(Object   list) {
176         if (this.isArray(list)) {
177             // Thanks to Eric Fixler for this refactor.
178             return new Integer  (Array.getLength(list));
179         }
180         if (!this.isList(list)) {
181             return null;
182         }
183 
184         return new Integer  (((List  ) list).size());
185     }
186 
187     /**
188      * Checks if an object is an array.
189      *
190      * @param object the object to check.
191      * @return <code>true</code> if the object is an array.
192      */
193     public boolean isArray(Object   object) {
194         if (object == null) {
195             return false;
196         }
197         return object.getClass().isArray();
198     }
199 
200     /**
201      * Checks if an object is a List.
202      *
203      * @param object the object to check.
204      * @return <code>true</code> if the object is a List.
205      */
206     public boolean isList(Object   object) {
207         return object instanceof List  ;
208     }
209 
210     /**
211      * Checks if a List/array is empty.
212      *
213      * @param list the List/array to check.
214      * @return <code>true</code> if the List/array is empty.
215      */
216     public Boolean   isEmpty(Object   list) {
217         Integer   size = this.size(list);
218         if (size == null) {
219             return null;
220         }
221 
222         return new Boolean  (size.intValue() == 0);
223     }
224 
225     /**
226      * Checks if a List/array contains a certain element.
227      *
228      * @param list    the List/array to check.
229      * @param element the element to check.
230      * @return <code>true</code> if the List/array contains the element.
231      */
232     public Boolean   contains(Object   list, Object   element) {
233         if (this.isArray(list)) {
234             return this.arrayContains(list, element);
235         }
236         if (!this.isList(list)) {
237             return null;
238         }
239 
240         return new Boolean  (((List  ) list).contains(element));
241     }
242 
243     /**
244      * Checks if an array contains a certain element.
245      *
246      * @param array   the array to check.
247      * @param element the element to check.
248      * @return <code>true</code> if the array contains the element.
249      */
250     private Boolean   arrayContains(Object   array, Object   element) {
251         int size = this.size(array).intValue();
252 
253         for (int index = 0; index < size; ++index) {
254             if (this.equals(element, this.getFromArray(array, index))) {
255                 return Boolean.TRUE;
256             }
257         }
258         return Boolean.FALSE;
259     }
260 
261     /**
262      * Check if two objects are equal.
263      *
264      * @param what an object
265      * @param with another object.
266      * @return <code>true</code> if the two objects are equal.
267      */
268     private boolean equals(Object   what, Object   with) {
269         if (what == null) {
270             return with == null;
271         }
272 
273         return what.equals(with);
274     }
275 
276 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags