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
`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
`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`