Author: ivaynberg
Date: Thu Mar 25 22:31:13 2010
New Revision: 927613
URL: http://svn.apache.org/viewvc?rev=927613&view=rev
Log:
javadoc for visitor stuff
Modified:
wicket/trunk/wicket-util/.settings/org.eclipse.jdt.core.prefs
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/ClassVisitFilter.java
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisit.java
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitFilter.java
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitor.java
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visit.java
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visits.java
Modified: wicket/trunk/wicket-util/.settings/org.eclipse.jdt.core.prefs
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket-util/.settings/org.eclipse.jdt.core.prefs?rev=927613&r1=927612&r2=927613&view=diff
==============================================================================
--- wicket/trunk/wicket-util/.settings/org.eclipse.jdt.core.prefs (original)
+++ wicket/trunk/wicket-util/.settings/org.eclipse.jdt.core.prefs Thu Mar 25
22:31:13 2010
@@ -1,6 +1,26 @@
-#Sun Mar 21 09:29:23 EET 2010
-eclipse.preferences.version=1
-org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5
-org.eclipse.jdt.core.compiler.compliance=1.5
-org.eclipse.jdt.core.compiler.problem.forbiddenReference=warning
-org.eclipse.jdt.core.compiler.source=1.5
+#Thu Mar 25 09:04:49 PDT 2010
+eclipse.preferences.version=1
+org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
+org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5
+org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
+org.eclipse.jdt.core.compiler.compliance=1.5
+org.eclipse.jdt.core.compiler.debug.lineNumber=generate
+org.eclipse.jdt.core.compiler.debug.localVariable=generate
+org.eclipse.jdt.core.compiler.debug.sourceFile=generate
+org.eclipse.jdt.core.compiler.doc.comment.support=enabled
+org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
+org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
+org.eclipse.jdt.core.compiler.problem.forbiddenReference=warning
+org.eclipse.jdt.core.compiler.problem.invalidJavadoc=warning
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTags=enabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsDeprecatedRef=enabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsNotVisibleRef=enabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsVisibility=public
+org.eclipse.jdt.core.compiler.problem.missingJavadocComments=warning
+org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsOverriding=disabled
+org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsVisibility=public
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=all_standard_tags
+org.eclipse.jdt.core.compiler.problem.missingJavadocTags=warning
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagsOverriding=disabled
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagsVisibility=public
+org.eclipse.jdt.core.compiler.source=1.5
Modified:
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/ClassVisitFilter.java
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/ClassVisitFilter.java?rev=927613&r1=927612&r2=927613&view=diff
==============================================================================
---
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/ClassVisitFilter.java
(original)
+++
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/ClassVisitFilter.java
Thu Mar 25 22:31:13 2010
@@ -1,19 +1,33 @@
package org.apache.wicket.util.visit;
+/**
+ * {...@link IVisitFilter} that restricts visitors to only visiting objects of
the
+ * specified class
+ *
+ * @author igor.vaynberg
+ */
public class ClassVisitFilter implements IVisitFilter
{
private final Class<?> clazz;
+ /**
+ * Constructor
+ *
+ * @param clazz
+ * class of objects that visitors should be restricted to
+ */
public ClassVisitFilter(Class<?> clazz)
{
this.clazz = clazz;
}
+ /** {...@inheritdoc} */
public boolean visitChildren(Object object)
{
return true;
}
+ /** {...@inheritdoc} */
public boolean visitObject(Object object)
{
return clazz.isAssignableFrom(object.getClass());
Modified:
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisit.java
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisit.java?rev=927613&r1=927612&r2=927613&view=diff
==============================================================================
---
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisit.java
(original)
+++
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisit.java
Thu Mar 25 22:31:13 2010
@@ -1,10 +1,31 @@
package org.apache.wicket.util.visit;
+/**
+ * Allows visitors to control the visit/traversal
+ *
+ * @author igor.vaynberg
+ *
+ * @param <R>
+ * type of object the visitor is expected to return, if none use
+ * {...@link Void}
+ */
public interface IVisit<R>
{
+ /**
+ * Stops the visit/traversal
+ */
void stop();
+ /**
+ * Stops the visit/traversal and returns {...@code result}
+ *
+ * @param result
+ */
void stop(R result);
+ /**
+ * Prevents the visitor from visiting any children of the object
currently
+ * visited
+ */
void dontGoDeeper();
}
Modified:
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitFilter.java
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitFilter.java?rev=927613&r1=927612&r2=927613&view=diff
==============================================================================
---
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitFilter.java
(original)
+++
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitFilter.java
Thu Mar 25 22:31:13 2010
@@ -1,22 +1,45 @@
package org.apache.wicket.util.visit;
+/**
+ * A filter that can be used to restrict the types of objects visited by the
+ * visitor
+ *
+ * @author igor.vaynberg
+ */
public interface IVisitFilter
{
+ /**
+ * Controls whether or not the {...@code object} will be visited
+ *
+ * @param object
+ * @return {...@code true} if the object should be visited
+ */
boolean visitObject(Object object);
+ /**
+ * Controls whether or not the {...@code object}'s children will be
visited
+ *
+ * @param object
+ * @return {...@code true} if the object's children should be visited
+ */
boolean visitChildren(Object object);
+ /**
+ * A visitor filter that allows all objects and their children to be
visited
+ */
public static IVisitFilter ANY = new IVisitFilter()
{
+ /** {...@inheritdoc} */
public boolean visitObject(Object object)
{
return true;
}
+ /** {...@inheritdoc} */
public boolean visitChildren(Object object)
{
return true;
}
};
-
+
}
Modified:
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitor.java
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitor.java?rev=927613&r1=927612&r2=927613&view=diff
==============================================================================
---
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitor.java
(original)
+++
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/IVisitor.java
Thu Mar 25 22:31:13 2010
@@ -2,24 +2,23 @@ package org.apache.wicket.util.visit;
/**
- * Generic component visitor interface for component traversals.
+ * Generic visitor interface for traversals.
*
* @param <T>
- * The component
+ * type of object to be visited
+ * @param <R>
+ * type of value the visitor should return as the result of the
+ * visit/traversal
*/
public interface IVisitor<T, R>
{
/**
- * Called at each component in a visit.
+ * Called at each object in a visit.
*
- * @param component
- * The component
- * @param traversal
- * An {...@link IVisit} which state will be modified
depending on
- * the visitation. CONTINUE_TRAVERSAL (null) if the traversal
- * should continue, or a non-null return value for the
traversal
- * method if it should stop. If no return value is useful,
the
- * generic non-null value STOP_TRAVERSAL can be used.
+ * @param object
+ * Object being visited
+ * @param visit
+ * Object used to control the visit/traversal
*/
- public void component(T component, IVisit<R> visit);
+ public void component(T object, IVisit<R> visit);
}
\ No newline at end of file
Modified:
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visit.java
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visit.java?rev=927613&r1=927612&r2=927613&view=diff
==============================================================================
---
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visit.java
(original)
+++
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visit.java
Thu Mar 25 22:31:13 2010
@@ -1,50 +1,85 @@
package org.apache.wicket.util.visit;
-public class Visit<R> implements IVisit<R>
- {
- private static enum Action {
- CONTINUE, CONTINUE_BUT_DONT_GO_DEEPER, STOP;
- }
-
- private R result;
- private Action action = Action.CONTINUE;
- public void stop()
- {
- stop(null);
- }
+/**
+ * Implementation of {...@link IVisit} used by traversal algorithms
+ *
+ * @author igor.vaynberg
+ *
+ * @param <R>
+ * type of object that should be returned by the visit/traversal
+ */
+public class Visit<R> implements IVisit<R>
+{
+ private static enum Action {
+ CONTINUE, CONTINUE_BUT_DONT_GO_DEEPER, STOP;
+ }
- public void stop(R result)
- {
- action = Action.STOP;
- this.result = result;
- }
+ private R result;
+ private Action action = Action.CONTINUE;
- public void dontGoDeeper()
- {
- action = Action.CONTINUE_BUT_DONT_GO_DEEPER;
- }
+ /** {...@inheritdoc} */
+ public void stop()
+ {
+ stop(null);
+ }
- public boolean isStopped()
- {
- return action == Action.STOP;
- }
+ /** {...@inheritdoc} */
+ public void stop(R result)
+ {
+ action = Action.STOP;
+ this.result = result;
+ }
- public boolean isContinue()
- {
- return action == Action.CONTINUE;
- }
+ /** {...@inheritdoc} */
+ public void dontGoDeeper()
+ {
+ action = Action.CONTINUE_BUT_DONT_GO_DEEPER;
+ }
- public boolean isDontGoDeeper()
- {
- return action == Action.CONTINUE_BUT_DONT_GO_DEEPER;
- }
+ /**
+ * Checks if the visit/traversal has been stopped
+ *
+ * @return {...@code true} if the visit/traversal has been stopped
+ */
+ public boolean isStopped()
+ {
+ return action == Action.STOP;
+ }
- public R getResult()
- {
- return result;
- }
+ /**
+ * Checks if the visit/traversal should continue
+ *
+ * @return {...@code true} if the visit/traversal should continue
+ */
+ public boolean isContinue()
+ {
+ return action == Action.CONTINUE;
+ }
+ /**
+ * Checks if the visit/traversal has been stopped from visiting
children of
+ * the currently visited object
+ *
+ * @return {...@code true} if the visit/traversal should not visit
children of
+ * the currently visited object
+ */
+ public boolean isDontGoDeeper()
+ {
+ return action == Action.CONTINUE_BUT_DONT_GO_DEEPER;
+ }
+ /**
+ * Gets the result of the visit/traversal. This value is set using
+ * {...@link #stop(Object)} or remains {...@code null} if
visit/traversal has
+ * ended in any other way
+ *
+ * @return value that should be returned to the method that initiated
the
+ * visit/traversal
+ */
+ public R getResult()
+ {
+ return result;
}
-
\ No newline at end of file
+
+}
Modified:
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visits.java
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visits.java?rev=927613&r1=927612&r2=927613&view=diff
==============================================================================
---
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visits.java
(original)
+++
wicket/trunk/wicket-util/src/main/java/org/apache/wicket/util/visit/Visits.java
Thu Mar 25 22:31:13 2010
@@ -3,11 +3,38 @@ package org.apache.wicket.util.visit;
import java.util.Iterator;
+/**
+ * Utility class that contains visitor/traversal related code
+ */
public class Visits
{
- // TODO replace class argument with IVisitFilter
- public static final <S, R> R visitChildren(Iterable<?> container,
- final IVisitor<S, R> visitor, IVisitFilter filter)
+ /** Constructor */
+ private Visits()
+ {
+
+ }
+
+ /**
+ * Visits children of the specified {...@link Iterable} pre-order
(parent
+ * first). Children are determined by calling {...@link
Iterable#iterator()}.
+ *
+ * @param <S>
+ * the type of object that will be visited, notice that
{...@code
+ * container} is not declared as {...@code Iterable<S>}
because it
+ * may return a generalization of {...@code S}
+ * @param <R>
+ * the type of object that should be returned from the
visitor,
+ * use {...@link Void} if no return value is needed
+ * @param container
+ * object whose children will be visited
+ * @param visitor
+ * the visitor
+ * @param filter
+ * filter used to limit the types of objects that will be
visited
+ * @return return value from the {...@code visitor} or {...@code null}
if none
+ */
+ public static final <S, R> R visitChildren(Iterable<?> container, final
IVisitor<S, R> visitor,
+ IVisitFilter filter)
{
Visit<R> visit = new Visit<R>();
visitChildren(container, visitor, filter, visit);
@@ -15,7 +42,7 @@ public class Visits
}
- private static final <S, R> void visitChildren(Iterable<?> container,
+ private static final <S, R> void visitChildren(Iterable<?> container,
final IVisitor<S, R> visitor, IVisitFilter filter,
Visit<R> visit)
{
if (visitor == null)
@@ -51,10 +78,11 @@ public class Visits
}
// If child is a container
- if (!visit.isDontGoDeeper() && (child instanceof
Iterable<?>)&&filter.visitChildren(child))
+ if (!visit.isDontGoDeeper() && (child instanceof
Iterable<?>)
+ && filter.visitChildren(child))
{
// visit the children in the container
- visitChildren((Iterable<?>)child, visitor,
filter, visit);
+ visitChildren((Iterable<?>)child, visitor,
filter, visit);
if (visit.isStopped())
{
@@ -67,46 +95,72 @@ public class Visits
}
/**
- * Traverses all child components in this container, calling the
visitor's
- * visit method at each one.
+ * Visits children of the specified {...@link Iterable} pre-order
(parent
+ * first). Children are determined by calling {...@link
Iterable#iterator()}.
*
+ * @param <S>
+ * the type of object that will be visited, notice that
{...@code
+ * container} is not declared as {...@code Iterable<S>}
because it
+ * may return a generalization of {...@code S}
+ * @param <R>
+ * the type of object that should be returned from the
visitor,
+ * use {...@link Void} if no return value is needed
+ * @param container
+ * object whose children will be visited
* @param visitor
- * The visitor to call back to
- * @return The return value from a visitor which halted the traversal,
or
- * null if the entire traversal occurred
+ * the visitor
+ * @return return value from the {...@code visitor} or {...@code null}
if none
*/
- public static final <S, R> R visitChildren(Iterable<?> visitable, final
IVisitor<S, R> visitor)
+ public static final <S, R> R visitChildren(Iterable<?> container, final
IVisitor<S, R> visitor)
{
- return visitChildren(visitable, visitor, IVisitFilter.ANY);
+ return visitChildren(container, visitor, IVisitFilter.ANY);
}
/**
- * Visits any form components inside component if it is a container, or
- * component itself if it is itself a form component
- *
- * @param component
- * starting point of the traversal
- *
+ * Visits the specified object and any of its children using a
post-order
+ * (child first) traversal. Children are determined by calling
+ * {...@link Iterable#iterator()} if the object implements {...@link
Iterable}.
+ *
+ * @param <S>
+ * the type of object that will be visited, notice that
{...@code
+ * container} is not declared as {...@code Iterable<S>}
because it
+ * may return a generalization of {...@code S}
+ * @param <R>
+ * the type of object that should be returned from the
visitor,
+ * use {...@link Void} if no return value is needed
+ * @param root
+ * root object that will be visited
* @param visitor
- * The visitor to call
+ * the visitor
+ * @return return value from the {...@code visitor} or {...@code null}
if none
*/
- public static final <S, R> R visitComponentsPostOrder(Iterable<?>
component,
+ public static final <S, R> R visitComponentsPostOrder(S root,
final org.apache.wicket.util.visit.IVisitor<S, R>
visitor)
{
- return visitComponentsPostOrder(component, visitor,
IVisitFilter.ANY);
+ return visitComponentsPostOrder(root, visitor,
IVisitFilter.ANY);
}
/**
- * Visits any form components inside component if it is a container, or
- * component itself if it is itself a form component
- *
- * @param component
- * starting point of the traversal
- *
+ * Visits the specified object and any of its children using a
post-order
+ * (child first) traversal. Children are determined by calling
+ * {...@link Iterable#iterator()} if the object implements {...@link
Iterable}.
+ *
+ * @param <S>
+ * the type of object that will be visited, notice that
{...@code
+ * container} is not declared as {...@code Iterable<S>}
because it
+ * may return a generalization of {...@code S}
+ * @param <R>
+ * the type of object that should be returned from the
visitor,
+ * use {...@link Void} if no return value is needed
+ * @param root
+ * root object that will be visited
* @param visitor
- * The visitor to call
+ * the visitor
+ * @param filter
+ * filter used to limit the types of objects that will be
visited
+ * @return return value from the {...@code visitor} or {...@code null}
if none
*/
- public static final <S, R> R visitComponentsPostOrder(Object component,
+ public static final <S, R> R visitComponentsPostOrder(Object root,
final org.apache.wicket.util.visit.IVisitor<S, R>
visitor, IVisitFilter filter)
{
if (visitor == null)
@@ -115,16 +169,11 @@ public class Visits
}
Visit<R> visit = new Visit<R>();
- visitComponentsPostOrderHelper(component, visitor, filter,
visit);
+ visitComponentsPostOrderHelper(root, visitor, filter, visit);
return visit.getResult();
}
- /**
- *
- * @param component
- * @param visitor
- * @return Object
- */
+
private static final <S, R> void visitComponentsPostOrderHelper(Object
component,
final org.apache.wicket.util.visit.IVisitor<S, R>
visitor, IVisitFilter filter,
Visit<R> visit)
@@ -142,7 +191,7 @@ public class Visits
final Object child = iterator.next();
if (child instanceof Iterable<?>)
{
-
visitComponentsPostOrderHelper((Iterable<?>)child, visitor, filter,
+
visitComponentsPostOrderHelper(child, visitor, filter,
childTraversal);
if (childTraversal.isStopped())
{
