You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by ek...@apache.org on 2006/03/01 05:43:54 UTC
svn commit: r381903 - in
/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow:
interceptor/ interceptor/request/ xmlhttprequest/
Author: ekoneil
Date: Tue Feb 28 20:43:53 2006
New Revision: 381903
URL: http://svn.apache.org/viewcvs?rev=381903&view=rev
Log:
Add a bunch of Javadoc to the NetUI Interceptor infrastructure. And fix a one character typo in the XmlHttpRequestServlet.
BB: self
Test: NetUI DRT pass
Modified:
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/AbstractInterceptor.java
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptor.java
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorChain.java
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorConfig.java
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorContext.java
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorException.java
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptors.java
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/request/RequestInterceptorContext.java
beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/xmlhttprequest/XmlHttpRequestServlet.java
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/AbstractInterceptor.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/AbstractInterceptor.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/AbstractInterceptor.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/AbstractInterceptor.java Tue Feb 28 20:43:53 2006
@@ -19,8 +19,11 @@
import java.io.Serializable;
+/**
+ * Abstract base class that provides a convenience implementation for creating an {@link Interceptor}.
+ */
public abstract class AbstractInterceptor
- implements Interceptor, Serializable
+ implements Interceptor, Serializable
{
private InterceptorConfig _config;
@@ -43,5 +46,4 @@
{
return _config;
}
-
}
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptor.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptor.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptor.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptor.java Tue Feb 28 20:43:53 2006
@@ -18,15 +18,38 @@
package org.apache.beehive.netui.pageflow.interceptor;
/**
- * Base class for all interceptors.
+ * <p>
+ * Base interface for all NetUI / Page Flow interceptors. An interceptor consists of an
+ * initialization step and two blocks of code that run before and after some block of code
+ * or event that is being intercepted.
+ * </p>
*/
public interface Interceptor
{
+ /**
+ * Method used to initialize the interceptor.
+ *
+ * @param config the {@link InterceptorConfig} object
+ */
public void init( InterceptorConfig config );
-
+
+ /**
+ * Method invoked during "pre" interception of some block of code / event.
+ *
+ * @param context the interception context
+ * @param chain the chain of interceptors
+ * @throws InterceptorException an exception thrown when an error occurs during interception
+ */
public void preInvoke( InterceptorContext context, InterceptorChain chain )
throws InterceptorException;
-
+
+ /**
+ * Method invoked during "post" interception of some block of code / event.
+ *
+ * @param context the interceptor context
+ * @param chain the chain of interceptors
+ * @throws InterceptorException an exception thrown when an error occurs during interception
+ */
public void postInvoke( InterceptorContext context, InterceptorChain chain )
throws InterceptorException;
}
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorChain.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorChain.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorChain.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorChain.java Tue Feb 28 20:43:53 2006
@@ -21,19 +21,34 @@
import java.util.LinkedList;
/**
- * Base class for all chains of {@link Interceptor}s.
+ * <p>
+ * Abstract base class that represents an interceptor chain.
+ * </p>
*/
public abstract class InterceptorChain
{
private LinkedList/*< Interceptor >*/ _chain = new LinkedList/*< Interceptor >*/();
private InterceptorContext _context;
-
+
+ /**
+ * Create an interceptor chain with the {@link InterceptorContext} and a {@link List} of
+ * interceptors.
+ *
+ * @param context the context
+ * @param interceptors the interceptors
+ */
protected InterceptorChain( InterceptorContext context, List/*< Interceptor >*/ interceptors )
{
_context = context;
_chain.addAll( interceptors );
}
-
+
+ /**
+ * Execute the next interceptor in the chain of interceptors.
+ *
+ * @return the object returned when the interceptor is invoked
+ * @throws InterceptorException the exception thrown if an error occurs while invoking the interceptor
+ */
public Object continueChain()
throws InterceptorException
{
@@ -46,19 +61,40 @@
return null;
}
}
-
+
+ /**
+ * Invoke an interceptor.
+ *
+ * @param interceptor the interceptor to invoke
+ * @return the interceptor's return value
+ * @throws InterceptorException the exception thrown if an error occurs while invoking the interceptor
+ */
protected abstract Object invoke( Interceptor interceptor ) throws InterceptorException;
-
+
+ /**
+ * Get the {@link InterceptorContext}
+ * @return the context
+ */
public InterceptorContext getContext()
{
return _context;
}
-
+
+ /**
+ * Check to see if the interception chain is empty.
+ * @return <code>true</code> if the chain is empty; <code>false</code> otherwise.
+ */
public boolean isEmpty()
{
return _chain.isEmpty();
}
-
+
+ /**
+ * Remove the first {@link Interceptor} that is currently the first interceptor in the chain.
+ * This method can be used to advance to the "next" interceptor in the chain when executing
+ * a chain of interceptors.
+ * @return the first interceptor if one exists
+ */
protected Interceptor removeFirst()
{
return ( Interceptor ) _chain.removeFirst();
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorConfig.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorConfig.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorConfig.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorConfig.java Tue Feb 28 20:43:53 2006
@@ -22,45 +22,80 @@
import java.util.HashMap;
/**
- * Class to hold configuration parameters for registered {@link Interceptor}s.
+ * <p>
+ * Class used to hold configuration information for an {@link Interceptor}. Each
+ * interceptor instance will have it's own configuration object which holds the
+ * interceptor implementation class and a set of custom properties that can be provided
+ * for each interceptor instance.
+ * </p>
*/
public class InterceptorConfig
- implements Serializable
+ implements Serializable
{
private String _interceptorClass;
private Map/*< String, String >*/ _customProperties = new HashMap/*< String, String >*/();
+ /**
+ * Default constructor.
+ */
protected InterceptorConfig()
{
}
+ /**
+ * Create this config object for an intereceptor with the given class name.
+ * @param interceptorClass the {@link Interceptor}'s class name
+ */
protected InterceptorConfig( String interceptorClass )
{
_interceptorClass = interceptorClass;
}
+ /**
+ * Get the interceptor class.
+ * @return the String for the interceptor's class
+ */
public String getInterceptorClass()
{
return _interceptorClass;
}
+ /**
+ * Set the interceptor class.
+ * @param interceptorClass the String for the interceptor's class
+ */
public void setInterceptorClass( String interceptorClass )
{
_interceptorClass = interceptorClass;
}
-
+
+ /**
+ * Get the interceptor's custom properties. This returned {@link Map} contains pairs
+ * of <String, String>.
+ * @return the map of custom properties
+ */
public Map/*< String, String >*/ getCustomProperties()
{
return _customProperties;
}
-
- void addCustomProperty( String name, String value )
- {
- _customProperties.put( name, value );
- }
-
+
+ /**
+ * Get the custom property value corresponding to the given property name.
+ * @param name the name of the property
+ * @return the value of the property; if the property name isn't found, the value will be null
+ */
public String getCustomProperty( String name )
{
return ( String ) _customProperties.get( name );
}
-}
+
+ /**
+ * Internal method used by the framework to add custom interceptor config properties.
+ * @param name the custom property's name
+ * @param value the custom property's value
+ */
+ void addCustomProperty( String name, String value )
+ {
+ _customProperties.put( name, value );
+ }
+}
\ No newline at end of file
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorContext.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorContext.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorContext.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorContext.java Tue Feb 28 20:43:53 2006
@@ -25,10 +25,12 @@
import java.util.List;
/**
- * Base context for callbacks on {@link Interceptor}s.
+ * <p>
+ * Context object that encapsulates the configuration for an entire interceptor chain.
+ * </p>
*/
public class InterceptorContext
- implements Serializable
+ implements Serializable
{
private static final Logger _log = Logger.getInstance( InterceptorContext.class );
@@ -56,8 +58,15 @@
return _overridingInterceptor;
}
+ /**
+ * Add an {@link Interceptor} to the list of interceptors.
+ * @param configBeans an array of JavaBeans that configure a set of interceptors
+ * @param interceptorsList the list of {@link Interceptor} instances
+ * @param baseClassOrInterface
+ */
protected static void addInterceptors( org.apache.beehive.netui.util.config.bean.InterceptorConfig[] configBeans,
- List/*< Interceptor >*/ interceptorsList, Class baseClassOrInterface )
+ List/*< Interceptor >*/ interceptorsList,
+ Class baseClassOrInterface )
{
if ( configBeans != null )
{
@@ -91,18 +100,20 @@
* @param interceptors the List of interceptors to which to add.
* @return an initialized Interceptor, or <code>null</code> if an error occurred.
*/
- protected static Interceptor addInterceptor( InterceptorConfig config, Class baseClassOrInterface,
+ protected static Interceptor addInterceptor( InterceptorConfig config,
+ Class baseClassOrInterface,
List/*< Interceptor >*/ interceptors )
{
Interceptor interceptor = createInterceptor( config, baseClassOrInterface );
- if ( interceptor != null ) interceptors.add( interceptor );
+ if ( interceptor != null )
+ interceptors.add( interceptor );
return interceptor;
}
/**
- * Instantiates an interceptor, based on the class name in the given InterceptorConfig.
+ * Instantiates an interceptor using the class name in the given InterceptorConfig.
*
- * @param config the InterceptorConfig used to determine the interceptor class.
+ * @param config the {@link InterceptorConfig} used to determine the {@link Interceptor} class.
* @param baseClassOrInterface the required base class or interface. May be <code>null</code>.
* @return an initialized Interceptor, or <code>null</code> if an error occurred.
*/
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorException.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorException.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorException.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/InterceptorException.java Tue Feb 28 20:43:53 2006
@@ -18,21 +18,40 @@
package org.apache.beehive.netui.pageflow.interceptor;
/**
- * Exception thrown during callbacks on {@link Interceptor}s.
+ * Exception thrown while invoking {@link Interceptor}s.
*/
public class InterceptorException
- extends Exception
+ extends Exception
{
+ /**
+ * Default constructor.
+ */
+ public InterceptorException() {
+ }
+
+ /**
+ * Exception with message.
+ * @param message
+ */
public InterceptorException( String message )
{
super( message );
}
-
+
+ /**
+ * Exception with message and cause.
+ * @param message
+ * @param cause
+ */
public InterceptorException( String message, Throwable cause )
{
super( message, cause );
}
-
+
+ /**
+ * Exception with cause.
+ * @param cause
+ */
public InterceptorException( Throwable cause )
{
super( cause );
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptors.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptors.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptors.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/Interceptors.java Tue Feb 28 20:43:53 2006
@@ -17,11 +17,25 @@
*/
package org.apache.beehive.netui.pageflow.interceptor;
-
import java.util.List;
+/**
+ * <p>
+ * Convenience utility used to execute an interceptor chain given an {@link InterceptorContext}. This
+ * class can be invoked to execute "pre" and "post" interceptor chains.
+ * </p>
+ */
public class Interceptors
{
+ /**
+ * Execute a "pre" interceptor chain. This will execute the
+ * {@link Interceptor#preInvoke(InterceptorContext, InterceptorChain)}
+ * method to be invoked on each interceptor in a chain.
+ *
+ * @param context the context for a set of interceptors
+ * @param interceptors the list of interceptors
+ * @throws InterceptorException
+ */
public static void doPreIntercept( InterceptorContext context, List/*< Interceptor >*/ interceptors )
throws InterceptorException
{
@@ -31,7 +45,15 @@
chain.continueChain();
}
}
-
+
+ /**
+ * Execute a "post" interceptor chain. This will execute the
+ * {@link Interceptor#postInvoke(InterceptorContext, InterceptorChain)}
+ * method to be invoked on each interceptor in a chain.
+ * @param context the context for a set of interceptors
+ * @param interceptors the list of interceptors
+ * @throws InterceptorException
+ */
public static void doPostIntercept( InterceptorContext context, List/*< Interceptor >*/ interceptors )
throws InterceptorException
{
@@ -41,9 +63,13 @@
chain.continueChain();
}
}
-
+
+ /**
+ * Utility class used to configure an {@link InterceptorChain} and invoke an interceptor's
+ * {@link Interceptor#preInvoke(InterceptorContext, InterceptorChain)} method.
+ */
private static final class PreInvokeInterceptorChain
- extends InterceptorChain
+ extends InterceptorChain
{
public PreInvokeInterceptorChain( InterceptorContext context, List/*< Interceptor >*/ interceptors )
{
@@ -57,9 +83,13 @@
return null;
}
}
-
+
+ /**
+ * Utility class used to configure an {@link InterceptorChain} and invoke an interceptor's
+ * {@link Interceptor#postInvoke(InterceptorContext, InterceptorChain)} method.
+ */
private static final class PostInvokeInterceptorChain
- extends InterceptorChain
+ extends InterceptorChain
{
public PostInvokeInterceptorChain( InterceptorContext context, List/*< Interceptor >*/ interceptors )
{
@@ -73,4 +103,4 @@
return null;
}
}
-}
+}
\ No newline at end of file
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/request/RequestInterceptorContext.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/request/RequestInterceptorContext.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/request/RequestInterceptorContext.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/request/RequestInterceptorContext.java Tue Feb 28 20:43:53 2006
@@ -100,7 +100,9 @@
{
List/*< Interceptor >*/ interceptorsList =
( List/*< Interceptor >*/ ) servletContext.getAttribute( INTERCEPTORS_LIST_ATTR );
- if ( interceptorsList == null ) interceptorsList = new ArrayList/*< Interceptor >*/();
+ if ( interceptorsList == null )
+ interceptorsList = new ArrayList/*< Interceptor >*/();
+
interceptorsList.add( interceptor );
servletContext.setAttribute( INTERCEPTORS_LIST_ATTR, interceptorsList );
}
Modified: beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/xmlhttprequest/XmlHttpRequestServlet.java
URL: http://svn.apache.org/viewcvs/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/xmlhttprequest/XmlHttpRequestServlet.java?rev=381903&r1=381902&r2=381903&view=diff
==============================================================================
--- beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/xmlhttprequest/XmlHttpRequestServlet.java (original)
+++ beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/xmlhttprequest/XmlHttpRequestServlet.java Tue Feb 28 20:43:53 2006
@@ -46,7 +46,7 @@
{
ServletContext ctxt = getServletContext();
RequestInterceptorContext.init(ctxt);
- // TODO: does ErrorCRT really need to be an interceptor?
+ // TODO: does ErrorCRI really need to be an interceptor?
RequestInterceptorContext.addInterceptor(ctxt, new ErrorCRI());
}