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/03/21 12:06:44 UTC
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
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;
}