org.jboss.netty.handler.traffic

## Class AbstractTrafficShapingHandler

- java.lang.Object
- - org.jboss.netty.channel.SimpleChannelHandler
  - - org.jboss.netty.handler.traffic.AbstractTrafficShapingHandler

- All Implemented Interfaces:
    ChannelDownstreamHandler, ChannelHandler, ChannelUpstreamHandler, ExternalResourceReleasable
  Direct Known Subclasses:
    ChannelTrafficShapingHandler, GlobalTrafficShapingHandler

      public abstract class AbstractTrafficShapingHandler
      extends SimpleChannelHandler
      implements ExternalResourceReleasable

  AbstractTrafficShapingHandler allows to limit the global bandwidth (see `GlobalTrafficShapingHandler`) or per session bandwidth (see `ChannelTrafficShapingHandler`), as traffic shaping. It allows too to implement an almost real time monitoring of the bandwidth using the monitors from `TrafficCounter` that will call back every checkInterval the method doAccounting of this handler.
  An `ObjectSizeEstimator` can be passed at construction to specify what is the size of the object to be read or write accordingly to the type of object. If not specified, it will used the `DefaultObjectSizeEstimator` implementation.
  If you want for any particular reasons to stop the monitoring (accounting) or to change the read/write limit or the check interval, several methods allow that for you:
  - `configure` allows you to change read or write limits, or the checkInterval
  - `getTrafficCounter` allows you to have access to the TrafficCounter and so to stop or start the monitoring, to change the checkInterval directly, or to have access to its values.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.jboss.netty.channel.ChannelHandler

      `ChannelHandler.Sharable`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `checkInterval` Delay between two performance snapshots
    `static long` | `DEFAULT_CHECK_INTERVAL` Default delay between two checks: 1s
    `protected Timer` | `timer` Timer to associated to any TrafficCounter
    `protected TrafficCounter` | `trafficCounter` Traffic Counter

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractTrafficShapingHandler(ObjectSizeEstimator objectSizeEstimator, Timer timer)` Constructor using the specified ObjectSizeEstimator and using NO LIMIT and default Check Interval
    `AbstractTrafficShapingHandler(ObjectSizeEstimator objectSizeEstimator, Timer timer, long checkInterval)` Constructor using the specified ObjectSizeEstimator and using NO LIMIT
    `AbstractTrafficShapingHandler(ObjectSizeEstimator objectSizeEstimator, Timer timer, long writeLimit, long readLimit)` Constructor using the specified ObjectSizeEstimator and using default Check Interval
    `AbstractTrafficShapingHandler(ObjectSizeEstimator objectSizeEstimator, Timer timer, long writeLimit, long readLimit, long checkInterval)` Constructor using the specified ObjectSizeEstimator
    `AbstractTrafficShapingHandler(Timer timer)` Constructor using default `ObjectSizeEstimator` and using NO LIMIT and default Check Interval
    `AbstractTrafficShapingHandler(Timer timer, long checkInterval)` Constructor using default `ObjectSizeEstimator` and using NO LIMIT
    `AbstractTrafficShapingHandler(Timer timer, long writeLimit, long readLimit)` Constructor using default `ObjectSizeEstimator` and using default Check Interval
    `AbstractTrafficShapingHandler(Timer timer, long writeLimit, long readLimit, long checkInterval)` Constructor using default `ObjectSizeEstimator`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `configure(long newCheckInterval)` Change the check interval.
    `void` | `configure(long newWriteLimit, long newReadLimit)` Change the underlying limitations.
    `void` | `configure(long newWriteLimit, long newReadLimit, long newCheckInterval)` Change the underlying limitations and check interval.
    `protected void` | `doAccounting(TrafficCounter counter)` Called each time the accounting is computed from the TrafficCounters.
    `TrafficCounter` | `getTrafficCounter()`
    `void` | `handleDownstream(ChannelHandlerContext ctx, ChannelEvent e)` Handles the specified downstream event.
    `void` | `messageReceived(ChannelHandlerContext arg0, MessageEvent arg1)` Invoked when a message object (e.g: `ChannelBuffer`) was received from a remote peer.
    `void` | `releaseExternalResources()` Releases the external resources that this object depends on.
    `String` | `toString()`
    `void` | `writeRequested(ChannelHandlerContext arg0, MessageEvent arg1)` Invoked when `Channel.write(Object)` is called.

    - ### Methods inherited from class org.jboss.netty.channel.SimpleChannelHandler

      `bindRequested, channelBound, channelClosed, channelConnected, channelDisconnected, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, closeRequested, connectRequested, disconnectRequested, exceptionCaught, handleUpstream, setInterestOpsRequested, unbindRequested, writeComplete`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_CHECK_INTERVAL

          public static final long DEFAULT_CHECK_INTERVAL

      Default delay between two checks: 1s
      See Also:
        Constant Field Values

    - #### trafficCounter

          protected TrafficCounter trafficCounter

      Traffic Counter

    - #### timer

          protected Timer timer

      Timer to associated to any TrafficCounter

    - #### checkInterval

          protected long checkInterval

      Delay between two performance snapshots

  - ### Constructor Detail

    - #### AbstractTrafficShapingHandler

          public AbstractTrafficShapingHandler(Timer timer,
                                       long writeLimit,
                                       long readLimit,
                                       long checkInterval)

      Constructor using default `ObjectSizeEstimator`
      Parameters:
        `timer` - created once for instance like HashedWheelTimer(10, TimeUnit.MILLISECONDS, 1024)
        `writeLimit` - 0 or a limit in bytes/s
        `readLimit` - 0 or a limit in bytes/s
        `checkInterval` - The delay between two computations of performances for channels or 0 if no stats are to be computed

    - #### AbstractTrafficShapingHandler

          public AbstractTrafficShapingHandler(ObjectSizeEstimator objectSizeEstimator,
                                       Timer timer,
                                       long writeLimit,
                                       long readLimit,
                                       long checkInterval)

      Constructor using the specified ObjectSizeEstimator
      Parameters:
        `objectSizeEstimator` - the `ObjectSizeEstimator` that will be used to compute the size of the message
        `timer` - created once for instance like HashedWheelTimer(10, TimeUnit.MILLISECONDS, 1024)
        `writeLimit` - 0 or a limit in bytes/s
        `readLimit` - 0 or a limit in bytes/s
        `checkInterval` - The delay between two computations of performances for channels or 0 if no stats are to be computed

    - #### AbstractTrafficShapingHandler

          public AbstractTrafficShapingHandler(Timer timer,
                                       long writeLimit,
                                       long readLimit)

      Constructor using default `ObjectSizeEstimator` and using default Check Interval
      Parameters:
        `timer` - created once for instance like HashedWheelTimer(10, TimeUnit.MILLISECONDS, 1024)
        `writeLimit` - 0 or a limit in bytes/s
        `readLimit` - 0 or a limit in bytes/s

    - #### AbstractTrafficShapingHandler

          public AbstractTrafficShapingHandler(ObjectSizeEstimator objectSizeEstimator,
                                       Timer timer,
                                       long writeLimit,
                                       long readLimit)

      Constructor using the specified ObjectSizeEstimator and using default Check Interval
      Parameters:
        `objectSizeEstimator` - the `ObjectSizeEstimator` that will be used to compute the size of the message
        `timer` - created once for instance like HashedWheelTimer(10, TimeUnit.MILLISECONDS, 1024)
        `writeLimit` - 0 or a limit in bytes/s
        `readLimit` - 0 or a limit in bytes/s

    - #### AbstractTrafficShapingHandler

          public AbstractTrafficShapingHandler(Timer timer)

      Constructor using default `ObjectSizeEstimator` and using NO LIMIT and default Check Interval
      Parameters:
        `timer` - created once for instance like HashedWheelTimer(10, TimeUnit.MILLISECONDS, 1024)

    - #### AbstractTrafficShapingHandler

          public AbstractTrafficShapingHandler(ObjectSizeEstimator objectSizeEstimator,
                                       Timer timer)

      Constructor using the specified ObjectSizeEstimator and using NO LIMIT and default Check Interval
      Parameters:
        `objectSizeEstimator` - the `ObjectSizeEstimator` that will be used to compute the size of the message
        `timer` - created once for instance like HashedWheelTimer(10, TimeUnit.MILLISECONDS, 1024)

    - #### AbstractTrafficShapingHandler

          public AbstractTrafficShapingHandler(Timer timer,
                                       long checkInterval)

      Constructor using default `ObjectSizeEstimator` and using NO LIMIT
      Parameters:
        `timer` - created once for instance like HashedWheelTimer(10, TimeUnit.MILLISECONDS, 1024)
        `checkInterval` - The delay between two computations of performances for channels or 0 if no stats are to be computed

    - #### AbstractTrafficShapingHandler

          public AbstractTrafficShapingHandler(ObjectSizeEstimator objectSizeEstimator,
                                       Timer timer,
                                       long checkInterval)

      Constructor using the specified ObjectSizeEstimator and using NO LIMIT
      Parameters:
        `objectSizeEstimator` - the `ObjectSizeEstimator` that will be used to compute the size of the message
        `timer` - created once for instance like HashedWheelTimer(10, TimeUnit.MILLISECONDS, 1024)
        `checkInterval` - The delay between two computations of performances for channels or 0 if no stats are to be computed

  - ### Method Detail

    - #### configure

          public void configure(long newWriteLimit,
                       long newReadLimit,
                       long newCheckInterval)

      Change the underlying limitations and check interval.
      Parameters:
        `newWriteLimit` -
        `newReadLimit` -
        `newCheckInterval` -

    - #### configure

          public void configure(long newWriteLimit,
                       long newReadLimit)

      Change the underlying limitations.
      Parameters:
        `newWriteLimit` -
        `newReadLimit` -

    - #### configure

          public void configure(long newCheckInterval)

      Change the check interval.
      Parameters:
        `newCheckInterval` -

    - #### doAccounting

          protected void doAccounting(TrafficCounter counter)

      Called each time the accounting is computed from the TrafficCounters. This method could be used for instance to implement almost real time accounting.
      Parameters:
        `counter` - the TrafficCounter that computes its performance

    - #### messageReceived

          public void messageReceived(ChannelHandlerContext arg0,
                             MessageEvent arg1)
                               throws Exception

      Description copied from class: `SimpleChannelHandler`
      Invoked when a message object (e.g: `ChannelBuffer`) was received from a remote peer.
      Overrides:
        `messageReceived` in class `SimpleChannelHandler`
      Throws:
        `Exception`

    - #### writeRequested

          public void writeRequested(ChannelHandlerContext arg0,
                            MessageEvent arg1)
                              throws Exception

      Description copied from class: `SimpleChannelHandler`
      Invoked when `Channel.write(Object)` is called.
      Overrides:
        `writeRequested` in class `SimpleChannelHandler`
      Throws:
        `Exception`

    - #### handleDownstream

          public void handleDownstream(ChannelHandlerContext ctx,
                              ChannelEvent e)
                                throws Exception

      Description copied from class: `SimpleChannelHandler`
      Handles the specified downstream event. Down-casts the received downstream event into more meaningful sub-type event and calls an appropriate handler method with the down-casted event.
      Specified by:
        `handleDownstream` in interface `ChannelDownstreamHandler`
      Overrides:
        `handleDownstream` in class `SimpleChannelHandler`
      Parameters:
        `ctx` - the context object for this handler
        `e` - the downstream event to process or intercept
      Throws:
        `Exception`

    - #### getTrafficCounter

          public TrafficCounter getTrafficCounter()

      Returns:
        the current TrafficCounter (if channel is still connected)

    - #### releaseExternalResources

          public void releaseExternalResources()

      Description copied from interface: `ExternalResourceReleasable`
      Releases the external resources that this object depends on. You should not call this method if the external resources (e.g. thread pool) are in use by other objects.
      Specified by:
        `releaseExternalResources` in interface `ExternalResourceReleasable`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright © 2008-2012 The Netty Project. All Rights Reserved.