io.netty.channel

Class MessageList<T>

java.lang.Object

io.netty.channel.MessageList<T>

Type Parameters:

T - the type of the contained messages

All Implemented Interfaces:

Iterable<T>

public final class MessageList<T>
extends Object
implements Iterable<T>

A simple array-backed list that holds one or more messages.

Recycling a MessageList

A MessageList is internally managed by a thread-local object pool to keep the GC pressure minimal. To return the MessageList to the pool, you must call one of the following methods: recycle(), releaseAllAndRecycle(), or releaseAllAndRecycle(int). If the list is returned to the pool (i.e. recycled), it will be reused when you attempts to get a MessageList via newInstance().

If you don't think recycling a MessageList isn't worth, it is also fine not to recycle it. Because of this relaxed contract, you can also decide not to wrap your code with a try-finally block only to recycle a list. However, if you decided to recycle it, you must keep in mind that:

• you must make sure you do not access the list once it has been recycled.
• If you are given with a MessageList as a parameter of your handler, it means it is your handler's responsibility to release the messages in it and to recycle it.

Method Summary

Methods

Modifier and Type	Method and Description
MessageList<T>	add(MessageList<T> src) Add the messages contained in the given MessageList to this MessageList and return itself.
MessageList<T>	add(MessageList<T> src, int srcIdx, int srcLen) Add the messages contained in the given MessageList, using the given src index and src length, to this MessageList and return itself.
MessageList<T>	add(T value) Add the message to this MessageList and return itself.
MessageList<T>	add(T[] src) Add the messages contained in the array to this MessageList and return itself.
MessageList<T>	add(T[] src, int srcIdx, int srcLen) Add the messages contained in the array, using the given src index and src length, to this MessageList and return itself.
T[]	array() Returns the backing array of this list.
<U> MessageList<U>	cast() Casts the type parameter of this list to a different type parameter.
MessageList<T>	clear() Clear all messages and return itself.
boolean	containsOnly(Class<?> clazz) Returns true if all messages contained in this MessageList are assignment-compatible with the object represented by this Class.
MessageList<T>	copy() Create a new copy all messages of this MessageList and return it.
MessageList<T>	copy(int index, int length) Create a new copy all messages of this MessageList, starting at the given index and using the given len, and return it.
int	forEach(int index, int length, MessageListProcessor<? super T> proc) Iterates over the messages in this list with the specified processor.
int	forEach(MessageListProcessor<? super T> proc) Iterates over the messages in this list with the specified processor.
T	get(int index) Return the message on the given index.
boolean	isEmpty() Return true if this MessageList is empty and so contains no messages.
Iterator<T>	iterator()
static <T> MessageList<T>	newInstance() Create a new empty MessageList instance
static <T> MessageList<T>	newInstance(int minCapacity) Create a new empty MessageList instance with the given capacity.
static <T> MessageList<T>	newInstance(T value) Create a new MessageList instance which holds the given value
boolean	recycle() Clear and recycle this instance.
boolean	releaseAll() Call ReferenceCountUtil.release(Object) on all messages in this MessageList and return true if all messages were released.
boolean	releaseAll(int decrement) Call ReferenceCountUtil.release(Object, int) on all messages in this MessageList and return true if all messages were released.
boolean	releaseAllAndRecycle() Short-cut for calling releaseAll() and recycle().
boolean	releaseAllAndRecycle(int decrement) Short-cut for calling releaseAll(int) and recycle().
MessageList<T>	retainAll() Call ReferenceCountUtil.retain(Object) on all messages in this MessageList and return itself.
MessageList<T>	retainAll(int increment) Call ReferenceCountUtil#retain(Object), int on all messages in this MessageList and return itself.
MessageList<T>	set(int index, T value) Sets the message on the given index.
int	size() Return the current size of this MessageList and so how many messages it holds.

Methods inherited from class java.lang.Object

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

Method Detail

newInstance

public static <T> MessageList<T> newInstance()

Create a new empty MessageList instance

newInstance

public static <T> MessageList<T> newInstance(int minCapacity)

Create a new empty MessageList instance with the given capacity.

newInstance

public static <T> MessageList<T> newInstance(T value)

Create a new MessageList instance which holds the given value

retainAll

public MessageList<T> retainAll()

Call ReferenceCountUtil.retain(Object) on all messages in this MessageList and return itself.

retainAll

public MessageList<T> retainAll(int increment)

Call ReferenceCountUtil#retain(Object), int on all messages in this MessageList and return itself.

releaseAll

public boolean releaseAll()

Call ReferenceCountUtil.release(Object) on all messages in this MessageList and return true if all messages were released.

releaseAll

public boolean releaseAll(int decrement)

Call ReferenceCountUtil.release(Object, int) on all messages in this MessageList and return true if all messages were released.

releaseAllAndRecycle

public boolean releaseAllAndRecycle()

Short-cut for calling releaseAll() and recycle(). Returns true if both return true.

releaseAllAndRecycle

public boolean releaseAllAndRecycle(int decrement)

Short-cut for calling releaseAll(int) and recycle(). Returns true if both return true.

recycle

public boolean recycle()

Clear and recycle this instance.

size

public int size()

Return the current size of this MessageList and so how many messages it holds.

isEmpty

public boolean isEmpty()

Return true if this MessageList is empty and so contains no messages.

get

public T get(int index)

Return the message on the given index. This method will throw an IndexOutOfBoundsException if there is no message stored in the given index.

set

public MessageList<T> set(int index,
                 T value)

Sets the message on the given index.

add

public MessageList<T> add(T value)

Add the message to this MessageList and return itself.

add

public MessageList<T> add(T[] src)

Add the messages contained in the array to this MessageList and return itself.

add

public MessageList<T> add(T[] src,
                 int srcIdx,
                 int srcLen)

Add the messages contained in the array, using the given src index and src length, to this MessageList and return itself.

add

public MessageList<T> add(MessageList<T> src)

Add the messages contained in the given MessageList to this MessageList and return itself.

add

public MessageList<T> add(MessageList<T> src,
                 int srcIdx,
                 int srcLen)

Add the messages contained in the given MessageList, using the given src index and src length, to this MessageList and return itself.

clear

public MessageList<T> clear()

Clear all messages and return itself.

copy

public MessageList<T> copy()

Create a new copy all messages of this MessageList and return it.

copy

public MessageList<T> copy(int index,
                  int length)

Create a new copy all messages of this MessageList, starting at the given index and using the given len, and return it.

cast

public <U> MessageList<U> cast()

Casts the type parameter of this list to a different type parameter. This method is often useful when you have to deal with multiple messages and do not want to down-cast the messages every time you access the list.

 public void messageReceived(ChannelHandlerContext ctx, MessageList<Object> msgs) {
     MessageList<MyMessage> cast = msgs.cast();
     for (MyMessage m: cast) { // or: for (MyMessage m: msgs.<MyMessage>cast())
         ...
     }
 }
 

forEach

public int forEach(MessageListProcessor<? super T> proc)

Iterates over the messages in this list with the specified processor.

Returns:

-1 if the processor iterated to or beyond the end of the readable bytes. If the processor raised MessageListProcessor.ABORT, the last-visited index will be returned.

forEach

public int forEach(int index,
          int length,
          MessageListProcessor<? super T> proc)

Iterates over the messages in this list with the specified processor.

Returns:

-1 if the processor iterated to or beyond the end of the specified area. If the processor raised MessageListProcessor.ABORT, the last-visited index will be returned.

iterator

public Iterator<T> iterator()

Specified by:

iterator in interface Iterable<T>

array

public T[] array()

Returns the backing array of this list. Use this array when you want to iterate over the list fast:

 MessageList list = ...;
 for (Object m: list.array()) {
     if (m == null) {
         break;
     }

     handleMessage(m);
 }
 

containsOnly

public boolean containsOnly(Class<?> clazz)

Returns true if all messages contained in this MessageList are assignment-compatible with the object represented by this Class.