## com.sun.grizzly.suspendable
Class SuspendableFilter<T>

    java.lang.Object
      com.sun.grizzly.suspendable.SuspendableFilter<T>

All Implemented Interfaces:
  ProtocolFilter

    public class SuspendableFilter<T>

extends Object
implements ProtocolFilter

Suspend the processing of the request and associated `ProtocolChain`

When a connection is suspended, the framework will not continue the execution of the ProtocolChain and its associated `ProtocolFilter`. Instead the framework will wait until either `Suspendable.resume()` is called, `Suspendable.cancel()` is called or the passed timeout expires. If `Suspendable.resume()` is called or the timeout expires then the ProtocolChain will be resumed from where it has been suspended. If `Suspendable.cancel()` is called, the ProtocolChain execution will not be interrupted and the connection automatically closed.

A connection can be suspended before (`#Suspend.BEFORE`) the ProtocolChain invoke the next ProtocolFilter, or after (`#Suspend.AFTER`) all ProtocolFilter has been called (e.g. when `postExecute(com.sun.grizzly.Context)` is invoked).

This ProtocolFilter must always be invoked after some read operation has occurred.

A common usage of SuspendableFilter could be:

            final ProtocolFilter readFilter = new ReadFilter();
            final SuspendableFilter suspendFilter = new SuspendableFilter();
            final ProtocolFilter yourProtocolFilter = new YourProtocolFilter();

            Suspendable suspendable =
              suspendFilter.suspend("YOUR TOKEN", timeout, attachment, new SuspendableHandler() {

                public void interupted(A attachment) {
                    // Add if you need write something before the connection get closed
                }

                public void resumed(A attachment) {
                    // When the connection is resumed
                }

                public void expired(A attachment) {
                    // When the connection is expired.
            }, #Suspend);

     As an example, all client that send the bytes 'grizzly is cool' will be
     suspended for 5 seconds before the {@link EchoFilter} is called.

            final ProtocolFilter readFilter = new ReadFilter();
            final SuspendableFilter suspendFilter = new SuspendableFilter();
            final ProtocolFilter echoFilter = new EchoFilter();

            suspendable
                    = suspendFilter.suspend("grizzly is cool", 5000, null, new SuspendableHandler() {

                public void interupted(Object attachment) {
                    System.out.println("interrupted");
                }

                public void resumed(Object attachment) {
                    System.out.println("resumed");
                }

                public void expired(Object attachment) {
                    System.out.println("expired");
                }
            }, Suspend.BEFORE);

TODO: Add a better patern matching algorithm Allow OP_WRITE operation to be suspended as well.

Since:
  1.7.3
Author:
  Jeanfrancois Arcand

Nested Class Summary
`protected class` `SuspendableFilter.KeyHandler` Struc to keep state of the current suspended Connection.
`static class` `SuspendableFilter.Suspend` Suspend the connection BEFORE of AFTER
`protected class` `SuspendableFilter.SuspendableHandlerWrapper<A>` Wrapper class around a `SuspendableHandler` with add some connection state.

Field Summary
`protected ConcurrentHashMap<SelectionKey,SuspendableFilter.KeyHandler>` `suspendedKeys` The current list of suspended `SelectionKey`.

Fields inherited from interface com.sun.grizzly.ProtocolFilter
`SUCCESSFUL_READ`

Constructor Summary
`SuspendableFilter()`
`SuspendableFilter(int nextFilterPosition)` Create a new SuspendableFilter, and resume its associated `DefaultProtocolChain` from position `nextFilterPosition`

Method Summary
`protected void` `cancel(SelectionKey key)` Cancel the connection by internalling cancelling the associated `ReadableChannel` and it associated `SelectionKey`
`boolean` `execute(Context ctx)` Excute the pattern matching algorithm to determine if a the current connection must be suspended or not, and when.
`boolean` `postExecute(Context ctx)` Excute the pattern matching algorithm to determine if a the current connection must be suspended or not, and when.
`protected boolean` `resume(SelectionKey key)` Resume the connection by register back the SelectionKey for OP event.
`Suspendable` `suspend(String match)` Suspend a connection based on a String.
`Suspendable` `suspend(String match, long expireTime, T attachement, SuspendableHandler<? extends T> sh)` Suspend a connection based on a String.
`Suspendable` `suspend(String match, long expireTime, T attachement, SuspendableHandler<? extends T> sh, SuspendableFilter.Suspend suspendWhen)` Suspend a connection based on a String.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### suspendedKeys

    protected ConcurrentHashMap<SelectionKey,SuspendableFilter.KeyHandler> suspendedKeys

  The current list of suspended `SelectionKey`.

Constructor Detail

### SuspendableFilter

    public SuspendableFilter()

### SuspendableFilter

    public SuspendableFilter(int nextFilterPosition)

  Create a new SuspendableFilter, and resume its associated `DefaultProtocolChain` from position `nextFilterPosition`

  Parameters:
    `nextFilterPosition` - `nextFilterPosition`

Method Detail

### suspend

    public Suspendable suspend(String match)

  Suspend a connection based on a String. Evevry bytes read from the connection will be inspected and if the String match, the connection will be suspended.

  Parameters:
    `match` - The String used to decide if a connection and its associated bytes need to be suspended. By default, the connection will be resumed after 60 seconds.
  Returns:
    A `Suspendable`

### suspend

    public Suspendable suspend(String match,
                               long expireTime,
                               T attachement,
                               SuspendableHandler<? extends T> sh)

  Suspend a connection based on a String. Evevry bytes read from the connection will be inspected and if the String match, the connection will be suspended.

  Parameters:
    `match` - The String used to decide if a connection and its associated bytes need to be suspended.
    `expireTime` - the time in milliseconds before a connection is resumed.
    `attachment` - The object that will be returned when the `SuspendableHandler` methods are invoked.
    `handler` - A `SuspendableHandler` used to get notification about the suspended connection state.
  Returns:
    A `Suspendable`

### suspend

    public Suspendable suspend(String match,
                               long expireTime,
                               T attachement,
                               SuspendableHandler<? extends T> sh,
                               SuspendableFilter.Suspend suspendWhen)

  Suspend a connection based on a String. Evevry bytes read from the connection will be inspected and if the String match, the connection will be suspended.

  Parameters:
    `match` - The String used to decide if a connection and its associated bytes need to be suspended.
    `expireTime` - the time in milliseconds before a connection is resumed.
    `attachment` - The object that will be returned when the `SuspendableHandler` methods are invoked.
    `handler` - A `SuspendableHandler` used to get notification about the suspended connection state.
    `suspendWhen` - Suspend before or after the next ProtocolChain execution,
  Returns:
    A `Suspendable`

### execute

    public boolean execute(Context ctx)
                    throws IOException

  Excute the pattern matching algorithm to determine if a the current connection must be suspended or not, and when.

  Specified by:
    `execute` in interface `ProtocolFilter`
  Parameters:
    `ctx` - The current `Context`
  Returns:
    true if the ProtocolChain should continue its execution, false if the connection has been suspended.
  Throws:
    `IOException`

### postExecute

    public boolean postExecute(Context ctx)
                        throws IOException

  Excute the pattern matching algorithm to determine if a the current connection must be suspended or not, and when.

  Specified by:
    `postExecute` in interface `ProtocolFilter`
  Parameters:
    `ctx` - The current `Context`
  Returns:
    true if the ProtocolChain should continue its execution, false if the connection has been suspended.
  Throws:
    `IOException`

### resume

    protected boolean resume(SelectionKey key)

  Resume the connection by register back the SelectionKey for OP event.

  Parameters:
    `key` -
  Returns:
    true if the connection was resumed.

### cancel

    protected void cancel(SelectionKey key)

  Cancel the connection by internalling cancelling the associated `ReadableChannel` and it associated `SelectionKey`

  Parameters:
    `key` -

Copyright © 2008 SUN Microsystems. All Rights Reserved.