001: package org.apache.velocity.tools.generic;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.util.List;
023: import java.util.Map;
024:
025: /**
026: * Simple tool to provide easy in-template instantiation of
027: * {@link Alternator}s from varying "list" types.
028: *
029: * <p><b>Example Use:</b>
030: * <pre>
031: * toolbox.xml...
032: * <tool>
033: * <key>alternator</key>
034: * <scope>application</scope>
035: * <class>org.apache.velocity.tools.generic.AlternatorTool</class>
036: * <parameter name="auto-alternate" value="true"/>
037: * </tool>
038: *
039: * template...
040: * #set( $color = $alternator.auto('red', 'blue') )
041: * ## use manual alternation for this one
042: * #set( $style = $alternator.manual(['hip','fly','groovy']) )
043: * #foreach( $i in [1..5] )
044: * Number $i is $color and $style. I dig $style.next numbers.
045: * #end *
046: *
047: * output...
048: * Number 1 is red and hip. I dig hip numbers.
049: * Number 2 is blue and fly. I dig fly numbers.
050: * Number 3 is red and groovy. I dig groovy numbers.
051: * Number 4 is blue and hip. I dig hip numbers.
052: * Number 5 is red and fly. I dig fly numbers.
053: * </pre></p>
054: *
055: * @since Velocity Tools 1.2
056: * @version $Revision: 484710 $ $Date: 2006-12-08 11:40:42 -0800 (Fri, 08 Dec 2006) $
057: */
058: public class AlternatorTool {
059: /** @since VelocityTools 1.3 */
060: public static final String AUTO_ALTERNATE_DEFAULT_KEY = "auto-alternate";
061:
062: // it's true by default in Alternator
063: private boolean autoAlternateDefault = true;
064:
065: /**
066: * Looks for a default auto-alternate value in the given params,
067: * if not, set the default to true.
068: * @since VelocityTools 1.3
069: */
070: public void configure(Map params) {
071: ValueParser parser = new ValueParser(params);
072: // it's true by default in Alternator
073: autoAlternateDefault = parser.getBoolean(
074: AUTO_ALTERNATE_DEFAULT_KEY, true);
075: }
076:
077: /**
078: * Returns true if the default for auto-alternating is true.
079: * @since VelocityTools 1.3
080: */
081: public boolean getAutoAlternateDefault() {
082: return autoAlternateDefault;
083: }
084:
085: /**
086: * Sets the default for auto-alternating.
087: * @since VelocityTools 1.3
088: */
089: protected void setAutoAlternateDefault(boolean bool) {
090: this .autoAlternateDefault = bool;
091: }
092:
093: /**
094: * Make an automatic {@link Alternator} from a List.
095: */
096: public Alternator make(List list) {
097: return make(autoAlternateDefault, list);
098: }
099:
100: /**
101: * @deprecated Use {@link #auto(List list)} or
102: * {@link #manual(List list)} instead.
103: */
104: public Alternator make(boolean auto, List list) {
105: if (list == null) {
106: return null;
107: }
108: return new Alternator(auto, list);
109: }
110:
111: /**
112: * Make an automatic {@link Alternator} from an object array.
113: */
114: public Alternator make(Object[] array) {
115: return make(autoAlternateDefault, array);
116: }
117:
118: /**
119: * @deprecated Use {@link #auto(Object[] array)} or
120: * {@link #manual(Object[] array)} instead.
121: */
122: public Alternator make(boolean auto, Object[] array) {
123: if (array == null) {
124: return null;
125: }
126: return new Alternator(auto, array);
127: }
128:
129: /**
130: * Make an automatic {@link Alternator} from a list containing the two
131: * specified objects.
132: *
133: * @return The new Alternator, or <code>null</code> if arguments
134: * were illegal.
135: */
136: public Alternator make(Object o1, Object o2) {
137: return make(autoAlternateDefault, o1, o2);
138: }
139:
140: /**
141: * @deprecated Use {@link #auto(Object o1, Object o2)} or
142: * {@link #manual(Object o1, Object o2)} instead.
143: */
144: public Alternator make(boolean auto, Object o1, Object o2) {
145: if (o1 == null || o2 == null) {
146: return null;
147: }
148: return new Alternator(auto, new Object[] { o1, o2 });
149: }
150:
151: /**
152: * Make an automatic {@link Alternator} from values in the specified List.
153: *
154: * @return a new, automatic Alternator with the values in the List or
155: * <code>null</code> if the List is <code>null</code>.
156: * @since VelocityTools 1.3
157: */
158: public Alternator auto(List list) {
159: return make(true, list);
160: }
161:
162: /**
163: * Make an automatic {@link Alternator} from the specified object array.
164: *
165: * @return a new, automatic Alternator with the values in the array or
166: * <code>null</code> if the array is <code>null</code>.
167: * @since VelocityTools 1.3
168: */
169: public Alternator auto(Object[] array) {
170: return make(true, array);
171: }
172:
173: /**
174: * Make an automatic {@link Alternator} from a list containing the two
175: * specified objects.
176: *
177: * @param o1 The first of two objects for alternation between.
178: * Must be non-<code>null</code>.
179: * @param o2 The second of two objects for alternation between.
180: * Must be non-<code>null</code>.
181: * @return The new Alternator, or <code>null</code> if an argument
182: * was <code>null</code>.
183: * @since VelocityTools 1.3
184: */
185: public Alternator auto(Object o1, Object o2) {
186: return make(true, o1, o2);
187: }
188:
189: /**
190: * Make a manual {@link Alternator} from values in the specified List.
191: *
192: * @return a new, manual Alternator with the values in the List or
193: * <code>null</code> if the List is <code>null</code>.
194: * @since VelocityTools 1.3
195: */
196: public Alternator manual(List list) {
197: return make(false, list);
198: }
199:
200: /**
201: * Make a manual {@link Alternator} from the specified object array.
202: *
203: * @return a new, manual Alternator with the values in the array or
204: * <code>null</code> if the array is <code>null</code>.
205: * @since VelocityTools 1.3
206: */
207: public Alternator manual(Object[] array) {
208: return make(false, array);
209: }
210:
211: /**
212: * Make a manual {@link Alternator} from a list containing the two
213: * specified objects.
214: *
215: * @param o1 The first of two objects for alternation between.
216: * Must be non-<code>null</code>.
217: * @param o2 The second of two objects for alternation between.
218: * Must be non-<code>null</code>.
219: * @return The new Alternator, or <code>null</code> if an argument
220: * was <code>null</code>.
221: * @since VelocityTools 1.3
222: */
223: public Alternator manual(Object o1, Object o2) {
224: return make(false, o1, o2);
225: }
226:
227: }
|