geirm 01/02/14 15:16:59
Modified: docs developer-guide.html
Log:
follow xml
Revision Changes Path
1.17 +56 -0 jakarta-velocity/docs/developer-guide.html
Index: developer-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- developer-guide.html 2001/02/12 20:03:26 1.16
+++ developer-guide.html 2001/02/14 23:16:58 1.17
@@ -184,6 +184,60 @@
That's really all there is to basic context operations. For more information, see
the API documentation included in the distribution.
</P>
+
+<B>Support for Iterative Objects for #foreach()</B>
+<P align="justify">
+As a programmer, you have great freedom in the objects that you put into the
context. But as with most freedoms, this one comes
+with a little bit of responsibility, so understand what Velocity supports, and any
issues that may arise. Velocity supports
+serveral types of collection types suitable for use in the VTL
+<CODE><FONT face="courier, monospaced">#foreach()</FONT></CODE> directive.
+
+<BLOCKQUOTE><UL>
+<LI> <CODE><FONT face="courier, monospaced">Object [] </FONT></CODE> Regular
object array, not much needs to be said here. Velocity will internally wrap your array
+in a class that provides an Iterator interface, but that shouldn't concern you as
the programmer, or the template author.</LI>
+<LI> <CODE><FONT face="courier, monospaced">java.util.Collection</FONT></CODE>
Velocity will use the <CODE><FONT face="courier, monospaced">iterator()</FONT></CODE>
+method to get an Iterator to use in the loop, so if you are implementing a
Collection interface on your object, please
+ensure that <CODE><FONT face="courier, monospaced">iterator()</FONT></CODE> returns
a working Iterator.</LI>
+<LI> <CODE><FONT face="courier, monospaced">java.util.Map </FONT></CODE> Here,
Velocity depends upon the <CODE><FONT face="courier,
monospaced">values()</FONT></CODE> method of the interface to get a <CODE><FONT
face="courier, monospaced">Collection</FONT></CODE> interface, on which <CODE><FONT
face="courier, monospaced">iterator()</FONT></CODE> is called to retrieve an Iterator
for the loop.</LI>
+<LI> <CODE><FONT face="courier, monospaced">java.util.Iterator</FONT></CODE> USE
WITH CAUTION : This is currently supported only provisionally -
+the issue of concern is the
+'non-resettablity' of the Iterator. If a 'naked' Iterator is placed into the
context, and used in more than one
+#foreach(), subsequent #foreach() blocks after the first will fail, as the Iterator
doesn't reset.</LI>
+</UL></BLOCKQUOTE>
+</P>
+
+<P align="justify">
+There are good reasons to use the <CODE><FONT face="courier,
monospaced">java.util.Iterator</FONT></CODE> interface directly (large data sets via
JDBC, for example), but
+if it can be avoided, it might be better to use something else. By 'directly' , we
meant doing something like :
+
+<DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD
bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0"
width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD
bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE>
+ Vector v = new Vector();
+ v.addElement("Hello");
+ v.addElement("There");
+
+ context.put("words", v.iterator() );
+</PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD></TR></TABLE></DIV>
+
+where the Iterator itself is placed into the context. Instead, if you simply did :
+
+<DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD
bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0"
width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD
bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE>
+
+ context.put("words", v );
+</PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD></TR></TABLE></DIV>
+
+then all would be fine : velocity would figure out that Vector implement Collection
(via List), and therefore will find the
+<CODE><FONT face="courier, monospaced">iterator()</FONT></CODE> method, and use
that to get a 'fresh' Iterator for its use each time it needs to. With just a plain
+Iterator (the first snippet above...), once velocity has used it in a <CODE><FONT
face="courier, monospaced">#foreach()</FONT></CODE>, Velocity has no way of
+getting a new one to use for the next <CODE><FONT face="courier,
monospaced">#foreach()</FONT></CODE> it is used in. The result is no output from any
subsequent
+<CODE><FONT face="courier, monospaced">#foreach()</FONT></CODE> blocks using that
reference.
+</P>
+
+<P align="justify">
+This above isn't meant to give the impression that iterating over collections in
Velocity is something that requires great care
+and thought. Rather, the opposite is true, in general. Just be careful when you
place an Iterator into the context.
+</P>
+
+
<B>Context Chaining</B>
<P align="justify">
An innovative feature of Velocity's context design is the concept of context
chaining.
@@ -235,6 +289,8 @@
</P>
</FONT></TD></TR></TABLE></DIV><BR>
+
+
<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="5"><B>Using Velocity In
Servlets</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0"
cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
<B>Programming</B>
