View Javadoc

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   * &lt;tools&gt;
34   *   &lt;toolbox scope="application"&gt;
35   *     &lt;tool class="org.apache.velocity.tools.generic.AlternatorTool"/&gt;
36   *   &lt;/toolbox&gt;
37   * &lt;/tools&gt;
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 }