directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From trus...@apache.org
Subject svn commit: r158447 - in directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor: BaseInterceptor.java Interceptor.java InterceptorChain.java InterceptorException.java NextInterceptor.java
Date Mon, 21 Mar 2005 11:06:44 GMT
Author: trustin
Date: Mon Mar 21 03:06:39 2005
New Revision: 158447

URL: http://svn.apache.org/viewcvs?view=rev&rev=158447
Log:
Added JavaDocs for interceptor framework.


Modified:
    directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/BaseInterceptor.java
    directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/Interceptor.java
    directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorChain.java
    directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorException.java
    directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/NextInterceptor.java

Modified: directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/BaseInterceptor.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/BaseInterceptor.java?view=diff&r1=158446&r2=158447
==============================================================================
--- directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/BaseInterceptor.java
(original)
+++ directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/BaseInterceptor.java
Mon Mar 21 03:06:39 2005
@@ -41,28 +41,32 @@
 
 
 /**
- * An interceptor base class which delegates handling of specific Invocations
- * to member methods within this Interceptor.  These handler methods are
- * analogous to the methods assocated with the Invocation.  They have the same
- * name and arguments as do the method associated with the Invocation.  The
- * analog member methods simply serve as a clean way to handle interception
- * without having to cast parameter Objects or recode this huge switch statement
- * for each concrete Interceptor implementation.
+ * A easy-to-use implementation of {@link Interceptor} that demultiplexes
+ * invocations using method signature overloading.
+ * <p>
+ * This {@link Interceptor} forwards received process requests to an
+ * appropriate <code>process(NextInterceptor, <em>ConcreteInvocation</em>)</code>
+ * methods.  Users can override any <code>process(..)</code> methods that
+ * corresponds to {@link Invocation} types that he or she wants to filter. 
+ * <p>
+ * For example, if user wants to filter {@link Add} invocation:
+ * <pre>
+ * public class MyInterceptor extends BaseInterceptor
+ * {
+ *     protected void process( NextInterceptor nextInterceptor, Add invocation )
+ *     {
+ *         nextInterceptor.process( invocation );
+ *         System.out.println( "Item added!" );
+ *     }
+ * }
+ * </pre>
+ * <code>BaseInterceptor</code> handles all long and tedious if-elseif blocks
+ * behind the scene.
  *
- * A ThreadLocal is used by all BaseInterceptors to associate the current
- * Thread of execution with an Invocation object.  This is done to optimize
- * the use of a single thread local for all instances of the BaseInterceptor
- * class.  It also removes the need for the invoke() method implementation to
- * have to set and [un]set the thread local Invocation on each invoke call of
- * every BaseInterceptor instance.
- *
- * The question then arrises, "Why do we need the ThreadLocal?"  Well why pass
- * around the Invocation object to all analog methods.  Plus we use member
- * methods rather than static methods to access thread locals and make the
- * analogs appear cleaner matching their respective invocation methods.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- * @version $Rev$
+ * @author The Apache Directory Project (dev@directory.apache.org)
+ * @author Alex Karasulu (akarasulu@apache.org)
+ * @author Trustin Lee (trustin@apache.org)
+ * @version $Rev$, $Date$
  */
 public abstract class BaseInterceptor implements Interceptor
 {

Modified: directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/Interceptor.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/Interceptor.java?view=diff&r1=158446&r2=158447
==============================================================================
--- directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/Interceptor.java
(original)
+++ directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/Interceptor.java
Mon Mar 21 03:06:39 2005
@@ -23,13 +23,15 @@
 import org.apache.ldap.server.jndi.invocation.Invocation;
 
 /**
- * Processes or filters any directory operations.  You can intercept the
- * {@link Invocation}s and perform 'before', 'after', 'around' any any other
- * filtering operations.
- *
+ * Filters any directory operations.  You can filter any
+ * {@link Invocation}s performed on {@link BackingStore}s just like Servlet
+ * filters do.
+ * 
  * @author The Apache Directory Project (dev@directory.apache.org)
  * @author Trustin Lee (trustin@apache.org)
  * @version $Rev$, $Date$
+ * 
+ * @see InvocationChain
  */
 public interface Interceptor
 {
@@ -49,13 +51,13 @@
     void destroy();
 
     /**
-     * Process a particular invocation.  You can pass control to
-     * <code>nextInterceptor</code> by invoking {@link #invoke(RequestProcessor,
Invocation)}. 
+     * Filters a particular invocation.  You can pass control to
+     * <code>nextInterceptor</code> by calling {@link NextInterceptor#invoke(Invocation)}.

      *
-     * @param nextProcessor the next processor in the processor chain
+     * @param nextInterceptor the next interceptor in the interceptor chain
      * @param invocation the invocation to process
      * @throws NamingException on failures while handling the invocation
      */
-    void process( NextInterceptor nextProcessor, Invocation call )
+    void process( NextInterceptor nextInterceptor, Invocation invocation )
             throws NamingException;
 }

Modified: directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorChain.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorChain.java?view=diff&r1=158446&r2=158447
==============================================================================
--- directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorChain.java
(original)
+++ directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorChain.java
Mon Mar 21 03:06:39 2005
@@ -1,3 +1,19 @@
+/*
+ *   Copyright 2004 The Apache Software Foundation
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ *
+ */
 package org.apache.ldap.server.jndi.invocation.interceptor;
 
 import java.util.ArrayList;
@@ -12,10 +28,11 @@
 import org.apache.ldap.server.jndi.invocation.Invocation;
 
 /**
- * Manages {@link Interceptor} stack.  The first {@link Interceptor} is
- * invoked and then invocation chain starts.
- * 
- * TODO imeplement me.
+ * Manages the chain of {@link Interceptor}s.
+ * <p>
+ * {@link org.apache.ldap.server.jndi.JndiProvider#invoke(Invocation)}
+ * redirects {@link Invocation}s to {@link #process(Invocation)} and
+ * the chain starts.
  * 
  * @author The Apache Directory Project (dev@directory.apache.org)
  * @author Trustin Lee (trustin@apache.org)
@@ -27,12 +44,12 @@
     {
         public void init(Properties config) throws NamingException
         {
-            // do nothing
+            // unused
         }
 
         public void destroy()
         {
-            // do nothing
+            // unused
         }
 
         public void process(NextInterceptor nextInterceptor, Invocation call)
@@ -185,7 +202,7 @@
     }
 
     /**
-     * Removed all interceptors added to this chain.
+     * Removes all interceptors added to this chain.
      */
     public synchronized void clear()
     {
@@ -194,6 +211,12 @@
         head = tail;
     }
 
+	/**
+	 * Throws an exception when the specified interceptor name is not registered
+	 * in this chain.
+	 * 
+	 * @return An interceptor entry with the specified name.
+	 */
     private Entry checkOldName( String baseName )
     {
         Entry e = ( Entry ) name2entry.get( baseName );
@@ -205,6 +228,10 @@
         return e;
     }
 
+	/**
+	 * Checks the specified interceptor name is already taken and throws
+	 * an exception if already taken.
+	 */
     private void checkNewName( String name )
     {
         if( name2entry.containsKey( name ) )
@@ -216,6 +243,7 @@
     
     /**
      * Start invocation chain with the specified invocation.
+     * 
      * @throws NamingException if invocation failed
      */
     public void process( Invocation call ) throws NamingException
@@ -238,7 +266,7 @@
     }
 
     /**
-     * Returns the list of interceptors this chain contains in the order of
+     * Returns the list of interceptors this chain in the order of
      * evaluation.
      */
     public List getAll()
@@ -256,7 +284,7 @@
     }
 
     /**
-     * Returns the list of interceptors this chain contains in the reversed
+     * Returns the list of interceptors this chain in the reversed
      * order of evaluation.
      */
     public List getAllReversed()
@@ -273,6 +301,9 @@
         return list;
     }
 
+	/**
+	 * Represents an internal entry of this chain.
+	 */
     private class Entry
     {
         private Entry prevEntry;

Modified: directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorException.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorException.java?view=diff&r1=158446&r2=158447
==============================================================================
--- directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorException.java
(original)
+++ directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/InterceptorException.java
Mon Mar 21 03:06:39 2005
@@ -24,81 +24,82 @@
 
 
 /**
- * Exception thrown by an Interceptor while intercepting an Invocation.
- * Interceptor failures caught from the method are bundled as
- * InterceptorExceptions and rethrown.
+ * A {@link LdapNamingException} that wraps uncaught runtime exceptions
+ * thrown from {@link Interceptor}s.
  *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- * @version $Rev$
+ * @author The Apache Directory Project (dev@directory.apache.org)
+ * @author Alex Karasulu (akarasulu@apache.org)
+ * @author Trustin Lee (trustin@apache.org)
+ * @version $Rev$, $Date$
  */
 public class InterceptorException extends LdapNamingException
 {
     private static final long serialVersionUID = 3258690996517746233L;
 
-    /** The Invokation the Interceptor failed on */
-    private final Invocation call;
+    /** The Invocation the Interceptor failed on */
+    private final Invocation invocation;
     /** The Interceptor causing the failure */
-    private final Interceptor requestProcessor;
+    private final Interceptor interceptor;
 
 
     /**
      * Creates an InterceptorException without a message.
      *
-     * @param requestProcessor the Interceptor causing the failure
+     * @param interceptor the Interceptor causing the failure
      * @param invocation the Invocation the Interceptor failed on
      */
-    public InterceptorException( Interceptor requestProcessor, Invocation request )
+    public InterceptorException( Interceptor interceptor, Invocation invocation )
     {
         super( ResultCodeEnum.OTHER );
-        this.call = request;
-        this.requestProcessor = requestProcessor;
+        this.invocation = invocation;
+        this.interceptor = interceptor;
     }
 
 
     /**
      * Creates an InterceptorException with a custom message.
      *
-     * @param requestProcessor the Interceptor causing the failure
+     * @param interceptor the Interceptor causing the failure
      * @param invocation the Invocation the Interceptor failed on
      * @param explanation String explanation of why the Interceptor failed
      */
-    public InterceptorException( Interceptor requestProcessor,
-                                      Invocation request, String explanation )
+    public InterceptorException( Interceptor interceptor,
+                                      Invocation invocation, String explanation )
     {
         super( explanation, ResultCodeEnum.OTHER );
-        this.call = request;
-        this.requestProcessor = requestProcessor;
+        this.invocation = invocation;
+        this.interceptor = interceptor;
     }
 
 
     /**
      * Creates an InterceptorException without a message.
      *
-     * @param requestProcessor the Interceptor causing the failure
+     * @param interceptor the Interceptor causing the failure
      * @param invocation the Invocation the Interceptor failed on
      * @param rootCause the root cause of this exception
      */
-    public InterceptorException( Interceptor requestProcessor,
-                                      Invocation request, Throwable rootCause )
+    public InterceptorException( Interceptor interceptor,
+                                      Invocation invocation, Throwable rootCause )
     {
-        this( requestProcessor, request );
+        this( interceptor, invocation );
         super.setRootCause( rootCause );
     }
 
     /**
      * Creates an InterceptorException without a message.
      *
-     * @param requestProcessor the Interceptor causing the failure
+     * @param interceptor the Interceptor causing the failure
      * @param invocation the Invocation the Interceptor failed on
      * @param explanation String explanation of why the Interceptor failed
      * @param rootCause the root cause of this exception
      */
-    public InterceptorException( Interceptor requestProcessor,
-                                      Invocation request,
+    public InterceptorException( Interceptor interceptor,
+                                      Invocation invocation,
                                       String explanation,
                                       Throwable rootCause )
     {
-        this( requestProcessor, request, explanation );
+        this( interceptor, invocation, explanation );
         super.setRootCause( rootCause );
     }
 
@@ -109,7 +110,7 @@
      */
     public Invocation getInvocation()
     {
-        return call;
+        return invocation;
     }
 
 
@@ -118,9 +119,9 @@
      *
      * @return the interceptor this exception is associated with
      */
-    public Interceptor getRequestProcessor()
+    public Interceptor getInterceptor()
     {
-        return requestProcessor;
+        return interceptor;
     }
 
 

Modified: directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/NextInterceptor.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/NextInterceptor.java?view=diff&r1=158446&r2=158447
==============================================================================
--- directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/NextInterceptor.java
(original)
+++ directory/apacheds/branches/interceptor_revamp/core/src/main/java/org/apache/ldap/server/jndi/invocation/interceptor/NextInterceptor.java
Mon Mar 21 03:06:39 2005
@@ -1,9 +1,49 @@
+/*
+ *   Copyright 2004 The Apache Software Foundation
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ *
+ */
 package org.apache.ldap.server.jndi.invocation.interceptor;
 
 import javax.naming.NamingException;
 
 import org.apache.ldap.server.jndi.invocation.Invocation;
 
+/**
+ * Represents the next {@link Interceptor} in the interceptor chain.
+ * {@link Interceptor}s should usually pass the control of current invocation
+ * to the next {@link Interceptor} by calling
+ * <code>nextInterceptor.process(invocation)</code>.
+ * This method returns when the next interceptor's
+ * {@link Interceptor#process(NextInterceptor, Invocation)} returns.
+ * You can therefore implement pre-, post-, around- invocation
+ * handler by how you place the statement. 
+ * 
+ * @author The Apache Directory Project (dev@directory.apache.org)
+ * @author Trustin Lee (trustin@apache.org)
+ * @version $Rev$, $Date$
+ * 
+ * @see Interceptor
+ * @see InterceptorChain
+ */
 public interface NextInterceptor {
+    /**
+     * Passes the control of current invocation to the next
+     * {@link Interceptor} in the {@link InterceptorChain}.
+     * 
+     * @param call
+     * @throws NamingException
+     */
     void process( Invocation call ) throws NamingException;
 }



Mime
View raw message