KickJava   Java API By Example, From Geeks To Geeks.

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


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