You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by tr...@apache.org on 2005/06/23 11:34:34 UTC
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
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;
}