KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > velocity > tools > generic > ExtendedListTool


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 JavaDoc;
20 import java.lang.reflect.Method JavaDoc;
21 import java.util.ArrayList JavaDoc;
22 import java.util.List JavaDoc;
23
24 /**
25  * Tool for working with Lists and arrays in Velocity templates.
26  * In addition to the features ListTool provides,
27  * it provides the function to retrieve the length,
28  * and create clones of a list or an array object.
29  * Also provides a method to convert arrays into Lists and
30  * Lists into arrays.
31  * <p/>
32  * <p><pre>
33  * Example uses:
34  * $primes -> new int[] {2, 3, 5, 7}
35  * $list.length($primes) -> 4
36  * $list.get($primes, 2) -> 5
37  * $list.clone($primes) -> int[] {2, 3, 5, 7}, != $primes
38  * $list.set($primes, 2, 1) -> (primes[2] becomes 1)
39  * $list.get($primes, 2) -> 1
40  * $list.get($clone, 2) -> 5
41  * <p/>
42  * Example toolbox.xml config (if you want to use this with VelocityView):
43  * &lt;tool&gt;
44  * &lt;key&gt;list&lt;/key&gt;
45  * &lt;scope&gt;application&lt;/scope&gt;
46  * &lt;class&gt;org.apache.velocity.tools.generic.ExtendedListTool&lt;/class&gt;
47  * &lt;/tool&gt;
48  * </pre></p>
49  * <p/>
50  * <p>This tool is entirely threadsafe, and has no instance members.
51  * It may be used in any scope (request, session, or application).
52  * </p>
53  *
54  * @author <a HREF="mailto:shinobu@ieee.org">Shinobu Kawai</a>
55  * @version $Id: ExtendedListTool.java,v 1.1 2006/03/23 06:36:11 czarneckid Exp $
56  */
57 public class ExtendedListTool extends ListTool {
58
59     /**
60      * Default constructor.
61      */
62     public ExtendedListTool() {
63     }
64
65     /**
66      * Converts an array object into a List.
67      * <ul>
68      * <li>
69      * If the object is already a List,
70      * it will return the object itself.
71      * </li>
72      * <li>
73      * If the object is an array of an Object,
74      * it will return a List of the elements.
75      * </li>
76      * <li>
77      * If the object is an array of a primitive type,
78      * it will return a List of the elements wrapped in their wrapper class.
79      * </li>
80      * <li>
81      * If the object is none of the above, it will return null.
82      * </li>
83      * </ul>
84      *
85      * @param array an array object.
86      * @return the converted java.util.List.
87      */
88     public List JavaDoc toList(Object JavaDoc array) {
89         if (this.isList(array)) {
90             return (List JavaDoc) array;
91         }
92         if (!this.isArray(array)) {
93             return null;
94         }
95
96         // Thanks to Eric Fixler for this refactor.
97 int length = Array.getLength(array);
98         List JavaDoc asList = new ArrayList JavaDoc(length);
99         for (int index = 0; index < length; ++index) {
100             asList.add(Array.get(array, index));
101         }
102         return asList;
103     }
104
105     /**
106      * Converts a List object into an array.
107      * <ul>
108      * <li>
109      * If the object is already an array,
110      * it will return the object itself.
111      * </li>
112      * <li>
113      * If the object is a List,
114      * it will return an array according to the object's
115      * <code>toArray()</code> method.
116      * </li>
117      * <li>
118      * If the object is none of the above, it will return null.
119      * </li>
120      * </ul>
121      *
122      * @param list a List object.
123      * @return the converted array.
124      */
125     public Object JavaDoc toArray(Object JavaDoc list) {
126         if (this.isArray(list)) {
127             return list;
128         }
129         if (!this.isList(list)) {
130             return null;
131         }
132
133         List JavaDoc asList = (List JavaDoc) list;
134         return asList.toArray(new Object JavaDoc[asList.size()]);
135     }
136
137     /**
138      * Gets the length of an array/List.
139      * It will return null under the following conditions:
140      * <ul>
141      * <li><code>array</code> is null.</li>
142      * <li><code>array</code> is not an array/List.</li>
143      * </ul>
144      * The result will be same as the {@link #size(Object)} method.
145      *
146      * @param array the array object.
147      * @return the length of the array.
148      * @see #size(Object)
149      */
150     public Integer JavaDoc length(Object JavaDoc array) {
151         if (this.isList(array)) {
152             return this.size(array);
153         }
154         if (!this.isArray(array)) {
155             return null;
156         }
157
158         // Thanks to Eric Fixler for this refactor.
159 return new Integer JavaDoc(Array.getLength(array));
160     }
161
162     /**
163      * Gets the clone 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      *
170      * @param list the List/array object.
171      * @return the clone of the List/array.
172      */
173     public Object JavaDoc clone(Object JavaDoc list) {
174         if (this.isArray(list)) {
175             Class JavaDoc type = list.getClass().getComponentType();
176             int length = Array.getLength(list);
177             Object JavaDoc clone = Array.newInstance(type, length);
178             System.arraycopy(list, 0, clone, 0, length);
179             return clone;
180         }
181         if (!this.isList(list)) {
182             return null;
183         }
184
185         // first, try the clone() method.
186 Class JavaDoc clazz = list.getClass();
187         try {
188             Method JavaDoc cloneMethod = clazz.getMethod("clone", new Class JavaDoc[0]);
189             return cloneMethod.invoke(list, null);
190         }
191         catch (Exception JavaDoc ignoreAndTryTheNextStep) {
192         }
193
194         // try to copy to a new instance.
195 try {
196             List JavaDoc clone = (List JavaDoc) clazz.newInstance();
197             clone.addAll(((List JavaDoc) list));
198             return clone;
199         }
200         catch (Exception JavaDoc ignoreAndTryTheNextStep) {
201         }
202
203         // last resort.
204 return new ArrayList JavaDoc(((List JavaDoc) list));
205     }
206
207 }
Popular Tags