directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From erodrig...@apache.org
Subject svn commit: r351782 - in /directory/network/trunk/src/java/org/apache/mina/handler/chain: Chain.java Command.java Context.java Filter.java
Date Fri, 02 Dec 2005 17:58:17 GMT
Author: erodriguez
Date: Fri Dec  2 09:58:10 2005
New Revision: 351782

URL: http://svn.apache.org/viewcvs?rev=351782&view=rev
Log:
Interfaces for handler chains.

Added:
    directory/network/trunk/src/java/org/apache/mina/handler/chain/Chain.java   (with props)
    directory/network/trunk/src/java/org/apache/mina/handler/chain/Command.java   (with props)
    directory/network/trunk/src/java/org/apache/mina/handler/chain/Context.java   (with props)
    directory/network/trunk/src/java/org/apache/mina/handler/chain/Filter.java   (with props)

Added: directory/network/trunk/src/java/org/apache/mina/handler/chain/Chain.java
URL: http://svn.apache.org/viewcvs/directory/network/trunk/src/java/org/apache/mina/handler/chain/Chain.java?rev=351782&view=auto
==============================================================================
--- directory/network/trunk/src/java/org/apache/mina/handler/chain/Chain.java (added)
+++ directory/network/trunk/src/java/org/apache/mina/handler/chain/Chain.java Fri Dec  2 09:58:10
2005
@@ -0,0 +1,111 @@
+/*
+ *   Copyright 2005 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.mina.handler.chain;
+
+/**
+ * <p>A {@link Chain} represents a configured list of
+ * {@link Command}s that will be executed in order to perform processing
+ * on a specified {@link Context}.  Each included {@link Command} will be
+ * executed in turn, until either one of them returns <code>true</code>,
+ * one of the executed {@link Command}s throws an exception,
+ * or the end of the chain has been reached.  The {@link Chain} itself will
+ * return the return value of the last {@link Command} that was executed
+ * (if no exception was thrown), or rethrow the thrown exception.</p>
+ *
+ * <p>Note that {@link Chain} extends {@link Command}, so that the two can
+ * be used interchangeably when a {@link Command} is expected.  This makes it
+ * easy to assemble workflows in a hierarchical manner by combining subchains
+ * into an overall processing chain.</p>
+ *
+ * <p>To protect applications from evolution of this interface, specialized
+ * implementations of {@link Chain} should generally be created by extending
+ * the provided base class {@link org.apache.mina.handler.chain.impl.ChainBase})
+ * rather than directly implementing this interface.</p>
+ *
+ * <p>{@link Chain} implementations should be designed in a thread-safe
+ * manner, suitable for execution on multiple threads simultaneously.  In
+ * general, this implies that the state information identifying which
+ * {@link Command} is currently being executed should be maintained in a
+ * local variable inside the <code>execute()</code> method, rather than
+ * in an instance variable.  The {@link Command}s in a {@link Chain} may be
+ * configured (via calls to <code>addCommand()</code>) at any time before
+ * the <code>execute()</code> method of the {@link Chain} is first called.
+ * After that, the configuration of the {@link Chain} is frozen.</p>
+ *
+ * @version $Revision: 1.6 $ $Date: 2004/02/25 00:01:07 $
+ */
+public interface Chain extends Command
+{
+    /**
+     * <p>Add a {@link Command} to the list of {@link Command}s that will
+     * be called in turn when this {@link Chain}'s <code>execute()</code>
+     * method is called.  Once <code>execute()</code> has been called
+     * at least once, it is no longer possible to add additional
+     * {@link Command}s; instead, an exception will be thrown.</p>
+     *
+     * @param command The {@link Command} to be added
+     *
+     * @exception IllegalArgumentException if <code>command</code>
+     *  is <code>null</code>
+     * @exception IllegalStateException if this {@link Chain} has already
+     *  been executed at least once, so no further configuration is allowed
+     */
+    void addCommand( Command command );
+
+    /**
+     * <p>Execute the processing represented by this {@link Chain} according
+     * to the following algorithm.</p>
+     * <ul>
+     * <li>If there are no configured {@link Command}s in the {@link Chain},
+     *     return <code>false</code>.</li>
+     * <li>Call the <code>execute()</code> method of each {@link Command}
+     *     configured on this chain, in the order they were added via calls
+     *     to the <code>addCommand()</code> method, until the end of the
+     *     configured {@link Command}s is encountered, or until one of
+     *     the executed {@link Command}s returns <code>true</code>
+     *     or throws an exception.</li>
+     * <li>Walk backwards through the {@link Command}s whose
+     *     <code>execute()</code> methods, starting with the last one that
+     *     was executed.  If this {@link Command} instance is also a
+     *     {@link Filter}, call its <code>postprocess()</code> method,
+     *     discarding any exception that is thrown.</li>
+     * <li>If the last {@link Command} whose <code>execute()</code> method
+     *     was called threw an exception, rethrow that exception.</li>
+     * <li>Otherwise, return the value returned by the <code>execute()</code>
+     *     method of the last {@link Command} that was executed.  This will be
+     *     <code>true</code> if the last {@link Command} indicated that
+     *     processing of this {@link Context} has been completed, or
+     *     <code>false</code> if none of the called {@link Command}s
+     *     returned <code>true</code>.</li>
+     * </ul>
+     *
+     * @param context The {@link Context} to be processed by this
+     *  {@link Chain}
+     *
+     * @exception Exception if thrown by one of the {@link Command}s
+     *  in this {@link Chain} but not handled by a <code>postprocess()</code>
+     *  method of a {@link Filter}
+     * @exception IllegalArgumentException if <code>context</code>
+     *  is <code>null</code>
+     *
+     * @return <code>true</code> if the processing of this {@link Context}
+     *  has been completed, or <code>false</code> if the processing
+     *  of this {@link Context} should be delegated to a subsequent
+     *  {@link Command} in an enclosing {@link Chain}
+     */
+    boolean execute( Context context ) throws Exception;
+}

Propchange: directory/network/trunk/src/java/org/apache/mina/handler/chain/Chain.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: directory/network/trunk/src/java/org/apache/mina/handler/chain/Command.java
URL: http://svn.apache.org/viewcvs/directory/network/trunk/src/java/org/apache/mina/handler/chain/Command.java?rev=351782&view=auto
==============================================================================
--- directory/network/trunk/src/java/org/apache/mina/handler/chain/Command.java (added)
+++ directory/network/trunk/src/java/org/apache/mina/handler/chain/Command.java Fri Dec  2
09:58:10 2005
@@ -0,0 +1,100 @@
+/*
+ *   Copyright 2005 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.mina.handler.chain;
+
+/**
+ * <p>A {@link Command} encapsulates a unit of processing work to be
+ * performed, whose purpose is to examine and/or modify the state of a
+ * transaction that is represented by a {@link Context}.  Individual
+ * {@link Command}s can be assembled into a {@link Chain}, which allows
+ * them to either complete the required processing or delegate further
+ * processing to the next {@link Command} in the {@link Chain}.</p>
+ *
+ * <p>{@link Command} implementations should be designed in a thread-safe
+ * manner, suitable for inclusion in multiple {@link Chain}s that might be
+ * processed by different threads simultaneously.  In general, this implies
+ * that {@link Command} classes should not maintain state information in
+ * instance variables.  Instead, state information should be maintained via
+ * suitable modifications to the attributes of the {@link Context} that is
+ * passed to the <code>execute()</code> command.</p>
+ *
+ * <p>{@link Command} implementations typically retrieve and store state
+ * information in the {@link Context} instance that is passed as a parameter
+ * to the <code>execute()</code> method, using particular keys into the
+ * <code>Map</code> that can be acquired via
+ * <code>Context.getAttributes()</code>.  To improve interoperability of
+ * {@link Command} implementations, a useful design pattern is to expose the
+ * key values used as JavaBeans properties of the {@link Command}
+ * implementation class itself.  For example, a {@link Command} that requires
+ * an input and an output key might implement the following properties:</p>
+ *
+ * <pre>
+ *   private String inputKey = "input";
+ *   public String getInputKey() {
+ *     return (this.inputKey);
+ *   }
+ *   public void setInputKey(String inputKey) {
+ *     this.inputKey = inputKey;
+ *   }
+ *
+ *   private String outputKey = "output";
+ *   public String getOutputKey() {
+ *     return (this.outputKey);
+ *   }
+ *   public void setOutputKey(String outputKey) {
+ *     this.outputKey = outputKey;
+ *   }
+ * </pre>
+ *
+ * <p>And the operation of accessing the "input" information in the context
+ * would be executed by calling:</p>
+ *
+ * <pre>
+ *   String input = (String) context.get(getInputKey());
+ * </pre>
+ *
+ * <p>instead of hard coding the attribute name.  The use of the "Key"
+ * suffix on such property names is a useful convention to identify properties
+ * being used in this fashion, as opposed to JavaBeans properties that simply
+ * configure the internal operation of this {@link Command}.</p>
+ *
+ * @version $Revision: 1.5 $ $Date: 2004/02/25 00:01:07 $
+ */
+public interface Command
+{
+    /**
+     * <p>Execute a unit of processing work to be performed.  This
+     * {@link Command} may either complete the required processing
+     * and return <code>true</code>, or delegate remaining processing
+     * to the next {@link Command} in a {@link Chain} containing this
+     * {@link Command} by returning <code>false</code>
+     *
+     * @param context The {@link Context} to be processed by this
+     *  {@link Command}
+     *
+     * @exception Exception general purpose exception return
+     *  to indicate abnormal termination
+     * @exception IllegalArgumentException if <code>context</code>
+     *  is <code>null</code>
+     *
+     * @return <code>true</code> if the processing of this {@link Context}
+     *  has been completed, or <code>false</code> if the processing
+     *  of this {@link Context} should be delegated to a subsequent
+     *  {@link Command} in an enclosing {@link Chain}
+     */
+    boolean execute( Context context ) throws Exception;
+}

Propchange: directory/network/trunk/src/java/org/apache/mina/handler/chain/Command.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: directory/network/trunk/src/java/org/apache/mina/handler/chain/Context.java
URL: http://svn.apache.org/viewcvs/directory/network/trunk/src/java/org/apache/mina/handler/chain/Context.java?rev=351782&view=auto
==============================================================================
--- directory/network/trunk/src/java/org/apache/mina/handler/chain/Context.java (added)
+++ directory/network/trunk/src/java/org/apache/mina/handler/chain/Context.java Fri Dec  2
09:58:10 2005
@@ -0,0 +1,62 @@
+/*
+ *   Copyright 2005 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.mina.handler.chain;
+
+import java.util.Map;
+
+/**
+ * <p>A {@link Context} represents the state information that is
+ * accessed and manipulated by the execution of a {@link Command} or a
+ * {@link Chain}.  Specialized implementations of {@link Context} will
+ * typically add JavaBeans properties that contain typesafe accessors
+ * to information that is relevant to a particular use case for this
+ * context, and/or add operations that affect the state information
+ * that is saved in the context.</p>
+ *
+ * <p>Implementations of {@link Context} must also implement all of the
+ * required and optional contracts of the <code>java.util.Map</code>
+ * interface.</p>
+ *
+ * <p>It is strongly recommended, but not required, that JavaBeans
+ * properties added to a particular {@link Context} implementation exhibit
+ * <em>Attribute-Property Transparency</em>.  In other words,
+ * a value stored via a call to <code>setFoo(value)</code> should be visible
+ * by calling <code>get("foo")</code>, and a value stored
+ * via a call to <code>put("foo", value)</code> should be
+ * visible by calling <code>getFoo()</code>.  If your {@link Context}
+ * implementation class exhibits this featue, it becomes easier to reuse the
+ * implementation in multiple environments, without the need to cast to a
+ * particular implementation class in order to access the property getter
+ * and setter methods.</p>
+ *
+ * <p>To protect applications from evolution of this interface, specialized
+ * implementations of {@link Context} should generally be created by extending
+ * the provided base class ({@link org.apache.mina.handler.chain.impl.ContextBase})
+ * rather than directly implementing this interface.</p>
+ *
+ * <p>Applications should <strong>NOT</strong> assume that
+ * {@link Context} implementations, or the values stored in its
+ * attributes, may be accessed from multiple threads
+ * simultaneously unless this is explicitly documented for a particular
+ * implementation.</p>
+ *
+ * @version $Revision: 1.6 $ $Date: 2004/02/25 00:01:07 $
+ */
+public interface Context extends Map
+{
+
+}

Propchange: directory/network/trunk/src/java/org/apache/mina/handler/chain/Context.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: directory/network/trunk/src/java/org/apache/mina/handler/chain/Filter.java
URL: http://svn.apache.org/viewcvs/directory/network/trunk/src/java/org/apache/mina/handler/chain/Filter.java?rev=351782&view=auto
==============================================================================
--- directory/network/trunk/src/java/org/apache/mina/handler/chain/Filter.java (added)
+++ directory/network/trunk/src/java/org/apache/mina/handler/chain/Filter.java Fri Dec  2
09:58:10 2005
@@ -0,0 +1,62 @@
+/*
+ *   Copyright 2005 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.mina.handler.chain;
+
+/**
+ * <p>A {@link Filter} is a specialized {@link Command} that also expects
+ * the {@link Chain} that is executing it to call the
+ * <code>postprocess()</code> method if it called the <code>execute()</code>
+ * method.  This promise must be fulfilled in spite of any possible
+ * exceptions thrown by the <code>execute()</code> method of this
+ * {@link Command}, or any subsequent {@link Command} whose
+ * <code>execute()</code> method was called.  The owning {@link Chain}
+ * must call the <code>postprocess()</code> method of each {@link Filter}
+ * in a {@link Chain} in reverse order of the invocation of their
+ * <code>execute()</code> methods.</p>
+ *
+ * <p>The most common use case for a {@link Filter}, as opposed to a
+ * {@link Command}, is where potentially expensive resources must be acquired
+ * and held until the processing of a particular request has been completed,
+ * even it execution is delegated to a subsequent {@link Command} via the
+ * <code>execute()</code> returning <code>false</code>.  A {@link
Filter}
+ * can reliably release such resources in the <code>postprocess()</code>
+ * method, which is guaranteed to be called by the owning {@link Chain}.</p>
+ *
+ * @version $Revision: 1.6 $ $Date: 2004/11/30 05:52:23 $
+ */
+public interface Filter extends Command
+{
+    /**
+     * <p>Execute any cleanup activities, such as releasing resources that
+     * were acquired during the <code>execute()</code> method of this
+     * {@link Filter} instance.</p>
+     *
+     * @param context The {@link Context} to be processed by this
+     *  {@link Filter}
+     * @param exception The <code>Exception</code> (if any) that was thrown
+     *  by the last {@link Command} that was executed; otherwise
+     *  <code>null</code>
+     *
+     * @exception IllegalArgumentException if <code>context</code>
+     *  is <code>null</code>
+     *
+     * @return If a non-null <code>exception</code> was "handled" by this
+     *  method (and therefore need not be rethrown), return <code>true</code>;
+     *  otherwise return <code>false</code>
+     */
+    boolean postprocess( Context context, Exception exception );
+}

Propchange: directory/network/trunk/src/java/org/apache/mina/handler/chain/Filter.java
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message