Author: hlship
Date: Tue Jun 1 14:24:23 2010
New Revision: 950085
URL: http://svn.apache.org/viewvc?rev=950085&view=rev
Log:
Improve Javadoc, being more specific about lazy vs. fully realizing operations,
and explicit about how Flows are initially created.
Modified:
tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/F.java
tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/Flow.java
Modified:
tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/F.java
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/F.java?rev=950085&r1=950084&r2=950085&view=diff
==============================================================================
---
tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/F.java
(original)
+++
tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/F.java
Tue Jun 1 14:24:23 2010
@@ -17,8 +17,15 @@ package org.apache.tapestry5.func;
import java.util.Collection;
/**
- * Functional operations on collections with generics support. Tending to use
the equivalent names from
- * Clojure. As with Clojure, all these functions return new lists.
+ * Functional operations on collections with generics support. The core
interface is {...@link Flow} to which operations
+ * and transformations
+ * (in terms of {...@link Predicate}s, {...@link Mapper}s and {...@link
Reducer}s) to create new Flows. Flows are initially
+ * created
+ * using {...@link #flow(Collection)} and {...@link #flow(Object...)}.
+ * <p>
+ * F will be used a bit, thus it has a short name (for those who don't like
static imports). It provides a base set of
+ * Predicate, Mapper and Reducer factories. A good development pattern for
applications is to provide a similar,
+ * application-specific, set of such factories.
*
* @since 5.2.0
*/
@@ -160,7 +167,7 @@ public class F
};
}
- /** Allows Mapper that maps to boolean to be used as a Predicate. */
+ /** Allows a Mapper that maps to boolean to be used as a Predicate. */
public static <S> Predicate<S> toPredicate(final Mapper<S, Boolean> mapper)
{
return new Predicate<S>()
Modified:
tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/Flow.java
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/Flow.java?rev=950085&r1=950084&r2=950085&view=diff
==============================================================================
---
tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/Flow.java
(original)
+++
tapestry/tapestry5/trunk/tapestry-ioc/src/main/java/org/apache/tapestry5/func/Flow.java
Tue Jun 1 14:24:23 2010
@@ -22,11 +22,13 @@ import java.util.List;
* A given Flow contains only values of a particular type. Standard operations
allow for
* filtering the Flow, or appending values to the Flow. Since Flows are
immutable, all operations
* on Flows return new immutable Flows. Flows are thread safe (to the extent
that the {...@link Mapper}s, {...@link Predicate}
- * s, {...@link Worker}s and {...@link Reducer}s are).
+ * s, {...@link Worker}s and {...@link Reducer}s applied to the Flow are).
* Flows are <em>lazy</em>: filtering, mapping, and concatenating Flows will
do so with no, or a minimum, of evaluation.
* However, converting a Flow into a {...@link List} will force a realization
of the entire Flow.
* <p>
* Using Flows allows for a very fluid interface.
+ * <p>
+ * Flows are initially created using {...@link F#flow(java.util.Collection)}
or {...@link F#flow(Object...)}.
*
* @since 5.2.0
*/
@@ -52,37 +54,44 @@ public interface Flow<T> extends Iterabl
/**
* Applies a Reducer to the values of the Flow. The Reducer is passed the
initial value
- * and the first value from the flow. The result is captured as the
accumulator and passed
- * to the Reducer with the next value from the flow, and so on. The final
accumulator
+ * and the first value from the Flow. The result is captured as the
accumulator and passed
+ * to the Reducer with the next value from the Flow, and so on. The final
accumulator
* value is returned. If the flow is empty, the initial value is returned.
+ * <p>
+ * Reducing is a non-lazy operation; it will fully realize the values of
the Flow.
*/
<A> A reduce(Reducer<A, T> reducer, A initial);
/**
* Applies the worker to each value in the Flow, then returns the flow for
further behaviors.
+ * <p>
+ * Each is a non-lazy operation; it will fully realize the values of the
Flow.
*/
Flow<T> each(Worker<? super T> worker);
- /** Converts the Flow into an unmodifiable list of values. */
+ /**
+ * Converts the Flow into an unmodifiable list of values. This is a
non-lazy operation that will fully realize
+ * the values of the Flow.
+ */
List<T> toList();
/** Returns a new flow with the same elements but in reverse order. */
Flow<T> reverse();
- /** Returns true if the Flow contains no values. */
+ /** Returns true if the Flow contains no values. This <em>may</em> realize
the first value in the Flow. */
boolean isEmpty();
- /** Returns a new Flow with the other Flow's elements appended to this
Flow's. */
+ /** Returns a new Flow with the other Flow's elements appended to this
Flow's. This is a lazy operation. */
Flow<T> concat(Flow<? extends T> other);
- /** Returns a new Flow with the values in the list appended to this Flow.
*/
+ /** Returns a new Flow with the values in the list appended to this Flow.
This is a lazy operation. */
Flow<T> concat(List<? extends T> list);
- /** Appends any number of type compatible values to the end of this Flow.
*/
+ /** Appends any number of type compatible values to the end of this Flow.
This is a lazy operation. */
<V extends T> Flow<T> append(V... values);
/**
- * Sorts this Flow, forming a new Flow.
+ * Sorts this Flow, forming a new Flow. This is a non-lazy operation; it
will fully realize the values of the Flow.
*
* @throws ClassCastException
* if type <T> does not extend {...@link Comparable}
@@ -90,13 +99,15 @@ public interface Flow<T> extends Iterabl
Flow<T> sort();
/**
- * Sorts this Flow using the comparator, forming a new Flow.
+ * Sorts this Flow using the comparator, forming a new Flow. This is a
non-lazy operation; it will fully realize the
+ * values of the Flow.
*/
Flow<T> sort(Comparator<? super T> comparator);
/**
* Returns the first value in the Flow. Returns null for empty flows, but
remember that null is a valid
- * value within a flow, so use {...@link #isEmpty() to determine if a flow
is actually empty.
+ * value within a flow, so use {...@link #isEmpty() to determine if a flow
is actually empty. The first value can be
+ * realized without realizing the full Flow.
*/
T first();
