You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jspwiki.apache.org by aj...@apache.org on 2008/09/18 05:17:43 UTC
svn commit: r696555 [1/2] - in
/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH:
src/com/ecyrd/jspwiki/ src/com/ecyrd/jspwiki/action/
src/com/ecyrd/jspwiki/tags/ src/com/ecyrd/jspwiki/url/
tests/com/ecyrd/jspwiki/ui/stripes/
Author: ajaquith
Date: Wed Sep 17 20:17:43 2008
New Revision: 696555
URL: http://svn.apache.org/viewvc?rev=696555&view=rev
Log:
Javadoc tweaks.
Modified:
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/VariableManager.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiContext.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiEngine.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiPage.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/AbstractActionBean.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/GroupTypeConverter.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/HandlerInfo.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/NoneActionBean.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/PrincipalTypeConverter.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/RenameActionBean.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/UserProfileActionBean.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/ViewActionBean.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanContext.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanFactory.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiPageTypeConverter.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiRequestContext.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/package.html
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/tags/WikiTagBase.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/url/StripesURLConstructor.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/tests/com/ecyrd/jspwiki/ui/stripes/AbstractNode.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/tests/com/ecyrd/jspwiki/ui/stripes/Node.java
incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/tests/com/ecyrd/jspwiki/ui/stripes/Tag.java
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/VariableManager.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/VariableManager.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/VariableManager.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/VariableManager.java Wed Sep 17 20:17:43 2008
@@ -174,7 +174,7 @@
}
/**
- * Returns the value of a named variable. See {@link #getValue(WikiContext, String)}.
+ * Returns the value of a named variable. See {@link #getValue(WikiActionBean, String)}.
* The only difference is that this method does not throw an exception, but it
* returns the given default value instead.
*
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiContext.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiContext.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiContext.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiContext.java Wed Sep 17 20:17:43 2008
@@ -488,7 +488,7 @@
/**
* Checks whether the current user has access to this wiki context,
- * by obtaining the required Permission ({@link #requiredPermission()})
+ * by obtaining the required Permission (see {@link HandlerInfo#getPermission(WikiActionBean)})
* and delegating the access check to
* {@link com.ecyrd.jspwiki.auth.AuthorizationManager#checkPermission(WikiSession, Permission)}.
* If the user is allowed, this method returns <code>true</code>;
@@ -510,7 +510,7 @@
/**
* Checks whether the current user has access to this wiki context (and
- * optionally redirects if not), by obtaining the required Permission ({@link #requiredPermission()})
+ * optionally redirects if not), by obtaining the required Permission (see {@link HandlerInfo#getPermission(WikiActionBean)})
* and delegating the access check to
* {@link com.ecyrd.jspwiki.auth.AuthorizationManager#checkPermission(WikiSession, Permission)}.
* If the user is allowed, this method returns <code>true</code>;
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiEngine.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiEngine.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiEngine.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiEngine.java Wed Sep 17 20:17:43 2008
@@ -1048,7 +1048,7 @@
* <p>If the page is a special page, then returns a direct URL
* to that page. Otherwise returns <code>null</code>.
* This method delegates requests to
- * {@link com.ecyrd.jspwiki.ui.CommandResolver#getSpecialPageReference(String)}.
+ * {@link com.ecyrd.jspwiki.action.WikiActionBeanFactory#getSpecialPageReference(String)}.
* </p>
* <p>
* Special pages are defined in jspwiki.properties using the jspwiki.specialPage
@@ -1232,7 +1232,7 @@
* Returns the correct page name, or null, if no such
* page can be found. Aliases are considered. This
* method simply delegates to
- * {@link com.ecyrd.jspwiki.ui.WikiActionBeanFactory#getFinalPageName(String)}.
+ * {@link com.ecyrd.jspwiki.action.WikiActionBeanFactory#getFinalPageName(String)}.
* @since 2.0
* @param page Page name.
* @return The rewritten page name, or null, if the page does not exist.
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiPage.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiPage.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiPage.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/WikiPage.java Wed Sep 17 20:17:43 2008
@@ -97,7 +97,7 @@
* Returns the full, qualified, name of the WikiPage that includes the wiki name.
* Used by the {@link com.ecyrd.jspwiki.action.HandlerInfo} class and
* {@link com.ecyrd.jspwiki.action.HandlerPermission} annotations.
- * @return
+ * @return the qualified page name, for example <code>mywiki:Main</code>
*/
public String getQualifiedName()
{
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/AbstractActionBean.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/AbstractActionBean.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/AbstractActionBean.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/AbstractActionBean.java Wed Sep 17 20:17:43 2008
@@ -15,7 +15,7 @@
/**
* <p>
* Abstract ActionBean superclass for all wiki actions, such as page actions ({@link com.ecyrd.jspwiki.WikiContext}
- * and subclasses), group actions (e.g., {@link ViewGroupActionBean}), user
+ * and subclasses), group actions (e.g., {@link GroupActionBean}), user
* actions (e.g., {@link UserPreferencesActionBean}) and others.
* </p>
*
@@ -92,7 +92,7 @@
* this ActionBean does not have a a current event handler assigned, or if
* the event handler method does not contain the WikiRequestContext
* annotation, this method will return
- * {@link ecyrd.jspwiki.WikiContext#NONE}.
+ * {@link com.ecyrd.jspwiki.WikiContext#NONE}.
*/
public String getRequestContext()
{
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/GroupTypeConverter.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/GroupTypeConverter.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/GroupTypeConverter.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/GroupTypeConverter.java Wed Sep 17 20:17:43 2008
@@ -30,7 +30,8 @@
/**
* Stripes type converter that converts a Group name, expressed as a String,
* into an {@link com.ecyrd.jspwiki.auth.authorize.Group} object. This converter
- * is looked up and returned by {@link WikiTypeConverterFactory} for HTTP
+ * is looked up and returned by the Stripes
+ * {@link net.sourceforge.stripes.validation.TypeConverterFactory} for HTTP
* request parameters that need to be bound to ActionBean properties of type
* Group. Stripes executes this TypeConverter during the
* {@link net.sourceforge.stripes.controller.LifecycleStage#BindingAndValidation}
@@ -51,33 +52,30 @@
* a message key of <code>pageNotFound</code> and a single parameter
* (equal to the value passed for <code>groupName</code>).
*
- * @param groupName
- * the name of the WikiPage to retrieve
- * @param targetType
- * the type to return, which will always be of type
+ * @param groupName the name of the WikiPage to retrieve
+ * @param targetType the type to return, which will always be of type
* {@link com.ecyrd.jspwiki.auth.authorize.Group}
- * @param errors
- * the current Collection of validation errors for this field
+ * @param errors the current Collection of validation errors for this field
* @return the resolved Group
*/
- public Group convert(String groupName, Class<? extends Group> targetType, Collection<ValidationError> errors)
+ public Group convert( String groupName, Class<? extends Group> targetType, Collection<ValidationError> errors )
{
- WikiRuntimeConfiguration config = (WikiRuntimeConfiguration)StripesFilter.getConfiguration();
+ WikiRuntimeConfiguration config = (WikiRuntimeConfiguration) StripesFilter.getConfiguration();
WikiEngine engine = config.getEngine();
GroupManager mgr = engine.getGroupManager();
Group group = null;
try
{
- group = mgr.getGroup(groupName);
+ group = mgr.getGroup( groupName );
}
- catch (NoSuchPrincipalException e)
+ catch( NoSuchPrincipalException e )
{
- errors.add(new LocalizableError("groupNotFound", groupName));
+ errors.add( new LocalizableError( "groupNotFound", groupName ) );
}
return group;
}
- public void setLocale(Locale locale)
+ public void setLocale( Locale locale )
{
};
}
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/HandlerInfo.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/HandlerInfo.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/HandlerInfo.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/HandlerInfo.java Wed Sep 17 20:17:43 2008
@@ -31,7 +31,7 @@
private static final Map<Class<? extends WikiActionBean>, Map<Method, HandlerInfo>> CACHED_INFO = new HashMap<Class<? extends WikiActionBean>, Map<Method, HandlerInfo>>();
private final Class<? extends WikiActionBean> m_beanClass;
-
+
private final Method m_handlerMethod;
private final Class<? extends Permission> m_permissionClass;
@@ -58,11 +58,12 @@
* the name of the wiki request context by looking for a
* {@link WikiRequestContext} annotation.
*
- * @param beanClass the ActionBean implementation for which event information should be created
+ * @param beanClass the ActionBean implementation for which event
+ * information should be created
* @param method the method that denotes the event handler
* @param eventHandler the name of the event the method handles
*/
- private HandlerInfo( Class<? extends WikiActionBean>beanClass, Method method, String eventHandler )
+ private HandlerInfo( Class<? extends WikiActionBean> beanClass, Method method, String eventHandler )
{
// Determine the permission annotated by @HandlerPermission (if
// supplied)
@@ -101,7 +102,8 @@
}
if( actions != null && actions.startsWith( "${" ) && actions.endsWith( "}" ) )
{
- m_permissionActionExpression = PropertyExpression.getExpression( m_permissionTarget.substring( 2, m_permissionTarget.length() - 1 ) );
+ m_permissionActionExpression = PropertyExpression.getExpression( m_permissionTarget.substring( 2, m_permissionTarget
+ .length() - 1 ) );
}
else
{
@@ -223,7 +225,7 @@
{
return eventInfoCollection;
}
-
+
// Not there, eh? Ok, let's figure it out.
eventInfoCollection = new HashMap<Method, HandlerInfo>();
CACHED_INFO.put( beanClass, eventInfoCollection );
@@ -245,18 +247,20 @@
}
/**
- * Returns the WikiActionBean class that is the parent of the event method used to
- * instantiate the HandlerInfo object.
- * @return
+ * Returns the WikiActionBean class that is the parent of the event method
+ * used to instantiate the HandlerInfo object.
+ *
+ * @return the WikiActionBean class
*/
public Class<? extends WikiActionBean> getActionBeanClass()
{
return m_beanClass;
}
-
+
/**
- * Returns the Method associated with the event handler. This is the same method
- * used to instantiate the HandlerInfo object in {@link #HandlerInfo(Method, String)}.
+ * Returns the Method associated with the event handler. This is the same
+ * method used to instantiate the HandlerInfo object in the private
+ * constructor {@link #HandlerInfo(Class, Method, String)}.
*
* @return the method
*/
@@ -312,7 +316,7 @@
* {@link IllegalArgumentException}.
* </p>
*
- * @return
+ * @return the wiki request context
*/
public String getRequestContext()
{
@@ -320,11 +324,12 @@
}
/**
- * Returns the Permission required to execute the method in the context of the supplied
- * WikiActionBean, based on its {@link HandlerPermission} annotation.
- * Any EL expressions found in the annotated target or actions are evaluated.
- * Note that this method returns <code>null</code> if no Permission is required
- * to execute this method, and <em>callers should check for nulls</code>.
+ * Returns the Permission required to execute the method in the context of
+ * the supplied WikiActionBean, based on its {@link HandlerPermission}
+ * annotation. Any EL expressions found in the annotated target or actions
+ * are evaluated. Note that this method returns <code>null</code> if no
+ * Permission is required to execute this method, and
+ * <em>callers should check for nulls</code>.
*
* @param actionBean the ActionBean that will be used as the base for any EL
* expressions
@@ -334,11 +339,11 @@
*/
public Permission getPermission( WikiActionBean actionBean ) throws ELException
{
- if ( m_permissionClass == null )
+ if( m_permissionClass == null )
{
return null;
}
-
+
// Get the target class, target and actions
boolean hasOneParameter = m_permissionActions == null;
String target = m_permissionTarget;
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/NoneActionBean.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/NoneActionBean.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/NoneActionBean.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/NoneActionBean.java Wed Sep 17 20:17:43 2008
@@ -9,11 +9,10 @@
/**
* Represents a dummy WikiContext that doesn't bind to a URL, and doesn't
* contain any embedded logic. When the NoneActionBean class is passed as a
- * parameter to {@link WikiActionBeanContext#getURL(Class, String)}, for
- * example, the resulting URL does not prepend anything before the page.
+ * parameter to a method that produces an URL, the resulting URL does not
+ * prepend anything before the page.
*
* @author Andrew Jaquith
- *
*/
public class NoneActionBean extends WikiContext
{
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/PrincipalTypeConverter.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/PrincipalTypeConverter.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/PrincipalTypeConverter.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/PrincipalTypeConverter.java Wed Sep 17 20:17:43 2008
@@ -24,11 +24,12 @@
import com.ecyrd.jspwiki.auth.WikiPrincipal;
/**
- * Stripes type converter that converts a Principal name, expressed as a String, into an
- * {@link com.ecyrd.jspwiki.auth.WikiPrincipal} object. This converter is looked up
- * and returned by {@link WikiTypeConverterFactory} for HTTP request parameters
- * that need to be bound to ActionBean properties of type Principal. Stripes
- * executes this TypeConverter during the
+ * Stripes type converter that converts a Principal name, expressed as a String,
+ * into an {@link com.ecyrd.jspwiki.auth.WikiPrincipal} object. This converter
+ * is looked up and returned by the Stripes
+ * {@link net.sourceforge.stripes.validation.TypeConverterFactory} for HTTP
+ * request parameters that need to be bound to ActionBean properties of type
+ * Principal. Stripes executes this TypeConverter during the
* {@link net.sourceforge.stripes.controller.LifecycleStage#BindingAndValidation}
* stage of request processing.
*
@@ -42,21 +43,18 @@
* {@link com.ecyrd.jspwiki.auth.WikiPrincipal} object. This method will not
* ever return errors.
*
- * @param principalName
- * the name of the Principal to create
- * @param targetType
- * the type to return, which will always be of type
+ * @param principalName the name of the Principal to create
+ * @param targetType the type to return, which will always be of type
* {@link java.security.Principal}
- * @param errors
- * the current Collection of validation errors for this field
+ * @param errors the current Collection of validation errors for this field
* @return the
*/
- public Principal convert(String principalName, Class<? extends Principal> targetType, Collection<ValidationError> errors)
+ public Principal convert( String principalName, Class<? extends Principal> targetType, Collection<ValidationError> errors )
{
- return new WikiPrincipal(principalName);
+ return new WikiPrincipal( principalName );
}
- public void setLocale(Locale locale)
+ public void setLocale( Locale locale )
{
};
}
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/RenameActionBean.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/RenameActionBean.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/RenameActionBean.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/RenameActionBean.java Wed Sep 17 20:17:43 2008
@@ -26,7 +26,7 @@
* <h3>Request parameters</h3>
* <ul>
* <li><code>page</code> - the existing page name. Returned by
- * {@ link #getPage()}
+ * {@link #getPage()}
* <li><code>renameTo</code> - the proposed new name for the page. This
* parameter is required, and it is a validation error if not</li>
* <li><code>changeReferences</code> - whether to change all referring pages'
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/UserProfileActionBean.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/UserProfileActionBean.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/UserProfileActionBean.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/UserProfileActionBean.java Wed Sep 17 20:17:43 2008
@@ -78,7 +78,8 @@
* to the <code>ApprovalRequiredForUserProfiles</code> will be returned.
* Other validation errors will cause redirection back to the profile tab.
*
- * @return
+ * @return a Resolution if the user is redirected for approvals or because
+ * of errors, or <code>null</code> otherwise
*/
@HandlesEvent( "save" )
@HandlerPermission( permissionClass = WikiPermission.class, target = "${engine.applicationName}", actions = WikiPermission.EDIT_PROFILE_ACTION )
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/ViewActionBean.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/ViewActionBean.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/ViewActionBean.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/ViewActionBean.java Wed Sep 17 20:17:43 2008
@@ -31,7 +31,7 @@
}
/**
- * <p>After the binding and validation {@link LifecycleStage.BindingAndValidation}
+ * <p>After the binding and validation {@link LifecycleStage#BindingAndValidation}
* lifecycle stage executes, this method determines whether the
* page name specified in the request is actually a special page and
* redirects the user if needed. If no page was specified in the request, this method
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanContext.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanContext.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanContext.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanContext.java Wed Sep 17 20:17:43 2008
@@ -102,8 +102,8 @@
* Adds a supplied ActionBean to "flash scope" so that it can be used by the next
* HttpRequest. When this method is called, the ActionBean is stashed in the
* request and the flash scope as attributes. For both, the bean is stored
- * under names {@link WikiActionBeanFactory.ATTR_ACTIONBEAN}
- * and {@link WikiTagBase.ATTR_CONTEXT}. This method assumes that the
+ * under names {@link WikiActionBeanFactory#ATTR_ACTIONBEAN}
+ * and {@link WikiTagBase#ATTR_CONTEXT}. This method assumes that the
* method {@link #setRequest(HttpServletRequest)} has been previously called.
* @param actionBean the action bean to add
* @throws IllegalStateException if the request object has not been previously set
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanFactory.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanFactory.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanFactory.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiActionBeanFactory.java Wed Sep 17 20:17:43 2008
@@ -28,37 +28,11 @@
/**
* <p>
- * Class that resolves special pages and JSPs on behalf of a WikiEngine.
- * WikiActionBeanResolver will automatically resolve page names with
- * singular/plural variants. It can also detect the correct Command based on
- * parameters supplied in an HTTP request, or due to the JSP being accessed.
- * </p>
- * <p>
- * <p>
- * WikiActionBeanResolver's static {@link #findCommand(String)} method is the
- * simplest method; it looks up and returns the Command matching a supplied wiki
- * context. For example, looking up the request context <code>view</code>
- * returns {@link PageCommand#VIEW}. Use this method to obtain static Command
- * instances that aren't targeted at a particular page or group.
- * </p>
- * <p>
- * For more complex lookups in which the caller supplies an HTTP request,
- * {@link #findCommand(HttpServletRequest, String)} will look up and return the
- * correct Command. The String parameter <code>defaultContext</code> supplies
- * the request context to use if it cannot be detected. However, note that the
- * default wiki context may be over-ridden if the request was for a "special
- * page."
- * </p>
- * <p>
- * For example, suppose the WikiEngine's properties specify a special page
- * called <code>UserPrefs</code> that redirects to
- * <code>UserPreferences.jsp</code>. The ordinary lookup method
- * {@linkplain #findCommand(String)} using a supplied context <code>view</code>
- * would return {@link PageCommand#VIEW}. But the
- * {@linkplain #findCommand(HttpServletRequest, String)} method, when passed the
- * same context (<code>view</code>) and an HTTP request containing the page
- * parameter value <code>UserPrefs</code>, will instead return
- * {@link WikiCommand#PREFS}.
+ * Class that looks up {@link WikiActionBean}s, and resolves special pages and
+ * JSPs on behalf of a WikiEngine. WikiActionBeanResolver will automatically
+ * resolve page names with singular/plural variants. It can also detect the
+ * correct WikiActionBean based on parameters supplied in an HTTP request, or
+ * due to the JSP being accessed.
* </p>
*
* @author Andrew Jaquith
@@ -83,7 +57,7 @@
* WikiInterceptor.
*/
public static final String ATTR_WIKISESSION = "wikiSession";
-
+
private static final Logger log = Logger.getLogger( WikiActionBeanFactory.class );
private static final long serialVersionUID = 1L;
@@ -94,7 +68,10 @@
/** Default list of packages to search for WikiActionBean implementations. */
private static final String DEFAULT_ACTIONBEAN_PACKAGES = "com.ecyrd.jspwiki.action";
- /** Property in jspwiki.properties that specifies packages to search for WikiActionBean implementations. */
+ /**
+ * Property in jspwiki.properties that specifies packages to search for
+ * WikiActionBean implementations.
+ */
private static final String PROPS_ACTIONBEAN_PACKAGES = "jspwiki.actionBean.packages";
/** Private map with JSPs as keys, Resolutions as values */
@@ -111,7 +88,9 @@
private final Map<String, HandlerInfo> m_contextMap = new HashMap<String, HandlerInfo>();
/**
- * Initializes the internal map that matches wiki request contexts with HandlerInfo objects.
+ * Initializes the internal map that matches wiki request contexts with
+ * HandlerInfo objects.
+ *
* @param properties
*/
private void initRequestContextMap( Properties properties )
@@ -119,7 +98,7 @@
// Look up all classes that are WikiActionBeans.
String beanPackagesProp = properties.getProperty( PROPS_ACTIONBEAN_PACKAGES, DEFAULT_ACTIONBEAN_PACKAGES ).trim();
String[] beanPackages = beanPackagesProp.split( "," );
- Set<Class<? extends WikiActionBean>> beanClasses = findBeanClasses( beanPackages);
+ Set<Class<? extends WikiActionBean>> beanClasses = findBeanClasses( beanPackages );
// Stash the contexts and corresponding classes into a Map.
for( Class<? extends WikiActionBean> beanClass : beanClasses )
@@ -146,8 +125,11 @@
}
/**
- * Searches a set of named packages for WikiActionBean implementations, and returns any it finds.
- * @param beanPackages the packages to search on the current classpath, separated by commas
+ * Searches a set of named packages for WikiActionBean implementations, and
+ * returns any it finds.
+ *
+ * @param beanPackages the packages to search on the current classpath,
+ * separated by commas
* @return the discovered classes
*/
private Set<Class<? extends WikiActionBean>> findBeanClasses( String[] beanPackages )
@@ -206,9 +188,10 @@
}
/**
- * Skims through a supplied set of Properties and looks for anything with the "special page"
- * prefix, and creates Stripes {@link net.sourceforge.stripes.action.RedirectResolution} objects
- * for any that are found.
+ * Skims through a supplied set of Properties and looks for anything with
+ * the "special page" prefix, and creates Stripes
+ * {@link net.sourceforge.stripes.action.RedirectResolution} objects for any
+ * that are found.
*/
private void initSpecialPageRedirects( Properties properties )
{
@@ -329,11 +312,11 @@
* response with it, and incorporates the correct WikiPage into the bean if
* required. This method will determine what page the user requested by
* delegating to
- * {@link #extractPageFromParameter(String, HttpServletRequest)}.
+ * {@link #extractPageFromParameter(HttpServletRequest)}.
* </p>
* <p>
* This method will <em>always</em>return a WikiActionBean that is
- * properly instantiated. It will also create a new {@WikiActionBeanContext}
+ * properly instantiated. It will also create a new {@link WikiActionBeanContext}
* and associate it with the action bean. The supplied request and response
* objects will be associated with the WikiActionBeanContext. The
* <code>beanClass</code>is required. If either the <code>request</code>
@@ -503,7 +486,8 @@
response = new MockHttpServletResponse();
}
- // Create the WikiActionBeanContext and set all of its relevant properties
+ // Create the WikiActionBeanContext and set all of its relevant
+ // properties
WikiActionBeanContext actionBeanContext = new WikiActionBeanContext();
bean.setContext( actionBeanContext );
actionBeanContext.setRequest( request );
@@ -599,27 +583,27 @@
/**
* Returns the WikiActionBean associated with the current
* {@link javax.servlet.http.HttpServletRequest}. The ActionBean will be
- * retrieved from attribute {@link WikiInterceptor#ATTR_ACTIONBEAN}. If
- * an ActionBean is not found under this name, the standard Stripes attribute
+ * retrieved from attribute {@link WikiActionBeanFactory#ATTR_ACTIONBEAN}. If an
+ * ActionBean is not found under this name, the standard Stripes attribute
* {@link net.sourceforge.stripes.controller.StripesConstants#REQ_ATTR_ACTION_BEAN}
* will be attempted.
*
- * @param pageContext the
+ * @param request the HTTP request
* @return the WikiActionBean
* @throws IllegalStateException if the WikiActionBean was not found in the
- * request scope
+ * request scope
*/
public static WikiActionBean findActionBean( ServletRequest request )
{
WikiActionBean bean = (WikiActionBean) request.getAttribute( ATTR_ACTIONBEAN );
- if ( bean == null )
+ if( bean == null )
{
- log.debug( "WikiActionBean not found under request attribute '" + ATTR_ACTIONBEAN +
- "'; trying standard Stripes attribute '" + StripesConstants.REQ_ATTR_ACTION_BEAN + "'." );
- bean = (WikiActionBean) request.getAttribute( StripesConstants.REQ_ATTR_ACTION_BEAN );
+ log.debug( "WikiActionBean not found under request attribute '" + ATTR_ACTIONBEAN
+ + "'; trying standard Stripes attribute '" + StripesConstants.REQ_ATTR_ACTION_BEAN + "'." );
+ bean = (WikiActionBean) request.getAttribute( StripesConstants.REQ_ATTR_ACTION_BEAN );
}
-
- if ( bean == null )
+
+ if( bean == null )
{
throw new IllegalStateException( "WikiActionBean not found in request! Something failed to stash it..." );
}
@@ -628,10 +612,10 @@
/**
* <p>
- * Saves the supplied WikiActionBean and its associated WikiPage as
- * in request scope. The action bean is saved as an
- * attribute named {@link WikiInterceptor#ATTR_ACTIONBEAN}. If the action
- * bean was also a WikiContext instance, it is saved as an attribute named
+ * Saves the supplied WikiActionBean and its associated WikiPage as in
+ * request scope. The action bean is saved as an attribute named
+ * {@link #ATTR_ACTIONBEAN}. If the action bean was also a
+ * WikiContext instance, it is saved as an attribute named
* {@link com.ecyrd.jspwiki.tags.WikiTagBase#ATTR_CONTEXT}. Among other
* things, by saving these items as attributes, they can be accessed via JSP
* Expression Language variables, in this case
@@ -655,11 +639,11 @@
// used later as ${wikiEngine} in EL markup)
WikiEngine engine = actionBean.getEngine();
request.setAttribute( ATTR_WIKIENGINE, engine );
-
+
// Stash the WikiSession as a request attribute
WikiSession wikiSession = SessionMonitor.getInstance( engine ).find( request.getSession() );
request.setAttribute( ATTR_WIKISESSION, wikiSession );
-
+
// Stash the WikiActionBean
request.setAttribute( ATTR_ACTIONBEAN, actionBean );
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiPageTypeConverter.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiPageTypeConverter.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiPageTypeConverter.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiPageTypeConverter.java Wed Sep 17 20:17:43 2008
@@ -28,11 +28,12 @@
import com.ecyrd.jspwiki.providers.ProviderException;
/**
- * Stripes type converter that converts a WikiPage name, expressed as a String, into an
- * {@link com.ecyrd.jspwiki.WikiPage} object. This converter is looked up
- * and returned by {@link WikiTypeConverterFactory} for HTTP request parameters
- * that need to be bound to ActionBean properties of type WikiPage. Stripes
- * executes this TypeConverter during the
+ * Stripes type converter that converts a WikiPage name, expressed as a String,
+ * into an {@link com.ecyrd.jspwiki.WikiPage} object. This converter is looked
+ * up and returned by the Stripes
+ * {@link net.sourceforge.stripes.validation.TypeConverterFactory} for HTTP
+ * request parameters that need to be bound to ActionBean properties of type
+ * WikiPage. Stripes executes this TypeConverter during the
* {@link net.sourceforge.stripes.controller.LifecycleStage#BindingAndValidation}
* stage of request processing.
*
@@ -50,39 +51,36 @@
* will have a message key of <code>pageNotFound</code> and a single
* parameter (equal to the value passed for <code>pageName</code>).
*
- * @param pageName
- * the name of the WikiPage to retrieve
- * @param targetType
- * the type to return, which will always be of type
+ * @param pageName the name of the WikiPage to retrieve
+ * @param targetType the type to return, which will always be of type
* {@link com.ecyrd.jspwiki.WikiPage}
- * @param errors
- * the current Collection of validation errors for this field
+ * @param errors the current Collection of validation errors for this field
* @return the
*/
- public WikiPage convert(String pageName, Class<? extends WikiPage> targetType, Collection<ValidationError> errors)
+ public WikiPage convert( String pageName, Class<? extends WikiPage> targetType, Collection<ValidationError> errors )
{
- WikiRuntimeConfiguration config = (WikiRuntimeConfiguration)StripesFilter.getConfiguration();
+ WikiRuntimeConfiguration config = (WikiRuntimeConfiguration) StripesFilter.getConfiguration();
WikiEngine engine = config.getEngine();
- WikiPage page = engine.getPage(pageName);
- if (page == null)
+ WikiPage page = engine.getPage( pageName );
+ if( page == null )
{
try
{
- String finalName = engine.getWikiActionBeanFactory().getFinalPageName(pageName);
- if (finalName == null || engine.getPage(finalName) == null)
+ String finalName = engine.getWikiActionBeanFactory().getFinalPageName( pageName );
+ if( finalName == null || engine.getPage( finalName ) == null )
{
- errors.add(new LocalizableError("pageNotFound", pageName));
+ errors.add( new LocalizableError( "pageNotFound", pageName ) );
}
}
- catch (ProviderException e)
+ catch( ProviderException e )
{
- errors.add(new SimpleError(e.getMessage()));
+ errors.add( new SimpleError( e.getMessage() ) );
}
}
return page;
}
- public void setLocale(Locale locale)
+ public void setLocale( Locale locale )
{
}
}
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiRequestContext.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiRequestContext.java?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiRequestContext.java (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/WikiRequestContext.java Wed Sep 17 20:17:43 2008
@@ -13,7 +13,7 @@
* the WikiRequestContext annotation must also have a {@link HandlesEvent}
* annotation. The values returned by both annotations do not need to match.
*
- * @see {@link HandlerInfo#getRequestContext(Class, String)}.
+ * @see HandlerInfo#getRequestContext()
* @author Andrew Jaquith
*/
@Retention( RetentionPolicy.RUNTIME )
Modified: incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/package.html
URL: http://svn.apache.org/viewvc/incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/package.html?rev=696555&r1=696554&r2=696555&view=diff
==============================================================================
--- incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/package.html (original)
+++ incubator/jspwiki/branches/JSPWIKI_2_9_STRIPES_BRANCH/src/com/ecyrd/jspwiki/action/package.html Wed Sep 17 20:17:43 2008
@@ -1,32 +1,66 @@
<html>
<body>
-<p>Provides processing logic used by JSPs, using ActionBeans as used by the <a href="http://mc4j.org/confluence/display/stripes/Home">Stripes MVC framework</a>. In JSPWiki 3.0, the old JSP layer has been completely overhauled and simplified.</p>
+<p>Provides processing logic used by JSPs, using ActionBeans as used
+by the <a href="http://mc4j.org/confluence/display/stripes/Home">Stripes
+MVC framework</a>. In JSPWiki 3.0, the old JSP layer has been completely
+overhauled and simplified.</p>
<h3>Overview of Stripes Features Used by JSPWiki 3.0</h3>
-<p>The Stripes MVC framework enforces separation of presentation and page markup (JSPs) from processing logic.
-By "presentation" we mean anything that generates valid HTML or related markup, like cascading stylesheets. By "processing logic" we mean things like:</p>
+<p>The Stripes MVC framework enforces separation of presentation and
+page markup (JSPs) from processing logic. By "presentation" we mean
+anything that generates valid HTML or related markup, like cascading
+stylesheets. By "processing logic" we mean things like:</p>
<ul>
- <li>Creating wiki contexts</li>
- <li>Extracting request parameters</li>
- <li>Validating submitted form values</li>
- <li>Looking, changing, or saving domain objects (<em>e.g.</em>, WikiPages, Groups, UserProfiles)</li>
- <li>Request flow processing (<em>e.g.</em>, redirects)</li>
- <li>Localization of resources</li>
+ <li>Creating wiki contexts</li>
+ <li>Extracting request parameters</li>
+ <li>Validating submitted form values</li>
+ <li>Looking, changing, or saving domain objects (<em>e.g.</em>,
+ WikiPages, Groups, UserProfiles)</li>
+ <li>Request flow processing (<em>e.g.</em>, redirects)</li>
+ <li>Localization of resources</li>
</ul>
-<p>In versions of JSPWiki prior to 3.0, JSPs did most of these things. In 3.0, JSPs do very little, and instead delegate most of the heavy lifting to the Stripes framework and to special JavaBeans called <a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/ActionBean.html">ActionBeans</a>. These ActionBeans contain getters/setters that are used to store parameter values extracted from the HTTP request, and additional methods called <em>events</em> that correspond to the values that old-style JSPWiki templates stored in their "action" form parameters. In JSPWiki 3.0, we provide a subclass called <a href="../ui/WikiActionBean.html">WikiActionBean</a> includes accessors for things needed by JSPWiki, such as a {@linkplain com.ecyrd.jspwiki.action.WikiActionBean#getEngine()} method that returns the WikiEngine, and {@linkplain com.ecyrd.jspwiki.action.WikiActionBean#getWikiSession()} that returns the user's WikiSession.</p>
+<p>In versions of JSPWiki prior to 3.0, JSPs did most of these
+things. In 3.0, JSPs do very little, and instead delegate most of the
+heavy lifting to the Stripes framework and to special JavaBeans called <a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/ActionBean.html">ActionBeans</a>.
+These ActionBeans contain getters/setters that are used to store
+parameter values extracted from the HTTP request, and additional methods
+called <em>events</em> that correspond to the values that old-style
+JSPWiki templates stored in their "action" form parameters. In JSPWiki
+3.0, we provide a subclass called <a href="../ui/WikiActionBean.html">WikiActionBean</a>
+includes accessors for things needed by JSPWiki, such as a {@linkplain
+com.ecyrd.jspwiki.action.WikiActionBean#getEngine()} method that returns
+the WikiEngine, and {@linkplain
+com.ecyrd.jspwiki.action.WikiActionBean#getWikiSession()} that returns
+the user's WikiSession.</p>
<h3>Request parameter binding</h3>
-<p>Stripes includes a very cool, easy-to-understand technique for <a href="http://mc4j.org/confluence/display/stripes/Quick+Start+Guide">automatically populating WikiActionBeans</a> with submitted request parameters. Basically it boils down to this: if you have a request parameter that you want to map to a bean value, just create getters and setters that have same field name. Stripes will detect which parameters correspond to ActionBean fields, and will set the values automatically. For example, consider JSPWiki 2.<em>x</em>'s <code>Edit.jsp</code> that edits wiki pages. Page-related parameters supplied to this JSP include:</p>
+<p>Stripes includes a very cool, easy-to-understand technique for <a
+ href="http://mc4j.org/confluence/display/stripes/Quick+Start+Guide">automatically
+populating WikiActionBeans</a> with submitted request parameters. Basically
+it boils down to this: if you have a request parameter that you want to
+map to a bean value, just create getters and setters that have same
+field name. Stripes will detect which parameters correspond to
+ActionBean fields, and will set the values automatically. For example,
+consider JSPWiki 2.<em>x</em>'s <code>Edit.jsp</code> that edits wiki
+pages. Page-related parameters supplied to this JSP include:</p>
<ul>
- <li><code>changenote</code></li>
- <li><code>author</code></li>
- <li><code>edittime</code></li>
- <li><code>link</code></li>
- <li><code>htmlPageText</code></li>
-</ul>
+ <li><code>changenote</code></li>
+ <li><code>author</code></li>
+ <li><code>edittime</code></li>
+ <li><code>link</code></li>
+ <li><code>htmlPageText</code></li>
+</ul>
-<p>These are parameters we need in order to save the wiki page correctly. Some of them are mandatory, and some aren't. In JSPWiki 3.0, responsibility for parsing and validating all of these parameters reside with Stripes. What happens is that when <code>Edit.jsp</code> is rendered, Stripes instantiates a corresponding WikiActionBean subclass called {@link com.ecyrd.jspwiki.action.EditActionBean} and automatically calls the correct accessors. In this example, the getters/setters look like this:</p>
+<p>These are parameters we need in order to save the wiki page
+correctly. Some of them are mandatory, and some aren't. In JSPWiki 3.0,
+responsibility for parsing and validating all of these parameters reside
+with Stripes. What happens is that when <code>Edit.jsp</code> is
+rendered, Stripes instantiates a corresponding WikiActionBean subclass
+called {@link com.ecyrd.jspwiki.action.EditActionBean} and automatically
+calls the correct accessors. In this example, the getters/setters look
+like this:</p>
<pre>public String getChangenote() { ... }
public void setChangenote(String note) { ... }
@@ -43,51 +77,147 @@
public String getHtmlPageText() { ... }
public void setHtmlPageText(String text) { ... }</pre>
-<p>As you can see, there is a straight 1-to-1 binding between the getter/setter field names (<em>e.g.</em>, <code>getChangenote</code>/<code>setChangenote</code>) and request parameters (<code>changenote</code>). So, when the URL <code>Edit.jsp?changenote=Finished</code> is requested, Stripes invokes ViewActionBean's <code>setChangenote</code> method and passes the String "Finished". This is all done completely automatically -- there is no code to write.</p>
-
-<blockquote><em><strong>Guideline #1 for JSPWiki developers</strong>: processing code that extracts request parameters (that would have ordinarily gone into top-level JSPs) should </em>always<em> be moved into WikiActionBean getter and setter fields. For example, if the parameter <code>foo</code> is needed, add methods <code>setFoo</code> and <code>getFoo</code> to the ActionBean). The field types can be <a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/validation/TypeConverter.html">any type that Stripes knows how to convert</a>, such as <code>int</code>, <code>long</code>, <code>Date</code>, <code>String</code>, <code>BigDecimal</code> and others, or JSPWiki-specific types we've built converters for: WikiPage (via {@link com.ecyrd.jspwiki.ui.WikiPageTypeConverter}), Group (via {@link com.ecyrd.jspwiki.ui.GroupTypeConverter}, and Principal (via {@link com.ecyrd.jspwiki.ui.PrincipalTypeConverter}).</em></blockquote>
+<p>As you can see, there is a straight 1-to-1 binding between the
+getter/setter field names (<em>e.g.</em>, <code>getChangenote</code>/<code>setChangenote</code>)
+and request parameters (<code>changenote</code>). So, when the URL <code>Edit.jsp?changenote=Finished</code>
+is requested, Stripes invokes ViewActionBean's <code>setChangenote</code>
+method and passes the String "Finished". This is all done completely
+automatically -- there is no code to write.</p>
+
+<blockquote><em><strong>Guideline #1 for
+JSPWiki developers</strong>: processing code that extracts request parameters
+(that would have ordinarily gone into top-level JSPs) should </em>always<em>
+be moved into WikiActionBean getter and setter fields. For example, if
+the parameter <code>foo</code> is needed, add methods <code>setFoo</code>
+and <code>getFoo</code> to the ActionBean). The field types can be <a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/validation/TypeConverter.html">any
+type that Stripes knows how to convert</a>, such as <code>int</code>, <code>long</code>,
+<code>Date</code>, <code>String</code>, <code>BigDecimal</code> and
+others, or JSPWiki-specific types we've built converters for: WikiPage
+(via {@link com.ecyrd.jspwiki.action.WikiPageTypeConverter}), Group (via
+{@link com.ecyrd.jspwiki.action.GroupTypeConverter}, and Principal (via
+{@link com.ecyrd.jspwiki.action.PrincipalTypeConverter}).</em></blockquote>
<h3>Bindings ActionBeans to URLs</h3>
-<p>All of this sounds great, but all of this assumes that somebody (us, Stripes, or God) knows how to bind the JSP <code>Edit.jsp</code> to our magic EditActionBean. How do we do this? Binding is done in two ways: manually in our JSPs by telling Stripes what bean to use, and automatically by Stripes when its servlet filter (StripesFilter) detects URLs that end in <code>.action</code>. JSPWiki uses both methods.</p>
+<p>All of this sounds great, but all of this assumes that somebody
+(us, Stripes, or God) knows how to bind the JSP <code>Edit.jsp</code> to
+our magic EditActionBean. How do we do this? Binding is done in two
+ways: manually in our JSPs by telling Stripes what bean to use, and
+automatically by Stripes when its servlet filter (StripesFilter) detects
+URLs that end in <code>.action</code>. JSPWiki uses both methods.</p>
<p><strong>Manual binding via JSP markup</strong></p>
-<p>In JSPWiki 3.0, each top-level JSP is mapped to at least one, and usually just one, WikiActionBean. Each JSP declares what WikiActionBean it needs by including the following line:<p>
-<blockquote><code><<a href="http://stripes.sourceforge.net/docs/current/taglib/stripes/useActionBean.html">stripes:useActionBean</a> beanclass="com.ecyrd.jspwiki.action.<em>foo</em>ActionBean"/></code></blockquote>
-<p>... where <em>foo</em> corresponds to a named action, such as <code>View</code> (for viewing wiki pages) and <code>UserProfile</code> (for editing a user's profile). For example, the page-editing JSP, <code>Edit.jsp</code>, contains this line:</p>
-
-<blockquote><code><stripes:useActionBean beanclass="com.ecyrd.jspwiki.action.EditActionBean"/></code></blockquote>
-
-<p>See this package for a complete list of WikiActionBeans used in JSPWiki 3.0. By convention, every top-level JSP in JSPWiki 3.0 <em>must</em> include a <code><stripes:useActionBean></code> tag at the top of their pages. This does three things: first, it guarantees that the specified WikiActionBean will be injected into into the PageContext's request scope with the well-known name {@link com.ecyrd.jspwiki.tags.WikiTagBase#ACTIONBEAN} ("wikiActionBean"). Second, it also means that JSTL expression language (EL) markup can access the WikiActionBean directly, for example, <code>${wikiActionBean.changenote}</code>. Third, it ensures that all of the request parameters we expect will be correctly bound to the WikiActionBean.</p>
-
-<p>In case you were wondering: conceptually, using <code><stripes:useActionBean></code> to instantiate WikiActionBeans is analogous to creating old-style "wiki contexts" JSPWiki versions prior to 3.0 using code like this:</p>
-
-<blockquote><code>WikiContext wikiContext = wiki.createContext( request, WikiContext.EDIT );</code></blockquote>
-
-<p>...although of course in 3.0 we do things via Stripes JSP tags rather than scriptlet code. WikiContexts aren't forgotten though; in fact, WikiContext is a <em>subclass</em> of WikiActionBean. That's right: we've refactored WikiContext so that it is now an ActionBean in its own right, and is the parent superclass of all of page-related WikiActionBeans, like {@link com.ecyrd.jspwiki.action.ViewActionBean}, {@link com.ecyrd.jspwiki.action.EditActionBean}, {@link com.ecyrd.jspwiki.action.PageInfoActionBean} and many others. If you've been paying attention, this means JSP markup can use and evaluate expressions like this:</p>
+<p>In JSPWiki 3.0, each top-level JSP is mapped to at least one, and
+usually just one, WikiActionBean. Each JSP declares what WikiActionBean
+it needs by including the following line:
+<p>
+<blockquote><code><<a
+ href="http://stripes.sourceforge.net/docs/current/taglib/stripes/useActionBean.html">stripes:useActionBean</a>
+beanclass="com.ecyrd.jspwiki.action.<em>foo</em>ActionBean"/></code></blockquote>
+<p>... where <em>foo</em> corresponds to a named action, such as <code>View</code>
+(for viewing wiki pages) and <code>UserProfile</code> (for editing a
+user's profile). For example, the page-editing JSP, <code>Edit.jsp</code>,
+contains this line:</p>
+
+<blockquote><code><stripes:useActionBean
+beanclass="com.ecyrd.jspwiki.action.EditActionBean"/></code></blockquote>
+
+<p>See this package for a complete list of WikiActionBeans used in
+JSPWiki 3.0. By convention, every top-level JSP in JSPWiki 3.0 <em>must</em>
+include a <code><stripes:useActionBean></code> tag at the top of
+their pages. This does three things: first, it guarantees that the
+specified WikiActionBean will be injected into into the PageContext's
+request scope with the well-known name {@link
+com.ecyrd.jspwiki.action.WikiActionBeanFactory#ATTR_ACTIONBEAN}
+("wikiActionBean"). Second, it also means that JSTL expression language
+(EL) markup can access the WikiActionBean directly, for example, <code>${wikiActionBean.changenote}</code>.
+Third, it ensures that all of the request parameters we expect will be
+correctly bound to the WikiActionBean.</p>
+
+<p>In case you were wondering: conceptually, using <code><stripes:useActionBean></code>
+to instantiate WikiActionBeans is analogous to creating old-style "wiki
+contexts" JSPWiki versions prior to 3.0 using code like this:</p>
+
+<blockquote><code>WikiContext wikiContext =
+wiki.createContext( request, WikiContext.EDIT );</code></blockquote>
+
+<p>...although of course in 3.0 we do things via Stripes JSP tags
+rather than scriptlet code. WikiContexts aren't forgotten though; in
+fact, WikiContext is a <em>subclass</em> of WikiActionBean. That's
+right: we've refactored WikiContext so that it is now an ActionBean in
+its own right, and is the parent superclass of all of page-related
+WikiActionBeans, like {@link com.ecyrd.jspwiki.action.ViewActionBean},
+{@link com.ecyrd.jspwiki.action.EditActionBean}, {@link
+com.ecyrd.jspwiki.action.PageInfoActionBean} and many others. If you've
+been paying attention, this means JSP markup can use and evaluate
+expressions like this:</p>
<blockquote><code>${wikiActionBean.wikiSession.loginName}</code></blockquote>
-<p>EL syntax can be used to navigate much more complicated object graphs than this, but you get the idea. What could be easier?</p>
+<p>EL syntax can be used to navigate much more complicated object
+graphs than this, but you get the idea. What could be easier?</p>
-<blockquote><em><strong>Guideline #2 for JSPWiki developers</strong>: JSPs should not attempt to instantiate WikiContexts directly. Instead, they </em>must<em> include a <code><stripes:useActionBean beanclass="com.ecyrd.jspwiki.action.</em>foo<em>Bean"/></code> element that tells JSPWiki which WikiActionBean (generally, a WikiContext subclass) to use. For example, <code><stripes:useActionBean beanclass="com.ecyrd.jspwiki.action.EditActionBean"/></code> tells a JSPWiki to automatically instantiate the wiki context EditActionBean and place it in request scope.</em></blockquote>
+<blockquote><em><strong>Guideline #2 for
+JSPWiki developers</strong>: JSPs should not attempt to instantiate WikiContexts
+directly. Instead, they </em>must<em> include a <code><stripes:useActionBean
+beanclass="com.ecyrd.jspwiki.action.</em>foo<em>Bean"/></code> element that
+tells JSPWiki which WikiActionBean (generally, a WikiContext subclass)
+to use. For example, <code><stripes:useActionBean
+beanclass="com.ecyrd.jspwiki.action.EditActionBean"/></code> tells a JSPWiki
+to automatically instantiate the wiki context EditActionBean and place
+it in request scope.</em></blockquote>
<p><strong>Automatic binding to <code>.action</code> URLs</strong></p>
-<p>In addition to the manual method for binding WikiActionBeans to JSPs, Stripes also automatically binds ActionBeans to URLs that contain the <code>.action</code> suffix. When it detects such a URL, it tries to locate and bind the correct ActionBean by scanning for ActionBean subclasses whose names share the same prefix and whose suffixes are ActionBean or Action. For example, the URL <code>Group.action</code> causes Stripes to look for ActionBeans called <code>GroupActionBean</code> and <code>GroupAction</code>, and if a class with that name is found, Stripes will instantiate one of these and bind its fields to the request parameters.</p>
-
-<p>Stripes also attempts to locate ActionBeans by looking for a special class-level annotation, <code><a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/UrlBinding.html">@UrlBinding</a></code>, that specifies the mapping. By convention, this is how we do things in JSPWiki 3.0. For example, the ViewActionBean class contains this annotation:</p>
+<p>In addition to the manual method for binding WikiActionBeans to
+JSPs, Stripes also automatically binds ActionBeans to URLs that contain
+the <code>.action</code> suffix. When it detects such a URL, it tries to
+locate and bind the correct ActionBean by scanning for ActionBean
+subclasses whose names share the same prefix and whose suffixes are
+ActionBean or Action. For example, the URL <code>Group.action</code>
+causes Stripes to look for ActionBeans called <code>GroupActionBean</code>
+and <code>GroupAction</code>, and if a class with that name is found,
+Stripes will instantiate one of these and bind its fields to the request
+parameters.</p>
+
+<p>Stripes also attempts to locate ActionBeans by looking for a
+special class-level annotation, <code><a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/UrlBinding.html">@UrlBinding</a></code>,
+that specifies the mapping. By convention, this is how we do things in
+JSPWiki 3.0. For example, the ViewActionBean class contains this
+annotation:</p>
<blockquote><code>@UrlBinding("/Wiki.action")</code></blockquote>
-<p>This annotation guarantees that any time StripesFilter encounters the URL <code>/Wiki.Action</code>, an instance of ViewActionBean will be instantiated and injected into the request as an attribute; its fields will also be bound in the same way as the manual method.</p>
-
-<p>Automatic ActionBean binding is typically done upon form submission, because Stripes' form tags cause forms to be posted to <code>.action</code> URLs. For this reason, automatic binding also causes fields to be validated as well (more on this shortly).</p>
-
-<blockquote><em><strong>Guideline #3 for JSPWiki developers</strong>: every WikiActionBean subclass should contain a class-level <code>@UrlBinding</code> annotation that tells Stripes how to locate the bean when user submit forms.</em></blockquote>
-
-<blockquote><em><strong>Guideline #4 for JSPWiki developers</strong>: JSPs can -- and should -- use JSP 2.0 EL syntax to access properties of the current WikiActionBean. JSPWiki guarantees that when the <code><useActionBean></code> tag is present, the ActionBean will be made available as the page attibute <code>wikiActionBean</code>. For example, <code>${wikiActionBean.wikiSession.loginName}</code> prints the user's login name.</em></blockquote>
+<p>This annotation guarantees that any time StripesFilter encounters
+the URL <code>/Wiki.Action</code>, an instance of ViewActionBean will be
+instantiated and injected into the request as an attribute; its fields
+will also be bound in the same way as the manual method.</p>
+
+<p>Automatic ActionBean binding is typically done upon form
+submission, because Stripes' form tags cause forms to be posted to <code>.action</code>
+URLs. For this reason, automatic binding also causes fields to be
+validated as well (more on this shortly).</p>
+
+<blockquote><em><strong>Guideline #3 for
+JSPWiki developers</strong>: every WikiActionBean subclass should contain a
+class-level <code>@UrlBinding</code> annotation that tells Stripes how
+to locate the bean when user submit forms.</em></blockquote>
+
+<blockquote><em><strong>Guideline #4 for
+JSPWiki developers</strong>: JSPs can -- and should -- use JSP 2.0 EL syntax to
+access properties of the current WikiActionBean. JSPWiki guarantees that
+when the <code><useActionBean></code> tag is present, the
+ActionBean will be made available as the page attibute <code>wikiActionBean</code>.
+For example, <code>${wikiActionBean.wikiSession.loginName}</code> prints
+the user's login name.</em></blockquote>
<h3>ActionBean Events</h3>
-<p>As discussed at the beginning of this page, Stripes ActionBeans includes getters and setters for parameters that are extracted from the request stream. ActionBeans also include methods that are annotated as "events," which respond to client activities like form POSTs. In JSPWiki 2.<em>x</em>, events were (very roughly) implemented using JSP scriptlet code. For example, consider this snippet from the old <code>UserPreferences.jsp</code>:</p>
+<p>As discussed at the beginning of this page, Stripes ActionBeans
+includes getters and setters for parameters that are extracted from the
+request stream. ActionBeans also include methods that are annotated as
+"events," which respond to client activities like form POSTs. In JSPWiki
+2.<em>x</em>, events were (very roughly) implemented using JSP scriptlet
+code. For example, consider this snippet from the old <code>UserPreferences.jsp</code>:</p>
<pre>String action = request.getParameter("action");
if( "createAssertedName".equals(action) )
@@ -97,7 +227,13 @@
...
}</pre>
-<p>Scriptlets like these served only to clutter up JSPs with lots of spaghetti code. With Stripes, all event processing code is moved into ActionBean methods that have a special <code><a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/HandlesEvent.html">@HandlesEvent</a></code> annotation. For example, the user preferences code that previously created user name assertions moved into an annotated <code>addAssertionCookie()</code> method that does the work by "handling" the event <code>createAssertedName</code>:</p>
+<p>Scriptlets like these served only to clutter up JSPs with lots of
+spaghetti code. With Stripes, all event processing code is moved into
+ActionBean methods that have a special <code><a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/HandlesEvent.html">@HandlesEvent</a></code>
+annotation. For example, the user preferences code that previously
+created user name assertions moved into an annotated <code>addAssertionCookie()</code>
+method that does the work by "handling" the event <code>createAssertedName</code>:</p>
<pre>@HandlesEvent("createAssertedName")
public Resolution addAssertionCookie()
@@ -108,7 +244,12 @@
return new RedirectResolution("/");
}</pre>
-<p>The effect of moving POST processing code into ActionBeans dramatically simplifies JSPs. But you might be wondering, how does Stripes know how (and when) it should call ActionBean event methods? Simple: a series of simple JSP tags, modeled after their HTML counterparts, tells Stripes what beans and events it should invoke. For example:</p>
+<p>The effect of moving POST processing code into ActionBeans
+dramatically simplifies JSPs. But you might be wondering, how does
+Stripes know how (and when) it should call ActionBean event methods?
+Simple: a series of simple JSP tags, modeled after their HTML
+counterparts, tells Stripes what beans and events it should invoke. For
+example:</p>
<pre><stripes:form id="preferences" action="/UserPreferences.action" method="POST" acceptcharset="UTF-8">
...
@@ -117,31 +258,99 @@
<stripes:submit name="createAssertedName"/>
</stripes:form></pre></pre>
-<p>Here, the <code><a href="http://stripes.sourceforge.net/docs/current/taglib/stripes/form.html">stripes:form</a></code> tag includes an <code>action</code> parameter that specifies the URL to post to. Because the {@link com.ecyrd.jspwiki.action.UserPreferencesActionBean} contains a class-level <code>@UrlBinding("/UserPreferences.action")</code> annotation, Stripes knows that this corresponds to that bean class UserPreferencesActionBean. And because the <code><a href="http://stripes.sourceforge.net/docs/current/taglib/stripes/submit.html">stripes:submit</a></code> tag's <code>name</code> attribute contains the value <code>createAssertedName</code>, Stripes knows that it needs to locate and call the corresponding method that handles that event, in this case <code>addAssertionCookie</code>.
-
-<p>Note: an alternative syntax for <stripes:form> uses the <code>beanClass</code> attribute instead of <code>action</code>, which might be a little easier in some cases. This is functionally equivalent:</p>
+<p>Here, the <code><a
+ href="http://stripes.sourceforge.net/docs/current/taglib/stripes/form.html">stripes:form</a></code>
+tag includes an <code>action</code> parameter that specifies the URL to
+post to. Because the {@link
+com.ecyrd.jspwiki.action.UserPreferencesActionBean} contains a
+class-level <code>@UrlBinding("/UserPreferences.action")</code>
+annotation, Stripes knows that this corresponds to that bean class
+UserPreferencesActionBean. And because the <code><a
+ href="http://stripes.sourceforge.net/docs/current/taglib/stripes/submit.html">stripes:submit</a></code>
+tag's <code>name</code> attribute contains the value <code>createAssertedName</code>,
+Stripes knows that it needs to locate and call the corresponding method
+that handles that event, in this case <code>addAssertionCookie</code>.
+<p>Note: an alternative syntax for <stripes:form> uses the <code>beanClass</code>
+attribute instead of <code>action</code>, which might be a little easier
+in some cases. This is functionally equivalent:</p>
<pre><stripes:form id="preferences" action="/UserPreferences.action" method="POST" acceptcharset="UTF-8"></pre>
-<blockquote><em><strong>Guideline #5 for JSPWiki developers</strong>: processing code that handles form POST activities (that would have ordinarily gone into top-level JSPs) should </em>always<em> be moved into WikiActionBean event handler methods. These methods should contain a <code>@HandlesEvent</code> annotation that specifies which named event it handles. On JSPs, each event name should have an equivalent <code><stripes:submit></code> button; for example, <code><stripes:submit name="createAssertedName"/></code>. Its containing <stripes:form> element's <code>action</code> should contain the URL of the ActionBean the event pertains to, or alternative a <code>beanClass</code> attribute that names the ActionBean class explicitly. Example: <code><stripes:form beanClass="UserPreferencesAction.class"></code></em></blockquote>
+<blockquote><em><strong>Guideline #5 for
+JSPWiki developers</strong>: processing code that handles form POST activities
+(that would have ordinarily gone into top-level JSPs) should </em>always<em>
+be moved into WikiActionBean event handler methods. These methods should
+contain a <code>@HandlesEvent</code> annotation that specifies which
+named event it handles. On JSPs, each event name should have an
+equivalent <code><stripes:submit></code> button; for example, <code><stripes:submit
+name="createAssertedName"/></code>. Its containing <stripes:form>
+element's <code>action</code> should contain the URL of the ActionBean
+the event pertains to, or alternative a <code>beanClass</code> attribute
+that names the ActionBean class explicitly. Example: <code><stripes:form
+beanClass="UserPreferencesAction.class"></code></em></blockquote>
+
+<blockquote><em><strong>Guideline #6 for
+JSPWiki developers</strong>: all <code><form></code> tags and related
+markup (such as <code><input></code>, <code><textarea></code>,
+<code><option></code>) should use the Stripes tags instead (</em>e.g.<em>,
+<code><stripes:form></code>, <code><a
+ href="http://stripes.sourceforge.net/docs/current/taglib/stripes/text.html"><stripes:text></a></code>,
+<code><a
+ href="http://stripes.sourceforge.net/docs/current/taglib/stripes/textarea.html"><stripes:textarea></a></code>,
+<code><a
+ href="http://stripes.sourceforge.net/docs/current/taglib/stripes/option.html"><stripes:option></a></code>).
+With one or two exceptions, these tags are identical to their HTML
+equivalents, and contain a few extra attributes used by Stripes.</em></blockquote>
-<blockquote><em><strong>Guideline #6 for JSPWiki developers</strong>: all <code><form></code> tags and related markup (such as <code><input></code>, <code><textarea></code>, <code><option></code>) should use the Stripes tags instead (</em>e.g.<em>, <code><stripes:form></code>, <code><a href="http://stripes.sourceforge.net/docs/current/taglib/stripes/text.html"><stripes:text></a></code>, <code><a href="http://stripes.sourceforge.net/docs/current/taglib/stripes/textarea.html"><stripes:textarea></a></code>, <code><a href="http://stripes.sourceforge.net/docs/current/taglib/stripes/option.html"><stripes:option></a></code>). With one or two exceptions, these tags are identical to their HTML equivalents, and contain a few extra attributes used by Stripes.</em></blockquote>
-
<h3>Form validation</h3>
-<p>Because JSPWiki 3.0 uses Stripes, our WikiActionBeans take advantage of another terrific feature: automatic form field validation based on annotations. Recall previously that ActionBeans have getters and setters that Stripes uses to store and retrieve request parameters. For validation, either the getter or setter (by convention, the setter) can also contain a <code><a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/validation/Validate.html">@validate</a></code> annotation that indicates whether values are required, and what their acceptable lengths or constraints might be. For example, consider {@link com.ecyrd.jspwiki.action.UserProfileActionBean}, a WikiActionBean that allows users to edit their user profile information. The <code>fullname</code> field has this annotation right above the setter:</p>
-
-<blockquote><code>@Validate(field="fullname", required=true, maxlength=100)</code></blockquote>
-
-<p>This annotation tells Stripes that the <code>fullname</code> field is a required field, and that its length must be less than 100 characters. When the form is POSTed, Stripes will check to see if this field was submitted by the user, and if not, automatically generate an error message that can be retrieved later. (By the <code><stripes:errors></code> tag, incidentally.) But Stripes can do more than simple text field validation. Here is the annotation for UserProfileActionBean's <code>email</code> field:</p>
-
-<blockquote><code>@Validate(field="email", required = false, converter = <a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/validation/EmailTypeConverter.html">EmailTypeConverter.class</a>)</code></blockquote>
-
-<p>In this case, Stripes will use one of its own custom String converters to validate the e-mail address. In addition to these two validators (for Strings and e-mail addresses), Stripes also converts and validates dates, times, integers, longs, doubles, and <a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/validation/TypeConverter.html">many other types</a>. It "knows" which converter to invoke because of the field's type. In addition to Stripes' own converters, JSPWiki 3.0 contains converters for fields of type WikiPage, Group and Principal.</p>
-
-<blockquote><em><strong>Guideline #7 for JSPWiki developers</strong>: When creating WikiActionBeans, all fields that require validation should have <code>@validate</code> annotations on their setter methods.</em></blockquote>
+<p>Because JSPWiki 3.0 uses Stripes, our WikiActionBeans take
+advantage of another terrific feature: automatic form field validation
+based on annotations. Recall previously that ActionBeans have getters
+and setters that Stripes uses to store and retrieve request parameters.
+For validation, either the getter or setter (by convention, the setter)
+can also contain a <code><a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/validation/Validate.html">@validate</a></code>
+annotation that indicates whether values are required, and what their
+acceptable lengths or constraints might be. For example, consider {@link
+com.ecyrd.jspwiki.action.UserProfileActionBean}, a WikiActionBean that
+allows users to edit their user profile information. The <code>fullname</code>
+field has this annotation right above the setter:</p>
+
+<blockquote><code>@Validate(field="fullname",
+required=true, maxlength=100)</code></blockquote>
+
+<p>This annotation tells Stripes that the <code>fullname</code>
+field is a required field, and that its length must be less than 100
+characters. When the form is POSTed, Stripes will check to see if this
+field was submitted by the user, and if not, automatically generate an
+error message that can be retrieved later. (By the <code><stripes:errors></code>
+tag, incidentally.) But Stripes can do more than simple text field
+validation. Here is the annotation for UserProfileActionBean's <code>email</code>
+field:</p>
+
+<blockquote><code>@Validate(field="email", required
+= false, converter = <a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/validation/EmailTypeConverter.html">EmailTypeConverter.class</a>)</code></blockquote>
+
+<p>In this case, Stripes will use one of its own custom String
+converters to validate the e-mail address. In addition to these two
+validators (for Strings and e-mail addresses), Stripes also converts and
+validates dates, times, integers, longs, doubles, and <a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/validation/TypeConverter.html">many
+other types</a>. It "knows" which converter to invoke because of the field's
+type. In addition to Stripes' own converters, JSPWiki 3.0 contains
+converters for fields of type WikiPage, Group and Principal.</p>
+
+<blockquote><em><strong>Guideline #7 for
+JSPWiki developers</strong>: When creating WikiActionBeans, all fields that
+require validation should have <code>@validate</code> annotations on
+their setter methods.</em></blockquote>
<h3>Pageflow and Redirection</h3>
-<p>Browser redirects and related pageflow issues are handled very differently in JSPWiki 3.0 than in previous versions. Previously, redirects were implemented directly in JSP scriptlet code. For example, consider this snippet from <code>Edit.jsp</code>:</p>
+<p>Browser redirects and related pageflow issues are handled very
+differently in JSPWiki 3.0 than in previous versions. Previously,
+redirects were implemented directly in JSP scriptlet code. For example,
+consider this snippet from <code>Edit.jsp</code>:</p>
<pre>if( change != null && change.getTime() != pagedate )
{
@@ -156,35 +365,62 @@
return;
}</pre>
-<p>In JSPWiki 3.0, these activities fall into the category of "processing logic" -- the type of code that gets put into WikiActionBean events. In this particular case, the code moves into a Stripes event handler method in the EditActionBean class; its method annotations contains <code>@HandlesEvent("save")</code>.</p>
-
-<p>When a Stripes event handler method needs to redirect a user to another page, it returns an object called a <a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/Resolution.html">Resolution</a> that tells Stripes how to proceed. Stripes contains four easy-to-use Resolutions:</p>
+<p>In JSPWiki 3.0, these activities fall into the category of
+"processing logic" -- the type of code that gets put into WikiActionBean
+events. In this particular case, the code moves into a Stripes event
+handler method in the EditActionBean class that has an <code>@HandlesEvent</code>
+annotation with the name <code>save</code>.</p>
+
+<p>When a Stripes event handler method needs to redirect a user to
+another page, it returns an object called a <a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/Resolution.html">Resolution</a>
+that tells Stripes how to proceed. Stripes contains four easy-to-use
+Resolutions:</p>
<ul>
- <li><strong><a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/ForwardResolution.html">ForwardResolution</a></strong>: forwards the user to another path within the same web application using a server side forward. Constructors include:
- <ul>
- <li><code>ForwardResolution(Class<? extends ActionBean> beanType, String event)</code> - Constructs a ForwardResolution that will forward to the URL appropriate for the ActionBean supplied.</li>
+ <li><strong><a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/ForwardResolution.html">ForwardResolution</a></strong>:
+ forwards the user to another path within the same web application using
+ a server side forward. Constructors include:
+ <ul>
+ <li><code>ForwardResolution(Class<? extends ActionBean> beanType, String event)</code> - Constructs a ForwardResolution that will forward to the URL appropriate for the ActionBean supplied.</li>
<li><code>ForwardResolution(String path)</code> - Simple constructor that takes in the path to forward the user to.</li>
</ul>
</li>
<li><strong><a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/ajax/JavaScriptResolution.html">JavaScriptResolution</a></strong>: converts a Java object web to a web of JavaScript objects and arrays, and stream the JavaScript back to the client. The output of this resolution can be evaluated in JavaScript using the eval() function, and will return a reference to the top level JavaScript object. Constructors include:
<ul>
- <li><code>JavaScriptResolution(Object rootObject, Class<?>... userTypesExcluded)</code></li>
- </ul>
- </li>
- <li><strong><a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/RedirectResolution.html">RedirectResolution</a></strong>: redirects the user to another path by issuing a client side redirect. Constructors include:
- <ul>
- <li><code>RedirectResolution(Class<? extends ActionBean> beanType)</code> - Constructs a RedirectResolution that will redirect to the URL appropriate for the ActionBean supplied.</li>
- <li><code>RedirectResolution(Class<? extends ActionBean> beanType, String event)</code> - Constructs a RedirectResolution that will redirect to the URL appropriate for the ActionBean supplied.</li>
- <li><code>RedirectResolution(String url)</code> - Simple constructor that takes the URL to which to forward the user.</li>
- </ul>
- </li>
-
- <li><strong><a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/StreamingResolution.html">StreamingResolution</a></strong>: streams data back to the client (in place of forwarding the user to another page). Designed to be used for streaming non-page data such as generated images/charts and XML islands.</li>
+ <li><code>JavaScriptResolution(Object rootObject, Class<?>...
+ userTypesExcluded)</code></li>
+ </ul>
+ </li>
+ <li><strong><a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/RedirectResolution.html">RedirectResolution</a></strong>:
+ redirects the user to another path by issuing a client side redirect.
+ Constructors include:
+ <ul>
+ <li><code>RedirectResolution(Class<? extends
+ ActionBean> beanType)</code> - Constructs a RedirectResolution that will
+ redirect to the URL appropriate for the ActionBean supplied.</li>
+ <li><code>RedirectResolution(Class<? extends
+ ActionBean> beanType, String event)</code> - Constructs a
+ RedirectResolution that will redirect to the URL appropriate for the
+ ActionBean supplied.</li>
+ <li><code>RedirectResolution(String url)</code> - Simple
+ constructor that takes the URL to which to forward the user.</li>
+ </ul>
+ </li>
+
+ <li><strong><a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/StreamingResolution.html">StreamingResolution</a></strong>:
+ streams data back to the client (in place of forwarding the user to
+ another page). Designed to be used for streaming non-page data such as
+ generated images/charts and XML islands.</li>
</ul>
-<p>Handler events that need to interrupt processing or return data to the use simply need to return one of these four resolutions. For example, the previous scriptlet code could be re-written as an EditActionBean event handler as follows:
-
+<p>Handler events that need to interrupt processing or return data
+to the use simply need to return one of these four resolutions. For
+example, the previous scriptlet code could be re-written as an
+EditActionBean event handler as follows:
<pre>
@HandlesEvent("save")
public Resolution save()
@@ -203,18 +439,44 @@
}
}</pre>
-<p>The <code>RedirectResolution</code> tells Stripes to redirect the user to the conflict-editing page, the URL for which Stripes will automatically locate due to ConflictActionBean's <code>@UrlBinding</code> annotation (see Guideline #3). It will also append the parameter <code>page</code> with the value of the page. And finally it will add the current ActionBean to a temporary storage area called the <a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/controller/FlashScope.html">flash scope</a> where it can be retrieved by the target of the redirect. When the target (in this case, ConflictActionBean) executes, it can retrieve the bean stored in flash scope easily:</p>
+<p>The <code>RedirectResolution</code> tells Stripes to redirect the
+user to the conflict-editing page, the URL for which Stripes will
+automatically locate due to ConflictActionBean's <code>@UrlBinding</code>
+annotation (see Guideline #3). It will also append the parameter <code>page</code>
+with the value of the page. And finally it will add the current
+ActionBean to a temporary storage area called the <a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/controller/FlashScope.html">flash
+scope</a> where it can be retrieved by the target of the redirect. When the
+target (in this case, ConflictActionBean) executes, it can retrieve the
+bean stored in flash scope easily:</p>
<pre>FlashScope scope = FlashScope.getCurrent( request, true);
WikiActionBean editContext = (WikiActionBean)scope.get( "/EditActionBean" );</pre>
-<p>After retrieving the previously-flashed EditActionBean, its contents can be retrieved and manipulated like any other bean.</p>
-
-<blockquote><em><strong>Guideline #8 for JSPWiki developers</strong>: processing logic that would, in previous versions of JSPWiki, reside in scriptlet code should be moved into WikiActionBean event handlers. When an event handler needs to modify the user page flow or redirect the browser, it should return a suitable Resolution, such as the RedirectResolution.</blockquote>
-
-<blockquote><em><strong>Guideline #9 for JSPWiki developers</strong>: client-side code that need to retrieve AJAX or JSON data from JSPWiki should POST to a WikiActionBean event handler, which should in turn return a <code>JavaScriptResolution</code> or a <code>StreamingResolution</code>.</blockquote>
+<p>After retrieving the previously-flashed EditActionBean, its
+contents can be retrieved and manipulated like any other bean.</p>
-<blockquote><em><strong>Guideline #10 for JSPWiki developers</strong>: event handlers that need to ensure that the current WikiActionBean is accessible by the next one in the request cycle should add themselves to "flash scope" by calling the Resolution's <code><a href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/RedirectResolution.html#flash(net.sourceforge.stripes.action.ActionBean)">flash()</a></code> method. These can be retrieved by the next ActionBean by retrieving the current FlashScope for the request and calling its <code><a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/HashMap.html#get(java.lang.Object)">get()</a></code> method and passing the URLBinding as a parameter.</blockquote>
+<blockquote><em><strong>Guideline #8 for
+JSPWiki developers</strong>: processing logic that would, in previous versions of
+JSPWiki, reside in scriptlet code should be moved into WikiActionBean
+event handlers. When an event handler needs to modify the user page flow
+or redirect the browser, it should return a suitable Resolution, such as
+the RedirectResolution.</blockquote>
+
+<blockquote><em><strong>Guideline #9 for
+JSPWiki developers</strong>: client-side code that need to retrieve AJAX or JSON
+data from JSPWiki should POST to a WikiActionBean event handler, which
+should in turn return a <code>JavaScriptResolution</code> or a <code>StreamingResolution</code>.</blockquote>
+
+<blockquote><em><strong>Guideline #10 for
+JSPWiki developers</strong>: event handlers that need to ensure that the current
+WikiActionBean is accessible by the next one in the request cycle should
+add themselves to "flash scope" by calling the Resolution's <code><a
+ href="http://stripes.sourceforge.net/docs/current/javadoc/net/sourceforge/stripes/action/RedirectResolution.html#flash(net.sourceforge.stripes.action.ActionBean)">flash()</a></code>
+method. These can be retrieved by the next ActionBean by retrieving the
+current FlashScope for the request and calling its <code><a
+ href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/HashMap.html#get(java.lang.Object)">get()</a></code>
+method and passing the URLBinding as a parameter.</blockquote>
</body>
</html>
\ No newline at end of file