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/12/01 04:19:35 UTC
svn commit: r350123 - in
/directory/network/branches/chain_refactor/src/java/org/apache/mina/common:
./ support/
Author: trustin
Date: Wed Nov 30 19:19:28 2005
New Revision: 350123
URL: http://svn.apache.org/viewcvs?rev=350123&view=rev
Log:
Revised documentation.
Modified:
directory/network/branches/chain_refactor/src/java/org/apache/mina/common/DefaultIoFilterChainBuilder.java
directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilter.java
directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilterChain.java
directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoSessionManager.java
directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/AbstractIoFilterChain.java
directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoAcceptor.java
directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoConnector.java
directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/IoFilterLifeCycleManager.java
Modified: directory/network/branches/chain_refactor/src/java/org/apache/mina/common/DefaultIoFilterChainBuilder.java
URL: http://svn.apache.org/viewcvs/directory/network/branches/chain_refactor/src/java/org/apache/mina/common/DefaultIoFilterChainBuilder.java?rev=350123&r1=350122&r2=350123&view=diff
==============================================================================
--- directory/network/branches/chain_refactor/src/java/org/apache/mina/common/DefaultIoFilterChainBuilder.java (original)
+++ directory/network/branches/chain_refactor/src/java/org/apache/mina/common/DefaultIoFilterChainBuilder.java Wed Nov 30 19:19:28 2005
@@ -30,7 +30,25 @@
import org.apache.mina.common.IoFilterChain.Entry;
/**
- * TODO Document me
+ * The default implementation of {@link IoFilterChainBuilder} which is useful
+ * in most cases. {@link DefaultIoFilterChainBuilder} has an identical interface
+ * with {@link IoFilter}; it contains a list of {@link IoFilter}s that you can
+ * modify. The {@link IoFilter}s which are added to this builder will be appended
+ * to the {@link IoFilterChain} when {@link #buildFilterChain(IoFilterChain)} is
+ * invoked.
+ * <p>
+ * However, the identical interface doesn't mean that it behaves in an exactly
+ * same way with {@link IoFilterChain}. {@link DefaultIoFilterChainBuilder}
+ * doesn't manage the life cycle of the {@link IoFilter}s at all, and the
+ * existing {@link IoSession}s won't get affected by the changes in this builder.
+ * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
+ *
+ * <pre>
+ * IoAcceptor acceptor = ...;
+ * DefaultIoFilterChainBuilder builder = acceptor.getFilterChain();
+ * builder.addLast( "myFilter", new MyFilter() );
+ * ...
+ * </pre>
*
* @author The Apache Directory Project (dev@directory.apache.org)
* @version $Rev$, $Date$
Modified: directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilter.java
URL: http://svn.apache.org/viewcvs/directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilter.java?rev=350123&r1=350122&r2=350123&view=diff
==============================================================================
--- directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilter.java (original)
+++ directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilter.java Wed Nov 30 19:19:28 2005
@@ -37,6 +37,8 @@
* session, which might malfunction if any filters are added or removed later.
*
* <h3>The Life Cycle</h3>
+ * {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
+ * <p>
* When you add an {@link IoFilter} to an {@link IoFilterChain}:
* <ol>
* <li>{@link #init()} is invoked by {@link IoFilterChain} if the filter is
@@ -49,7 +51,7 @@
* threw an exception. {@link #destroy()} is also invoked if the filter
* is the last filter which was added to {@link IoFilterChain}s.</li>
* </ol>
- *
+ * <p>
* When you remove an {@link IoFilter} from an {@link IoFilterChain}:
* <ol>
* <li>The filter is removed from the chain, and any events and I/O requests
@@ -63,8 +65,6 @@
* @version $Rev$, $Date$
*
* @see IoFilterAdapter
- *
- * TODO The better life cycle management (util class)
*/
public interface IoFilter
{
Modified: directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilterChain.java
URL: http://svn.apache.org/viewcvs/directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilterChain.java?rev=350123&r1=350122&r2=350123&view=diff
==============================================================================
--- directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilterChain.java (original)
+++ directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoFilterChain.java Wed Nov 30 19:19:28 2005
@@ -25,6 +25,7 @@
/**
* A container of {@link IoFilter}s that forwards {@link IoHandler} events
* to the consisting filters and terminal {@link IoHandler} sequentially.
+ * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship).
*
* @author The Apache Directory Project (dev@directory.apache.org)
* @version $Rev$, $Date$
Modified: directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoSessionManager.java
URL: http://svn.apache.org/viewcvs/directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoSessionManager.java?rev=350123&r1=350122&r2=350123&view=diff
==============================================================================
--- directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoSessionManager.java (original)
+++ directory/network/branches/chain_refactor/src/java/org/apache/mina/common/IoSessionManager.java Wed Nov 30 19:19:28 2005
@@ -34,15 +34,17 @@
public interface IoSessionManager {
/**
- * Returns the {@link IoFilterChain} which will affect the {@link IoFilterChain}
- * of all {@link IoSession}s which is managed by this manager.
+ * Returns the {@link IoFilterChainBuilder} which will modify the
+ * {@link IoFilterChain} of all {@link IoSession}s which is managed
+ * by this manager.
* The default value is an empty {@link DefaultIoFilterChainBuilder}.
*/
IoFilterChainBuilder getFilterChainBuilder();
/**
- * Sets the {@link IoFilterChain} which will affect the {@link IoFilterChain}
- * of all {@link IoSession}s which is managed by this manager.
+ * Sets the {@link IoFilterChainBuilder} which will modify the
+ * {@link IoFilterChain} of all {@link IoSession}s which is managed
+ * by this manager.
* If you specify <tt>null</tt> this property will be set to
* an empty {@link DefaultIoFilterChainBuilder}.
*/
@@ -50,8 +52,11 @@
/**
* A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>.
- * Please note that the returned object is not a <b>real</b> {2link IoFilterChain}.
- *
+ * Please note that the returned object is not a <b>real</b> {@link IoFilterChain}
+ * but a {@link DefaultIoFilterChainBuilder}. Modifying the returned builder
+ * won't affect the existing {@link IoSession}s at all, because
+ * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
+ *
* @throws IllegalStateException if the current {@link IoFilterChainBuilder} is
* not a {@link DefaultIoFilterChainBuilder}
*/
Modified: directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/AbstractIoFilterChain.java
URL: http://svn.apache.org/viewcvs/directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/AbstractIoFilterChain.java?rev=350123&r1=350122&r2=350123&view=diff
==============================================================================
--- directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/AbstractIoFilterChain.java (original)
+++ directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/AbstractIoFilterChain.java Wed Nov 30 19:19:28 2005
@@ -38,7 +38,7 @@
/**
* An abstract implementation of {@link IoFilterChain} that provides
- * common operations for developers to extend protocol layer.
+ * common operations for developers to implement their own transport layer.
* <p>
* The only method a developer should implement is
* {@link #doWrite(IoSession, WriteRequest)}. This method is invoked
Modified: directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoAcceptor.java
URL: http://svn.apache.org/viewcvs/directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoAcceptor.java?rev=350123&r1=350122&r2=350123&view=diff
==============================================================================
--- directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoAcceptor.java (original)
+++ directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoAcceptor.java Wed Nov 30 19:19:28 2005
@@ -46,7 +46,8 @@
}
/**
- * Sets the delegate.
+ * Sets the delegate. This method should be invoked before any operations
+ * is requested.
*/
protected void init( IoAcceptor delegate )
{
Modified: directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoConnector.java
URL: http://svn.apache.org/viewcvs/directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoConnector.java?rev=350123&r1=350122&r2=350123&view=diff
==============================================================================
--- directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoConnector.java (original)
+++ directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/DelegatedIoConnector.java Wed Nov 30 19:19:28 2005
@@ -46,7 +46,8 @@
}
/**
- * Sets the delegate.
+ * Sets the delegate. This method should be invoked before any operation
+ * is requested.
*/
protected void init( IoConnector delegate )
{
Modified: directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/IoFilterLifeCycleManager.java
URL: http://svn.apache.org/viewcvs/directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/IoFilterLifeCycleManager.java?rev=350123&r1=350122&r2=350123&view=diff
==============================================================================
--- directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/IoFilterLifeCycleManager.java (original)
+++ directory/network/branches/chain_refactor/src/java/org/apache/mina/common/support/IoFilterLifeCycleManager.java Wed Nov 30 19:19:28 2005
@@ -26,6 +26,12 @@
import org.apache.mina.common.IoFilterLifeCycleException;
import org.apache.mina.common.IoFilter.NextFilter;
+/**
+ * Manages the life cycle of {@link IoFilter}s globally.
+ *
+ * @author The Apache Directory Project (dev@directory.apache.org)
+ * @version $Rev$, $Date$
+ */
public class IoFilterLifeCycleManager
{
private static final IoFilterLifeCycleManager INSTANCE = new IoFilterLifeCycleManager();
@@ -131,6 +137,7 @@
}
}
+ /** Maintains the reference count of an {@link IoFilter}. */
private static class ReferenceCount
{
private int count;