You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by jd...@apache.org on 2011/07/03 10:02:49 UTC
svn commit: r1142391 - in
/wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator:
AbstractHierarchyIterator.java AbstractHierarchyIteratorWithFilter.java
ComponentHierarchyIterator.java IteratorFilter.java
Author: jdonnerstag
Date: Sun Jul 3 08:02:48 2011
New Revision: 1142391
URL: http://svn.apache.org/viewvc?rev=1142391&view=rev
Log:
javadoc only
Issue: WICKET-3789
Modified:
wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIterator.java
wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIteratorWithFilter.java
wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/ComponentHierarchyIterator.java
wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/IteratorFilter.java
Modified: wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIterator.java
URL: http://svn.apache.org/viewvc/wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIterator.java?rev=1142391&r1=1142390&r2=1142391&view=diff
==============================================================================
--- wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIterator.java (original)
+++ wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIterator.java Sun Jul 3 08:02:48 2011
@@ -22,16 +22,17 @@ import org.apache.wicket.util.collection
import org.apache.wicket.util.lang.Args;
/**
- * This is a basic iterator for hierarchical structure such as Component hierarchies or HTML markup.
- * It supports child first and parent first traversal and intercepts while moving down or up the
- * hierarchy.
+ * This is a basic iterator for hierarchical structures such as Component hierarchies or HTML
+ * markup. It supports child first and parent first traversal and intercepts while moving down or up
+ * the hierarchy.
* <p>
* It assume the container class implements <code>Iterable</code>. The leaf nodes don't need to.
* <p>
- * Consecutive calls to hasNext() without next() in between, does not move the cursor, but returns
- * the same value until next() is called.
+ * Consecutive calls to <code>hasNext()</code> without <code>next()</code> in between, don't move
+ * the cursor, but return the same value until <code>next()</code> is called.
* <p>
- * Every call to next(), with or without hasNext(), will move the cursor to the next element.
+ * Every call to <code>next()</code>, with or without <code>hasNext()</code>, will move the cursor
+ * to the next element.
*
* @TODO Replace ChildFirst with a strategy
*
@@ -78,15 +79,15 @@ public abstract class AbstractHierarchyI
/**
*
- * @param elem
- * @return True, if elem is a container and has at least one child.
+ * @param node
+ * @return True, if node is a container and has at least one child.
*/
- abstract protected boolean hasChildren(final S elem);
+ abstract protected boolean hasChildren(final S node);
/**
* If node is a container than return an iterator for its children.
* <p>
- * Gets only called if {@link #hasChildren()} return true.
+ * Gets only called if {@link #hasChildren(Object)} return true.
*
* @param node
* @return container iterator
@@ -144,7 +145,7 @@ public abstract class AbstractHierarchyI
* @param node
* @return False if no more elements were found
*/
- protected boolean moveDown(final S node)
+ private boolean moveDown(final S node)
{
// Remember all details of the current level
stack.push(data);
@@ -158,9 +159,11 @@ public abstract class AbstractHierarchyI
}
/**
+ * Gets called for each element within the hierarchy (nodes and leafs)
*
* @param node
- * @return if false, than skip (filter) the node
+ * @return if false, than skip (filter) the element. It'll not stop the iterator from traversing
+ * into children though.
*/
protected boolean onFilter(final S node)
{
@@ -168,15 +171,21 @@ public abstract class AbstractHierarchyI
}
/**
+ * Gets called for each element where {@link #hasChildren(Object)} return true.
*
* @param node
- * @return if false, than skip (filter) the node
+ * @return if false, than do not traverse into the children and grand-children.
*/
protected boolean onTraversalFilter(final S node)
{
return true;
}
+ /**
+ * Get the next node from the underlying iterator and handle it.
+ *
+ * @return true, if one more element was found
+ */
private boolean nextNode()
{
// Get the next element
Modified: wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIteratorWithFilter.java
URL: http://svn.apache.org/viewvc/wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIteratorWithFilter.java?rev=1142391&r1=1142390&r2=1142391&view=diff
==============================================================================
--- wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIteratorWithFilter.java (original)
+++ wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/AbstractHierarchyIteratorWithFilter.java Sun Jul 3 08:02:48 2011
@@ -23,6 +23,7 @@ import org.apache.wicket.util.lang.Args;
import org.apache.wicket.util.lang.Generics;
/**
+ * Extend {@link AbstractHierarchyIterator} and add support for filters.
*
* @author Juergen Donnerstag
* @param <S>
@@ -46,19 +47,19 @@ public abstract class AbstractHierarchyI
}
/**
- * Allows to filter out component from the search.
+ * Apply all registered filters
*
- * @param comp
- * @return false, to filter the component. True, to continue processing the component.
+ * @param node
+ * @return False, to filter the component. True, to continue processing the component.
*/
@Override
- protected final boolean onFilter(final S comp)
+ protected final boolean onFilter(final S node)
{
if (filters != null)
{
for (IteratorFilter<S> filter : filters)
{
- if (filter.onFilter(comp) == false)
+ if (filter.onFilter(node) == false)
{
return false;
}
@@ -70,7 +71,8 @@ public abstract class AbstractHierarchyI
/**
*
* @param filter
- * @return Filters
+ * @return Gets the List of all registered filters. A new list will be created if no filter has
+ * been registered yet (never return null).
*/
public final List<IteratorFilter<S>> getFilters()
{
@@ -83,7 +85,7 @@ public abstract class AbstractHierarchyI
}
/**
- * Allow to add your own filter (fluent API)
+ * Add a filter (fluent API)
*
* @param filter
* @return this
@@ -97,11 +99,12 @@ public abstract class AbstractHierarchyI
}
/**
- * Replace the current set of filters
+ * Replace the current set of filters. Sometimes you need to first find X to than start
+ * searching for Y.
*
* @param filters
- * New filter set
- * @return Old filter set
+ * New filter set. May be null to remove all filters.
+ * @return Old filter set. Null, if no filter was registered.
*/
public Collection<IteratorFilter<S>> replaceFilterSet(
final Collection<IteratorFilter<S>> filters)
@@ -122,7 +125,8 @@ public abstract class AbstractHierarchyI
/**
* @param throwException
- * @return Find the the first Component matching all filters
+ * If true, an exception is thrown if no matching element was found.
+ * @return Find the the first element matching all filters
*/
public final S getFirst(final boolean throwException)
{
@@ -155,7 +159,8 @@ public abstract class AbstractHierarchyI
}
/**
- * @return Gets the traversal filters
+ * @return Gets the List of all registered traversal filters. A new list will be created if no
+ * traversal filter has been registered yet (never return null).
*/
public final List<IteratorFilter<S>> getTraverseFilters()
{
@@ -173,18 +178,17 @@ public abstract class AbstractHierarchyI
* @param filter
* @return this
*/
- public final AbstractHierarchyIteratorWithFilter<S> addTraverseFilters(
- final IteratorFilter<S> filter)
+ public AbstractHierarchyIteratorWithFilter<S> addTraverseFilters(final IteratorFilter<S> filter)
{
getTraverseFilters().add(filter);
return this;
}
/**
- * Allows to filter out component from the search.
+ * Apply all registered traversal filters
*
* @param node
- * @return false to skip traversing its children
+ * @return False, to filter the element. True, to continue processing the component.
*/
@Override
protected boolean onTraversalFilter(final S node)
Modified: wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/ComponentHierarchyIterator.java
URL: http://svn.apache.org/viewvc/wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/ComponentHierarchyIterator.java?rev=1142391&r1=1142390&r2=1142391&view=diff
==============================================================================
--- wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/ComponentHierarchyIterator.java (original)
+++ wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/ComponentHierarchyIterator.java Sun Jul 3 08:02:48 2011
@@ -25,12 +25,8 @@ import org.apache.wicket.util.lang.Args;
/**
* Iterator over the complete Component hierarchy. The implementation is parent first, meaning that
* first the parent gets returned upon next() and only than it's children.
- *
- * @TODO wrong sematic. next() should move it forward. hasNext() should never do it.
- * @TODO It'd be cool if next would return the class/generics provided via filterByClass
- * @TODO currently we have a parent first strategy only. A deepest child first strategy must be
- * useful as well.
- * @TODO make it more generic to work with Markup as well.
+ * <p>
+ * A fluent or builder type of API is provided to configure the iterator with filters.
*
* @author Juergen Donnerstag
*/
@@ -53,11 +49,11 @@ public class ComponentHierarchyIterator
* @param component
* Iterate over the containers children
* @param clazz
- * filter by class
+ * Add filter by class
* @param visible
- * if true, than ignore invisible components
+ * Add filter by visibility
* @param enabled
- * if true, than ignore disabled components
+ * Add filter by "enabled"
*/
public ComponentHierarchyIterator(final Component component, Class<?> clazz, boolean visible,
boolean enabled)
@@ -86,7 +82,7 @@ public class ComponentHierarchyIterator
* @param component
* Iterate over the containers children
* @param clazz
- * filter by class
+ * Add filter by class
*/
public ComponentHierarchyIterator(final Component component, Class<?> clazz)
{
@@ -94,7 +90,7 @@ public class ComponentHierarchyIterator
}
/**
- * Add a filter which returns only leaf components
+ * Add a filter which returns only leaf components.
*
* @return this
*/
@@ -117,12 +113,10 @@ public class ComponentHierarchyIterator
}
/**
- * Part of the fluent API: Filter Components by Class.
- * <p>
- * Must only be used before hasNext() has been called.
+ * Ignore components which don't implement (instanceof) the class provided.
*
* @param clazz
- * @return A new iterator with the added filter
+ * @return this
*/
public ComponentHierarchyIterator filterByClass(final Class<?> clazz)
{
@@ -142,11 +136,9 @@ public class ComponentHierarchyIterator
}
/**
- * Part of the fluent API: Ignore all Components which not visible in the hierachy
- * <p>
- * Must only be used before hasNext() has been called.
+ * Ignore all Components which not visible.
*
- * @return A new iterator with the added filter
+ * @return this
*/
public ComponentHierarchyIterator filterByVisibility()
{
@@ -166,11 +158,9 @@ public class ComponentHierarchyIterator
}
/**
- * Part of the fluent API: Ignore all Components which not enabled in the hierachy
- * <p>
- * Must only be used before hasNext() has been called.
+ * Ignore all Components which not enabled (disabled) in the hierarchy
*
- * @return A new iterator with the added filter
+ * @return this
*/
public ComponentHierarchyIterator filterEnabled()
{
@@ -190,13 +180,11 @@ public class ComponentHierarchyIterator
}
/**
- * Part of the fluent API: Accept only Components with matching id's.
- * <p>
- * Must only be used before hasNext() has been called.
+ * Ignore all components which don't match the id (regex).
*
* @param match
* Regex to find Components matching
- * @return A new iterator with the added filter
+ * @return this
*/
public ComponentHierarchyIterator filterById(final String match)
{
@@ -214,6 +202,9 @@ public class ComponentHierarchyIterator
return this;
}
+ /**
+ * The component must be a MarkupContainer to contain children
+ */
@Override
protected Iterator<Component> newIterator(final Component node)
{
@@ -224,6 +215,9 @@ public class ComponentHierarchyIterator
return null;
}
+ /**
+ * Only MarkupContainer's might have children
+ */
@Override
protected boolean hasChildren(Component elem)
{
@@ -240,4 +234,11 @@ public class ComponentHierarchyIterator
super.addFilter(filter);
return this;
}
+
+ @Override
+ public ComponentHierarchyIterator addTraverseFilters(IteratorFilter<Component> filter)
+ {
+ super.addTraverseFilters(filter);
+ return this;
+ }
}
\ No newline at end of file
Modified: wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/IteratorFilter.java
URL: http://svn.apache.org/viewvc/wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/IteratorFilter.java?rev=1142391&r1=1142390&r2=1142391&view=diff
==============================================================================
--- wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/IteratorFilter.java (original)
+++ wicket/trunk/wicket-core/src/main/java/org/apache/wicket/util/iterator/IteratorFilter.java Sun Jul 3 08:02:48 2011
@@ -18,6 +18,7 @@ package org.apache.wicket.util.iterator;
/**
+ * A simple filter interface for the hierarchy iterator.
*
* @author Juergen Donnerstag
* @param <S>
@@ -27,7 +28,7 @@ public abstract class IteratorFilter<S>
/**
*
* @param node
- * @return false, to filter the component. True, to continue processing the component.
+ * @return false, to filter the component. True, to continue processing the node.
*/
abstract boolean onFilter(S node);
}