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.util.Collection; 23 import org.apache.velocity.tools.config.DefaultKey; 24 25 /** 26 * Simple tool to provide easy in-template instantiation of 27 * {@link Alternator}s from varying "list" types or individual 28 * arguments. 29 * 30 * <p><b>Example Use:</b> 31 * <pre> 32 * tools.xml... 33 * <tools> 34 * <toolbox scope="application"> 35 * <tool class="org.apache.velocity.tools.generic.AlternatorTool"/> 36 * </toolbox> 37 * </tools> 38 * 39 * template... 40 * #set( $color = $alternator.auto('red', 'blue') ) 41 * ## use manual alternation for this one 42 * #set( $style = $alternator.manual('hip','fly','groovy') ) 43 * #foreach( $i in [1..5] ) 44 * Number $i is $color and $style. I dig $style.next numbers. 45 * #end * 46 * 47 * output... 48 * Number 1 is red and hip. I dig hip numbers. 49 * Number 2 is blue and fly. I dig fly numbers. 50 * Number 3 is red and groovy. I dig groovy numbers. 51 * Number 4 is blue and hip. I dig hip numbers. 52 * Number 5 is red and fly. I dig fly numbers. 53 * </pre></p> 54 * 55 * @since Velocity Tools 1.2 56 * @version $Revision: 671010 $ $Date: 2008-06-23 20:40:41 -0700 (Mon, 23 Jun 2008) $ 57 */ 58 @DefaultKey("alternator") 59 public class AlternatorTool extends SafeConfig 60 { 61 @Deprecated 62 public static final String OLD_AUTO_ALTERNATE_DEFAULT_KEY = "auto-alternate"; 63 64 public static final String AUTO_ALTERNATE_DEFAULT_KEY = "autoAlternate"; 65 66 // it's true by default in Alternator 67 private boolean autoAlternateDefault = true; 68 69 /** 70 * Looks for a default auto-alternate value in the given params, 71 * if not, set the default to true. 72 */ 73 protected void configure(ValueParser parser) 74 { 75 Boolean auto = parser.getBoolean(AUTO_ALTERNATE_DEFAULT_KEY); 76 if (auto == null) 77 { 78 // check for old key, use true as default (just like Alternator) 79 auto = parser.getBoolean(OLD_AUTO_ALTERNATE_DEFAULT_KEY, 80 Boolean.TRUE); 81 } 82 this.autoAlternateDefault = auto.booleanValue(); 83 } 84 85 /** 86 * Returns true if the default for auto-alternating is true. 87 * @since VelocityTools 1.3 88 */ 89 public boolean getAutoAlternateDefault() 90 { 91 return autoAlternateDefault; 92 } 93 94 /** 95 * Sets the default for auto-alternating. 96 * @since VelocityTools 1.3 97 */ 98 protected void setAutoAlternateDefault(boolean bool) 99 { 100 this.autoAlternateDefault = bool; 101 } 102 103 /** 104 * Make an automatic {@link Alternator} from the specifed objects. 105 */ 106 public Alternator make(Object... list) 107 { 108 return make(autoAlternateDefault, list); 109 } 110 111 /** 112 * @deprecated Will be unnecessary with Velocity 1.6 113 */ 114 @Deprecated 115 public Alternator make(Collection list) 116 { 117 return make(autoAlternateDefault, list); 118 } 119 120 /** 121 * Returns a new Alternator for the specified list with the specified 122 * automatic shifting preference. 123 * 124 * @param auto See {@link Alternator#setAuto(boolean auto)}. 125 * @param list The list of elements to alternate. 126 */ 127 public Alternator make(boolean auto, Object... list) 128 { 129 if (list == null || list.length == 0) 130 { 131 return null; 132 } 133 else if (list.length == 1 && 134 list[0] instanceof Collection && 135 ((Collection)list[0]).isEmpty()) 136 { 137 return null; 138 } 139 return new Alternator(auto, list); 140 } 141 142 /** 143 * @deprecated Will be unnecessary with Velocity 1.6 144 */ 145 @Deprecated 146 public Alternator make(boolean auto, Collection list) 147 { 148 return make(auto, new Object[] { list }); 149 } 150 151 /** 152 * @deprecated Will be unnecessary with Velocity 1.6 153 */ 154 @Deprecated 155 public Alternator make(Object o1, Object o2) 156 { 157 return make(autoAlternateDefault, o1, o2); 158 } 159 160 /** 161 * @deprecated Will be unnecessary with Velocity 1.6 162 */ 163 @Deprecated 164 public Alternator make(boolean auto, Object o1, Object o2) 165 { 166 if (o1 == null || o2 == null) 167 { 168 return null; 169 } 170 return new Alternator(auto, new Object[] { o1, o2 }); 171 } 172 173 /** 174 * Make an automatic {@link Alternator} from the specified objects. 175 * 176 * @return a new, automatic Alternator with the specified values or 177 * <code>null</code> if there are none specified. 178 * @since VelocityTools 1.3 179 */ 180 public Alternator auto(Object... list) 181 { 182 return make(true, list); 183 } 184 185 /** 186 * @deprecated Will be unnecessary with Velocity 1.6 187 */ 188 @Deprecated 189 public Alternator auto(Collection list) 190 { 191 return make(true, list); 192 } 193 194 /** 195 * @deprecated Will be unnecessary with Velocity 1.6 196 */ 197 @Deprecated 198 public Alternator auto(Object o1, Object o2) 199 { 200 return make(true, o1, o2); 201 } 202 203 /** 204 * Make a manual {@link Alternator} from the specified objects. 205 * 206 * @return a new, manual Alternator with the values in the array or 207 * <code>null</code> if the array is <code>null</code>. 208 * @since VelocityTools 1.3 209 */ 210 public Alternator manual(Object... list) 211 { 212 return make(false, list); 213 } 214 215 /** 216 * @deprecated Will be unnecessary with Velocity 1.6 217 */ 218 @Deprecated 219 public Alternator manual(Collection list) 220 { 221 return make(false, list); 222 } 223 224 /** 225 * @deprecated Will be unnecessary with Velocity 1.6 226 */ 227 @Deprecated 228 public Alternator manual(Object o1, Object o2) 229 { 230 return make(false, o1, o2); 231 } 232 233 }