directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From trus...@apache.org
Subject svn commit: r193121 - in /directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor: BaseInterceptor.java Interceptor.java InterceptorChain.java InterceptorException.java NextInterceptor.java
Date Thu, 23 Jun 2005 09:34:34 GMT
Author: trustin
Date: Thu Jun 23 02:34:32 2005
New Revision: 193121

URL: http://svn.apache.org/viewcvs?rev=193121&view=rev
Log:
* Revised JavaDoc for interceptor package.

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

Modified: directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/BaseInterceptor.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/BaseInterceptor.java?rev=193121&r1=193120&r2=193121&view=diff
==============================================================================
--- directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/BaseInterceptor.java
(original)
+++ directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/BaseInterceptor.java
Thu Jun 23 02:34:32 2005
@@ -20,6 +20,7 @@
 import java.util.Iterator;
 import java.util.Map;
 
+import javax.naming.Context;
 import javax.naming.Name;
 import javax.naming.NamingEnumeration;
 import javax.naming.NamingException;
@@ -31,34 +32,15 @@
 import org.apache.ldap.common.filter.ExprNode;
 import org.apache.ldap.server.authn.LdapPrincipal;
 import org.apache.ldap.server.configuration.InterceptorConfiguration;
-import org.apache.ldap.server.invocation.Invocation;
 import org.apache.ldap.server.invocation.InvocationStack;
 import org.apache.ldap.server.jndi.ContextFactoryConfiguration;
 import org.apache.ldap.server.jndi.ServerContext;
 
 
 /**
- * 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 correspond 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
- * scenes.
+ * A easy-to-use implementation of {@link Interceptor}.  All methods are
+ * implemented to pass the flow of control to next interceptor by defaults.
+ * Please override the methods you have concern in.
  *
  * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
  * @version $Rev$, $Date$
@@ -66,9 +48,7 @@
 public abstract class BaseInterceptor implements Interceptor
 {
     /**
-     * Gets the call's current context's Principal.
-     *
-     * @return the principal making the call
+     * Returns {@link LdapPrincipal} of current context.
      */
     public static LdapPrincipal getPrincipal()
     {
@@ -76,22 +56,34 @@
         return ctx.getPrincipal();
     }
     
+    /**
+     * Returns the current JNDI {@link Context}.
+     */
     public static LdapContext getContext()
     {
         return ( LdapContext ) InvocationStack.getInstance().peek().getTarget();
     }
 
 
+    /**
+     * Creates a new instance.
+     */
     protected BaseInterceptor()
     {
     }
 
 
+    /**
+     * This method does nothing by default.
+     */
     public void init( ContextFactoryConfiguration factoryCfg, InterceptorConfiguration cfg
) throws NamingException
     {
     }
 
 
+    /**
+     * This method does nothing by default.
+     */
     public void destroy()
     {
     }

Modified: directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/Interceptor.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/Interceptor.java?rev=193121&r1=193120&r2=193121&view=diff
==============================================================================
--- directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/Interceptor.java
(original)
+++ directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/Interceptor.java
Thu Jun 23 02:34:32 2005
@@ -29,49 +29,51 @@
 
 import org.apache.ldap.common.filter.ExprNode;
 import org.apache.ldap.server.configuration.InterceptorConfiguration;
-import org.apache.ldap.server.configuration.StartupConfiguration;
-import org.apache.ldap.server.invocation.Invocation;
 import org.apache.ldap.server.jndi.ContextFactoryConfiguration;
 import org.apache.ldap.server.partition.ContextPartition;
+import org.apache.ldap.server.partition.ContextPartitionNexus;
 
 
 /**
- * Filters any directory operations.  You can filter any {@link Invocation}
- * performed on {@link ContextPartition}s just like Servlet filters do.
- * <p/>
- * <h2>Interceptor Chaining</h2> Interceptors should usually pass the control
- * of current invocation to the next interceptor by calling
- * {@link NextInterceptor#process(Invocation)}. The flow control is returned
- * 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.
+ * Filters invocations on {@link ContextPartitionNexus}.  {@link Interceptor}
+ * filters most method calls performed on {@link ContextPartitionNexus} just
+ * like Servlet filters do.
+ * <p/>
+ * <h2>Interceptor Chaining</h2>
+ * 
+ * Interceptors should usually pass the control
+ * of current invocation to the next interceptor by calling an appropriate method
+ * on {@link NextInterceptor}.  The flow control is returned when the next 
+ * interceptor's filter method returns. You can therefore implement pre-, post-,
+ * around- invocation handler by how you place the statement.  Otherwise, you
+ * can transform the invocation into other(s).
  * <p/>
  * <h3>Pre-invocation Filtering</h3>
  * <pre>
- * public void process( NextInterceptor nextInterceptor, Invocation invocation )
+ * public void delete( NextInterceptor nextInterceptor, Name name )
  * {
  *     System.out.println( "Starting invocation." );
- *     nextInterceptor.process( invocation );
+ *     nextInterceptor.delete( name );
  * }
  * </pre>
  * <p/>
  * <h3>Post-invocation Filtering</h3>
  * <pre>
- * public void process( NextInterceptor nextInterceptor, Invocation invocation )
+ * public void delete( NextInterceptor nextInterceptor, Name name )
  * {
- *     nextInterceptor.process( invocation );
+ *     nextInterceptor.delete( name );
  *     System.out.println( "Invocation ended." );
  * }
  * </pre>
  * <p/>
  * <h3>Around-invocation Filtering</h3>
  * <pre>
- * public void process( NextInterceptor nextInterceptor, Invocation invocation )
+ * public void delete( NextInterceptor nextInterceptor, Name name )
  * {
  *     long startTime = System.currentTimeMillis();
  *     try
  *     {
- *         nextInterceptor.process( invocation );
+ *         nextInterceptor.delete( name );
  *     }
  *     finally
  *     {
@@ -81,21 +83,15 @@
  * }
  * </pre>
  * <p/>
- * <h2>Interceptor Naming Convention</h2>
- * <p/>
- * When you create an implementation of Interceptor, you have to follow the
- * basic class naming convention to avoid others' confusion:
- * <ul>
- *  <li>Class name must be an agent noun or end with <code>Interceptor</code>
or
- * <code>Service</code>.</li>
- * </ul>
- * Plus, placing your interceptor implementations into relavent packages like
- * <code>interceptor</code> or ones that reflect its purpose would be a good
- * practice.
- * <p/>
- * <h2>Overriding Default Interceptor Settings</h2>
- * <p/>
- * See {@link StartupConfiguration}.
+ * <h3>Transforming invocations</h3>
+ * <pre>
+ * public void delete( NextInterceptor nextInterceptor, Name name )
+ * {
+ *     // transform deletion into modification.
+ *     Attribute mark = new BasicAttribute( "entryDeleted", "true" );
+ *     nextInterceptor.modify( name, DirContext.REPLACE_ATTRIBUTE, mark );
+ * }
+ * </pre>
  *
  * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
  * @version $Rev$, $Date$
@@ -104,38 +100,86 @@
 public interface Interceptor
 {
     /**
-     * Intializes this interceptor.  This is invoked by directory
-     * service provider when this intercepter is loaded into interceptor chain.
-     *
-     * @param context the configuration properties for this interceptor
-     * @throws NamingException if failed to initialize this interceptor
+     * Intializes this interceptor.  This is invoked by context factory
+     * when this intercepter is loaded into interceptor chain.
      */
     void init( ContextFactoryConfiguration factoryCfg, InterceptorConfiguration cfg ) throws
NamingException;
 
 
     /**
-     * Deinitializes this interceptor.  This is invoked by directory
-     * service provider when this intercepter is unloaded from interceptor chain.
+     * Deinitializes this interceptor.  This is invoked by context factory
+     * when this intercepter is unloaded from interceptor chain.
      */
     void destroy();
 
+    /**
+     * Filters {@link ContextPartitionNexus#getRootDSE()} call.
+     */
     Attributes getRootDSE( NextInterceptor next ) throws NamingException; 
+    /**
+     * Filters {@link ContextPartitionNexus#getMatchedDn(Name, boolean)} call.
+     */
     Name getMatchedDn( NextInterceptor next, Name dn, boolean normalized ) throws NamingException;
+    /**
+     * Filters {@link ContextPartitionNexus#getSuffix(Name, boolean)} call.
+     */
     Name getSuffix( NextInterceptor next, Name dn, boolean normalized ) throws NamingException;
+    /**
+     * Filters {@link ContextPartitionNexus#listSuffixes(boolean)} call.
+     */
     Iterator listSuffixes( NextInterceptor next, boolean normalized ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#delete(Name)} call.
+     */
     void delete( NextInterceptor next, Name name ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#add(String, Name, Attributes)} call.
+     */
     void add( NextInterceptor next, String upName, Name normName, Attributes entry ) throws
NamingException;
+    /**
+     * Filters {@link ContextPartition#modify(Name, int, Attributes)} call.
+     */
     void modify( NextInterceptor next, Name name, int modOp, Attributes mods ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#modify(Name, ModificationItem[])} call.
+     */
     void modify( NextInterceptor next, Name name, ModificationItem [] mods ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#list(Name)} call.
+     */
     NamingEnumeration list( NextInterceptor next, Name base ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#search(Name, Map, ExprNode, SearchControls)} call.
+     */
     NamingEnumeration search( NextInterceptor next, Name base, Map env, ExprNode filter,
                               SearchControls searchCtls ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#lookup(Name)} call.
+     */
     Attributes lookup( NextInterceptor next, Name name ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#lookup(Name, String[])} call.
+     */
     Attributes lookup( NextInterceptor next, Name dn, String [] attrIds ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#lookup(Name, String[])} call.
+     */
     boolean hasEntry( NextInterceptor next, Name name ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#isSuffix(Name)} call.
+     */
     boolean isSuffix( NextInterceptor next, Name name ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#modifyRn(Name, String, boolean)} call.
+     */
     void modifyRn( NextInterceptor next, Name name, String newRn, boolean deleteOldRn ) throws
NamingException;
+    /**
+     * Filters {@link ContextPartition#move(Name, Name)} call.
+     */
     void move( NextInterceptor next, Name oriChildName, Name newParentName ) throws NamingException;
+    /**
+     * Filters {@link ContextPartition#move(Name, Name, String, boolean)} call.
+     */
     void move( NextInterceptor next, Name oriChildName, Name newParentName, String newRn,
                boolean deleteOldRn ) throws NamingException;
 }

Modified: directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/InterceptorChain.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/InterceptorChain.java?rev=193121&r1=193120&r2=193121&view=diff
==============================================================================
--- directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/InterceptorChain.java
(original)
+++ directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/InterceptorChain.java
Thu Jun 23 02:34:32 2005
@@ -40,9 +40,7 @@
 
 
 /**
- * Manages the chain of {@link Interceptor}s.  <tt>InterceptorChain</tt>
- * is also an {@link Interceptor}, and thus you can create hiararchical
- * interceptor structure to break down complex interceptors.
+ * Manages the chain of {@link Interceptor}s.
  *
  * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
  * @version $Rev$, $Date$
@@ -189,7 +187,8 @@
 
 
     /**
-     * Initializes all interceptors this chain contains.
+     * Initializes and registers all interceptors according to the specified
+     * {@link ContextFactoryConfiguration}.
      */
     public synchronized void init( ContextFactoryConfiguration factoryCfg ) throws NamingException
     {
@@ -227,7 +226,7 @@
 
 
     /**
-     * Deinitializes all interceptors this chain contains.
+     * Deinitializes and deregisters all interceptors this chain contains.
      */
     public synchronized void destroy()
     {
@@ -260,8 +259,7 @@
 
 
     /**
-     * Adds the specified interceptor with the specified name at the end of this chain.
-     * @throws NamingException 
+     * Adds and initializes an interceptor with the specified configuration.
      */
     private void register( InterceptorConfiguration cfg ) throws NamingException
     {
@@ -271,8 +269,7 @@
 
 
     /**
-     * Removes the interceptor with the specified name from this chain.
-     * @throws ConfigurationException 
+     * Removes and deinitializes the interceptor with the specified configuration.
      */
     private void deregister( InterceptorConfiguration cfg ) throws ConfigurationException
     {

Modified: directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/InterceptorException.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/InterceptorException.java?rev=193121&r1=193120&r2=193121&view=diff
==============================================================================
--- directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/InterceptorException.java
(original)
+++ directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/InterceptorException.java
Thu Jun 23 02:34:32 2005
@@ -17,19 +17,17 @@
 package org.apache.ldap.server.interceptor;
 
 
-import org.apache.ldap.common.exception.LdapException;
-import org.apache.ldap.common.exception.LdapNamingException;
-import org.apache.ldap.common.message.ResultCodeEnum;
-import org.apache.ldap.server.invocation.Invocation;
+import javax.naming.NamingException;
 
 
 /**
- * A {@link LdapNamingException} that wraps uncaught runtime exceptions thrown from {@link
Interceptor}s.
+ * A {@link NamingException} that wraps uncaught runtime exceptions thrown
+ * from {@link Interceptor}s.
  *
  * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
  * @version $Rev$, $Date$
  */
-public class InterceptorException extends LdapNamingException
+public class InterceptorException extends NamingException
 {
     private static final long serialVersionUID = 3258690996517746233L;
 
@@ -46,7 +44,6 @@
      */
     public InterceptorException( Interceptor interceptor )
     {
-        super( ResultCodeEnum.OTHER );
         this.interceptor = interceptor;
     }
 
@@ -59,7 +56,7 @@
      */
     public InterceptorException( Interceptor interceptor, String explanation )
     {
-        super( explanation, ResultCodeEnum.OTHER );
+        super( explanation );
         this.interceptor = interceptor;
     }
 
@@ -100,21 +97,5 @@
     public Interceptor getInterceptor()
     {
         return interceptor;
-    }
-
-
-    /**
-     * Will return the resultCode of the root cause if the root cause implements LdapException.
-     *
-     * @see org.apache.ldap.common.exception.LdapException#getResultCode()
-     */
-    public ResultCodeEnum getResultCode()
-    {
-        if ( getRootCause() != null && ( getRootCause() instanceof LdapException
) )
-        {
-            return ( ( LdapException ) getRootCause() ).getResultCode();
-        }
-
-        return super.getResultCode();
     }
 }

Modified: directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/NextInterceptor.java
URL: http://svn.apache.org/viewcvs/directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/NextInterceptor.java?rev=193121&r1=193120&r2=193121&view=diff
==============================================================================
--- directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/NextInterceptor.java
(original)
+++ directory/apacheds/branches/db_refactor/core/src/main/java/org/apache/ldap/server/interceptor/NextInterceptor.java
Thu Jun 23 02:34:32 2005
@@ -31,32 +31,83 @@
 
 
 /**
- * Represents the next {@link org.apache.ldap.server.interceptor.Interceptor} in the interceptor
chain.
+ * Represents the next {@link Interceptor} in the interceptor chain.
  *
  * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
  * @version $Rev$, $Date$
- * @see org.apache.ldap.server.interceptor.Interceptor
- * @see org.apache.ldap.server.interceptor.InterceptorChain
+ * @see Interceptor
+ * @see InterceptorChain
  */
 public interface NextInterceptor
 {
+    /**
+     * Calls the next interceptor's {@link Interceptor#getRootDSE(NextInterceptor)}.
+     */
     Attributes getRootDSE() throws NamingException; 
+    /**
+     * Calls the next interceptor's {@link Interceptor#getMatchedDn(NextInterceptor, Name,
boolean)}.
+     */
     Name getMatchedDn( Name dn, boolean normalized ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#getSuffix(NextInterceptor, Name, boolean)}.
+     */
     Name getSuffix( Name dn, boolean normalized ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#listSuffixes(NextInterceptor, boolean)}.
+     */
     Iterator listSuffixes( boolean normalized ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#delete(NextInterceptor, Name)}.
+     */
     void delete( Name name ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#add(NextInterceptor, String, Name,
Attributes)}.
+     */
     void add( String upName, Name normName, Attributes entry ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#modify(NextInterceptor, Name, int,
Attributes)}.
+     */
     void modify( Name name, int modOp, Attributes mods ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#modify(NextInterceptor, Name, ModificationItem[])}.
+     */
     void modify( Name name, ModificationItem [] mods ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#list(NextInterceptor, Name)}.
+     */
     NamingEnumeration list( Name base ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#search(NextInterceptor, Name, Map,
ExprNode, SearchControls)}.
+     */
     NamingEnumeration search( Name base, Map env, ExprNode filter,
                               SearchControls searchCtls ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#lookup(NextInterceptor, Name)}.
+     */
     Attributes lookup( Name name ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#lookup(NextInterceptor, Name, String[])}.
+     */
     Attributes lookup( Name dn, String [] attrIds ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#hasEntry(NextInterceptor, Name)}.
+     */
     boolean hasEntry( Name name ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#isSuffix(NextInterceptor, Name)}.
+     */
     boolean isSuffix( Name name ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#modifyRn(NextInterceptor, Name, String,
boolean)}.
+     */
     void modifyRn( Name name, String newRn, boolean deleteOldRn ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#move(NextInterceptor, Name, Name)}.
+     */
     void move( Name oriChildName, Name newParentName ) throws NamingException;
+    /**
+     * Calls the next interceptor's {@link Interceptor#move(NextInterceptor, Name, Name,
String, boolean)}.
+     */
     void move( Name oriChildName, Name newParentName, String newRn,
                boolean deleteOldRn ) throws NamingException;
 }



Mime
View raw message