com.devexperts.io

Class ChunkList

java.lang.Object

com.devexperts.io.ChunkList

All Implemented Interfaces:

Iterable<Chunk>

public class ChunkList
extends Object
implements Iterable<Chunk>

Reusable list of chunks with data. This class is used for containment and transfer of variable-sized binary data within the system. It uses a list of limited-capacity chunks to accommodate data of any size.

This class does not implement Collection interface but some of its methods conform with methods of standard collections (such as ArrayList and Queue) from Java Collections Framework.

Chunk lists are designed to be reusable in much the same way as individual chunks; they have similar reuse, sharing and owning API methods. Chunk lists may be acquired from pools via getChunkList(owner) method and recycled via recycle(owner) method. They also have owners, supports handover and may be marked as read-only. A read-only chunk list may contain only read-only chunks. All chunks within the chunk list (except for the read-only ones) are owned by the chunk list. Thus, adding and removing chunks into/from the list implies handover of these chunks from external owner to the list and vice versa. Only the owner of the list may add and remove chunks to/from the list.

The ChunkList cannot contain null chunks.

Iterable

ChunkList implements Iterable interface. The particular feature of its Iterator is that it is reusable: after the invocation of Iterator.hasNext() returns false the iterator becomes invalid and may no longer be used, however several iterator instances may still be acquired and used concurrently. This feature provides garbage-free "foreach" iteration over chunk lists.

Threads and locks

This class is not thread-safe. It cannot be safely updated from multiple threads at the same time. Code that is using chunks shall include its own synchronization, especially to guarantee correct operation of hand-over protocol.

The only only exception are read-only chunk lists that can be used (for read only) concurrently from multiple threads.

See Also:

Chunk, ChunkPool, ChunkedInput, ChunkedOutput

Field Summary

Fields

Modifier and Type	Field and Description
protected Chunk[]	chunkArray
static ChunkList	EMPTY Read-only empty chunk list.
protected int	head
protected WeakReference<ChunkPool>	poolReference
protected int	tail

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ChunkList(ChunkPool pool, Object owner) Constructs new chunk list of specified owner corresponding to a specified pool.
	ChunkList(Object owner) Constructs empty chunk list of specified owner not corresponding to any pool.

Method Summary

Modifier and Type	Method and Description
void	add(byte[] bytes, int offset, int length) Adds to this chunk list data from specified byte array.
void	add(Chunk chunk, Object owner) Adds given chunk to the end of this chunk list.
void	addAll(ChunkList chunks, Object owner) Adds chunks from specified chunk list into the end of this one.
protected void	checkOwner(Object owner) Throws an exception if the chunk list is not owned by specified owner.
protected void	checkRange(int index)
Chunk	get(int index) Returns the chunk located at the specified position of the list.
ChunkPool	getPool() Returns chunk pool that this chunk list was allocated from or null if none.
long	getTotalLength() Returns the total number of bytes stored in chunks, i.e.
void	handOver(Object oldOwner, Object newOwner) Hands over the chunk list to another owner.
boolean	isEmpty() Checks whether this chunk list is empty, i.e.
boolean	isReadOnly() Checks whether the chunk list is read-only.
Iterator<Chunk>	iterator() Returns an iterator over the chunks.
void	markReadOnly(Object owner) Marks this chunk list as isReadOnly().
Chunk	poll(Object owner) Retrieves a chunk from the beginning of the list, hands it over to the owner of this chunk list and returns it.
Chunk	pollLast(Object owner) Retrieves a chunk from the end of the list, hands it over to the owner of this chunk list and returns it.
void	recycle(Object owner) Returns this chunk list as well as all the chunks it contains into the pool.
void	setChunkRange(int index, int offset, int length, Object owner) Sets range for specified chunk.
int	size() Returns the number of chunks in this list.
String	toString() Returns a string representation of the object.
static ChunkList	wrap(byte[] bytes, int offset, int length, Object owner) Constructs a new chunk list of specified owner that wraps specified byte array with specified range of data, and does not correspond to any pool.
static ChunkList	wrap(byte[] bytes, Object owner) Constructs a new chunk list of specified owner that wraps specified byte array and does not correspond to any pool.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

EMPTY

public static final ChunkList EMPTY

Read-only empty chunk list.

poolReference

protected final WeakReference<ChunkPool> poolReference

chunkArray

protected Chunk[] chunkArray

head

protected int head

tail

protected int tail

Constructor Detail

ChunkList

public ChunkList(Object owner)

Constructs empty chunk list of specified owner not corresponding to any pool.

Parameters:

owner - owner of new chunk list

ChunkList

protected ChunkList(ChunkPool pool,
                    Object owner)

Constructs new chunk list of specified owner corresponding to a specified pool.

Parameters:

pool - pool to use for pooling

owner - owner of new chunk list

Method Detail

wrap

public static ChunkList wrap(byte[] bytes,
                             Object owner)

Constructs a new chunk list of specified owner that wraps specified byte array and does not correspond to any pool.

Note: wrapping shall be used only with 'throw-away' arrays that will not be used by source code after wrapping.

Parameters:

bytes - the byte array to wrap

owner - owner of new chunk list

Returns:

new chunks

Throws:

NullPointerException - if bytes is null.

wrap

public static ChunkList wrap(byte[] bytes,
                             int offset,
                             int length,
                             Object owner)

Constructs a new chunk list of specified owner that wraps specified byte array with specified range of data, and does not correspond to any pool.

Note: wrapping shall be used only with 'throw-away' arrays that will not be used by source code after wrapping.

Parameters:

bytes - the byte array to wrap

offset - position of the first meaningful byte

length - total number of meaningful bytes

owner - owner of new chunk list

Returns:

new chunks

Throws:

NullPointerException - if bytes is null.

IndexOutOfBoundsException - if the region defined by offset and length is out of underlying byte array range

getPool

public ChunkPool getPool()

Returns chunk pool that this chunk list was allocated from or null if none.

Returns:

chunk pool that this chunk list was allocated from or null if none.

size

public int size()

Returns the number of chunks in this list. In order to get the total number of bytes stored in chunks getTotalLength() method should be used.

Returns:

number of chunks in this chunk list

isEmpty

public boolean isEmpty()

Checks whether this chunk list is empty, i.e. contains no chunks. Note, that this method will return false if there are any chunks even if they are all empty.

Returns:

true if there is no chunks in this chunk list

get

public Chunk get(int index)

Returns the chunk located at the specified position of the list. This method does not extract the chunk from the list and does not change its owner.

Parameters:

index - position of a chunk to get

Returns:

Chunk located at the specified position

Throws:

IndexOutOfBoundsException - if index is out of bounds

getTotalLength

public long getTotalLength()

Returns the total number of bytes stored in chunks, i.e. ∑ chunk.getLength().

Returns:

the total number of bytes stored in chunks

iterator

public Iterator<Chunk> iterator()

Returns an iterator over the chunks. The returned iterator does not support remove operation.

Iterator returned by this method may be reused again by someone else after it have traversed all the elements in this ChunkList, therefore it is not allowed to use the iterator after its hasNext() method has returned false. However it is still allowed to acquire and use several instances of iterator (it will generate garbage).

Read-only chunk lists can be iterated concurrently from multiple threads. Each call to this method creates its own instance of iterator for read-only chunk lists.

Specified by:

iterator in interface Iterable<Chunk>

Returns:

iterator over chunks as specified by Iterable interface.

add

public void add(Chunk chunk,
                Object owner)

Adds given chunk to the end of this chunk list. The specified chunk must either be read-only or have the same owner as this chunk list. The chunk will be handed over to this chunk list's internal owner object after invocation of this method.

Parameters:

chunk - a chunk to add

owner - current owner of this chunk list and given chunk

Throws:

NullPointerException - if chunk is null

IllegalStateException - if this chunk list's owner differs from the one specified (in particular, if it is read-only) or if the given chunk is not read-only and its owner differs from the one specified

addAll

public void addAll(ChunkList chunks,
                   Object owner)

Adds chunks from specified chunk list into the end of this one. The specified chunk list must either be read-only or have the same owner as this chunk list. All chunks added will be handed over to this chunk list's internal owner object and the given chunk list will be recycled after invocation of this method.

Parameters:

chunks - chunk list with chunks to add

owner - current owner of both this and given chunk lists (if the given chunk list is not read-only).

Throws:

NullPointerException - if chunks is null

IllegalArgumentException - if chunks is this

IllegalStateException - if this chunk list's owner differs from the one specified (in particular, if it is read-only) or if the given chunk list is not read-only and its owner differs from the one specified

add

public void add(byte[] bytes,
                int offset,
                int length)

Adds to this chunk list data from specified byte array. Chunk pool that this chunk list was acquired from must be strongly-reachable (new chunks will be acquired from it).

Parameters:

bytes - byte array to take data from

offset - offset of data within the array

length - length of data

poll

public Chunk poll(Object owner)

Retrieves a chunk from the beginning of the list, hands it over to the owner of this chunk list and returns it. The chunk list must not be read-only.

Parameters:

owner - owner of this chunk list (which will also become the owner of the taken chunk after invocation of this method), unless the taken chunk was read-only.

Returns:

a chunk from the beginning of this chunk list or null if the list is empty

Throws:

IllegalStateException - if this chunk list's owner differs from the one specified or if the chunk list is read-only.

pollLast

public Chunk pollLast(Object owner)

Retrieves a chunk from the end of the list, hands it over to the owner of this chunk list and returns it. The chunk list must not be read-only.

Parameters:

owner - owner of this chunk list (which will also become the owner of the taken chunk after invocation of this method).

Returns:

a chunk from the end of this chunk list or null if the list is empty

Throws:

IllegalStateException - if this chunk list's owner differs from the one specified (in particular, if the chunk list is read-only)

setChunkRange

public void setChunkRange(int index,
                          int offset,
                          int length,
                          Object owner)

Sets range for specified chunk.

Parameters:

index - position of a chunk to set range

offset - position of the first meaningful byte

length - total number of meaningful bytes

owner - owner of the chunk list

Throws:

IndexOutOfBoundsException - if the region defined by offset and length is out of chunk's underlying byte array range

IllegalStateException - if the chunk list's owner differs from the one specified (in particular, if the chunk list or chunk is read-only).

See Also:

Chunk.setRange(int, int, java.lang.Object)

isReadOnly

public boolean isReadOnly()

Checks whether the chunk list is read-only.

Returns:

true if this chunk list is read-only.

See Also:

markReadOnly(Object), Chunk.isReadOnly()

markReadOnly

public void markReadOnly(Object owner)

Marks this chunk list as isReadOnly(). All contained chunks also become read-only after invocation of this method. Does nothing if the list is already read-only.

Parameters:

owner - current owner of this chunk list

Throws:

IllegalStateException - if the chunk list is not read-only and its current owner differs from the one specified

See Also:

Chunk.markReadOnly(Object)

handOver

public void handOver(Object oldOwner,
                     Object newOwner)

Hands over the chunk list to another owner. Does nothing if the list is read-only.

Parameters:

oldOwner - old (current) owner of the chunk list

newOwner - new owner of the chunk list

Throws:

IllegalStateException - if the chunk list is not read-only and its current owner differs from the one specified

recycle

public void recycle(Object owner)

Returns this chunk list as well as all the chunks it contains into the pool. This method has no effect if this chunk list is read-only. A reference to this chunk list is considered to become invalid after invocation of this method and may no longer be used, unless the chunk list was read-only.

Parameters:

owner - current owner of the chunk list

Throws:

IllegalStateException - if the chunk list is not read-only and its current owner differs from the one specified

See Also:

Chunk.recycle(Object)

checkOwner

protected void checkOwner(Object owner)

Throws an exception if the chunk list is not owned by specified owner.

Parameters:

owner - expected owner of the chunk list

Throws:

IllegalStateException - if the chunk list's current owner differs from the one specified

checkRange

protected void checkRange(int index)

toString

public String toString()

Returns a string representation of the object.

Overrides:

toString in class Object

Returns:

a string representation of the object.