KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tapestry > components > Foreach


1 // Copyright 2004, 2005 The Apache Software Foundation
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 package org.apache.tapestry.components;
16
17 import java.util.Iterator JavaDoc;
18
19 import org.apache.tapestry.AbstractComponent;
20 import org.apache.tapestry.IMarkupWriter;
21 import org.apache.tapestry.IRequestCycle;
22 import org.apache.tapestry.Tapestry;
23 import org.apache.tapestry.coerce.ValueConverter;
24
25 /**
26  * Repeatedly renders its wrapped contents while iterating through a list of values. [ <a
27  * HREF="../../../../../ComponentReference/Foreach.html">Component Reference </a>]
28  * <p>
29  * While the component is rendering, the property {@link #getValue() value}(accessed as
30  * <code>components.<i>foreach</i>.value</code> is set to each successive value from the source,
31  * and the property {@link #getIndex() index}is set to each successive index into the source
32  * (starting with zero).
33  *
34  * @author Howard Lewis Ship
35  */
36
37 public abstract class Foreach extends AbstractComponent
38 {
39     private Object JavaDoc _value;
40
41     private int _index;
42
43     /**
44      * Gets the source binding and returns an {@link Iterator}representing the values identified by
45      * the source. Returns an empty {@link Iterator}if the binding, or the binding value, is null.
46      * <p>
47      * Invokes {@link Tapestry#coerceToIterator(Object)}to perform the actual conversion.
48      */
49
50     protected Iterator JavaDoc getSourceData()
51     {
52         Object JavaDoc source = getSource();
53
54         if (source == null)
55             return null;
56
57         return (Iterator JavaDoc) getValueConverter().coerceValue(source, Iterator JavaDoc.class);
58     }
59
60     protected void prepareForRender(IRequestCycle cycle)
61     {
62         _value = null;
63         _index = 0;
64     }
65
66     protected void cleanupAfterRender(IRequestCycle cycle)
67     {
68         _value = null;
69     }
70
71     /**
72      * Gets the source binding and iterates through its values. For each, it updates the value
73      * binding and render's its wrapped elements.
74      */
75
76     protected void renderComponent(IMarkupWriter writer, IRequestCycle cycle)
77     {
78         Iterator JavaDoc dataSource = getSourceData();
79
80         // The dataSource was either not convertable, or was empty.
81
82         if (dataSource == null)
83             return;
84
85         boolean indexBound = isParameterBound("index");
86         boolean valueBound = isParameterBound("value");
87
88         String JavaDoc element = getElement();
89
90         boolean hasNext = dataSource.hasNext();
91
92         while (hasNext)
93         {
94             _value = dataSource.next();
95             hasNext = dataSource.hasNext();
96
97             if (indexBound)
98                 setIndexParameter(_index);
99
100             if (valueBound)
101                 setValueParameter(_value);
102
103             if (element != null)
104             {
105                 writer.begin(element);
106                 renderInformalParameters(writer, cycle);
107             }
108
109             renderBody(writer, cycle);
110
111             if (element != null)
112                 writer.end();
113
114             _index++;
115         }
116
117     }
118
119     /**
120      * Returns the most recent value extracted from the source parameter.
121      *
122      * @throws org.apache.tapestry.ApplicationRuntimeException
123      * if the Foreach is not currently rendering.
124      */
125
126     public Object JavaDoc getValue()
127     {
128         if (!isRendering())
129             throw Tapestry.createRenderOnlyPropertyException(this, "value");
130
131         return _value;
132     }
133
134     public abstract String JavaDoc getElement();
135
136     public abstract Object JavaDoc getSource();
137
138     /**
139      * The index number, within the {@link #getSource() source}, of the the current value.
140      *
141      * @throws org.apache.tapestry.ApplicationRuntimeException
142      * if the Foreach is not currently rendering.
143      * @since 2.2
144      */
145
146     public int getIndex()
147     {
148         if (!isRendering())
149             throw Tapestry.createRenderOnlyPropertyException(this, "index");
150
151         return _index;
152     }
153
154     /** @since 4.0 */
155     public abstract void setIndexParameter(int value);
156
157     /** @since 4.0 */
158     public abstract void setValueParameter(Object JavaDoc value);
159
160     /** @since 4.0 */
161     public abstract ValueConverter getValueConverter();
162 }
Popular Tags