org.snf4j.core.codec

Interface ICodecPipeline

public interface ICodecPipeline

A manager that manages encoders and decoders in the pipeline that is associated with the ICodecExecutor.

All the methods that change the pipeline should always validate if the change that is about to be made will not break the matching of the inbound and outbound types between codecs in the pipeline.

Special care must be taken when adding or inserting the first codec into the pipeline:

• for the first decoder it is required that the inbound type can be either byte[] or ByteBuffer
• for the first encoder it is required that the outbound type can be either byte[] or ByteBuffer

The diagram describing how data are processed thru a pipeline

              I/O read                       I/O write
                |                              |
  +-------------+------------------------------+-------------+
  |             |         CodecPipeline       /|\            |
  |            \|/                             |             |
  |    +--------+--------+            +--------+--------+    |
  |    |  First Decoder  |            |  First Encoder  |    |
  |    +--------+--------+            +--------+--------+    |
  |             |                             /|\            |
  |            \|/                             |             |
  |    +--------+--------+            +--------+--------+    |
  |    | Second Decoder  |            | Second Encoder  |    |
  |    +--------+--------+            +--------+--------+    |
  |             .                             /|\            |
  |             .                              .             |
  |             .                              .             |
  |             .                              .             |
  |            \|/                             .             |
  |    +--------+--------+            +--------+--------+    |
  |    |   Last Decoder  |            |   Last Encoder  |    |
  |    +--------+--------+            +--------+--------+    |
  |             |                             /|\            |
  |            \|/                             |             |
  +-------------+------------------------------+-------------+
                |                              |
         Handler.read()                 Session.write()
 

Thread-safe considerations: Any class implementing this interface should be thread safe as it is expected that the internal state of the pipeline can be changed at any time.

Author:

SNF4J.ORG

Method Summary

Modifier and Type	Method and Description
void	add(Object key, IDecoder<?,?> decoder) Appends a decoder at the last position of this pipeline.
void	add(Object key, IEncoder<?,?> encoder) Appends a encoder at the last position of this pipeline.
void	addAfter(Object baseKey, Object key, IDecoder<?,?> decoder) Inserts a decoder after an existing decoder of this pipeline.
void	addAfter(Object baseKey, Object key, IEncoder<?,?> encoder) Inserts a encoder after an existing decoder of this pipeline.
void	addBefore(Object baseKey, Object key, IDecoder<?,?> decoder) Inserts a decoder before an existing decoder of this pipeline.
void	addBefore(Object baseKey, Object key, IEncoder<?,?> encoder) Inserts a encoder before an existing encoder of this pipeline.
void	addFirst(Object key, IDecoder<?,?> decoder) Inserts a decoder at the first position of this pipeline.
void	addFirst(Object key, IEncoder<?,?> encoder) Inserts a encoder at the first position of this pipeline.
List<Object>	decoderKeys() Returns a list of keys that identify all decoders in this pipeline.
List<Object>	encoderKeys() Returns a list of keys that identify all encoders in this pipeline.
ICodec<?,?>	get(Object key) Returns the codec identified by the specified key in this pipeline.
ICodec<?,?>	remove(Object key) Removes the codec identified by the specified key from this pipeline.
IDecoder<?,?>	replace(Object oldKey, Object key, IDecoder<?,?> decoder) Replaces the decoder identified by the specified old key with a new decoder in this pipeline.
IEncoder<?,?>	replace(Object oldKey, Object key, IEncoder<?,?> encoder) Replaces the encoder identified by the specified old key with a new encoder in this pipeline.

Method Detail

add

void add(Object key,
         IDecoder<?,?> decoder)

Appends a decoder at the last position of this pipeline.

Parameters:

key - the key under which the decoder should be appended

decoder - the decoder to append

Throws:

IllegalArgumentException - if a decoder identified by the specified key already exists in this pipeline

IllegalArgumentException - if the decoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

add

void add(Object key,
         IEncoder<?,?> encoder)

Appends a encoder at the last position of this pipeline.

Parameters:

key - the key under which the encoder should be appended

encoder - the encoder to append

Throws:

IllegalArgumentException - if a encoder identified by the specified key already exists in this pipeline

IllegalArgumentException - if the encoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

addAfter

void addAfter(Object baseKey,
              Object key,
              IDecoder<?,?> decoder)

Inserts a decoder after an existing decoder of this pipeline.

Parameters:

baseKey - the key identifying the existing decoder

key - the key under which the decoder should be inserted after

decoder - the decoder to insert after

Throws:

NoSuchElementException - if the decoder identified by the specified base key does not exist in this pipeline

IllegalArgumentException - if a decoder identified by the specified key already exists in this pipeline

IllegalArgumentException - if the decoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

addAfter

void addAfter(Object baseKey,
              Object key,
              IEncoder<?,?> encoder)

Inserts a encoder after an existing decoder of this pipeline.

Parameters:

baseKey - the key identifying the existing encoder

key - the key under which the encoder should be inserted after

encoder - the encoder to insert after

Throws:

NoSuchElementException - if the encoder identified by the specified base key does not exist in this pipeline

IllegalArgumentException - if a encoder identified by the specified key already exists in this pipeline

IllegalArgumentException - if the encoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

addFirst

void addFirst(Object key,
              IDecoder<?,?> decoder)

Inserts a decoder at the first position of this pipeline.

Parameters:

key - the key under which the decoder should be inserted first

decoder - the decoder to insert first

Throws:

IllegalArgumentException - if a decoder identified by the specified key already exists in this pipeline

IllegalArgumentException - if the decoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

addFirst

void addFirst(Object key,
              IEncoder<?,?> encoder)

Inserts a encoder at the first position of this pipeline.

Parameters:

key - the key under which the encoder should be inserted first

encoder - the encoder to insert first

Throws:

IllegalArgumentException - if a encoder identified by the specified key already exists in this pipeline

IllegalArgumentException - if the encoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

addBefore

void addBefore(Object baseKey,
               Object key,
               IDecoder<?,?> decoder)

Inserts a decoder before an existing decoder of this pipeline.

Parameters:

baseKey - the key identifying the existing decoder

key - the key under which the decoder should be inserted before

decoder - the decoder to insert before

Throws:

NoSuchElementException - if the decoder identified by the specified base key does not exist in this pipeline

IllegalArgumentException - if a decoder identified by the specified key already exists in this pipeline

IllegalArgumentException - if the decoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

addBefore

void addBefore(Object baseKey,
               Object key,
               IEncoder<?,?> encoder)

Inserts a encoder before an existing encoder of this pipeline.

Parameters:

baseKey - the key identifying the existing encoder

key - the key under which the encoder should be inserted before

encoder - the encoder to insert before

Throws:

NoSuchElementException - if the encoder identified by the specified base key does not exist in this pipeline

IllegalArgumentException - if a encoder identified by the specified key already exists in this pipeline

IllegalArgumentException - if the encoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

replace

IDecoder<?,?> replace(Object oldKey,
                      Object key,
                      IDecoder<?,?> decoder)

Replaces the decoder identified by the specified old key with a new decoder in this pipeline.

Parameters:

oldKey - the key of the decoder to be replaced

key - the key under which the replacement should be added

decoder - the decoder which is used as replacement

Returns:

the removed decoder

Throws:

NoSuchElementException - if the decoder identified by the specified old key does not exist in this pipeline

IllegalArgumentException - if a decoder identified by the specified key already exists in this pipeline, except for the decoder to be replaced

IllegalArgumentException - if the decoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

replace

IEncoder<?,?> replace(Object oldKey,
                      Object key,
                      IEncoder<?,?> encoder)

Replaces the encoder identified by the specified old key with a new encoder in this pipeline.

Parameters:

oldKey - the key of the encoder to be replaced

key - the key under which the replacement should be added

encoder - the encoder which is used as replacement

Returns:

the removed encoder

Throws:

NoSuchElementException - if the encoder identified by the specified old key does not exist in this pipeline

IllegalArgumentException - if a encoder identified by the specified key already exists in this pipeline, except for the encoder to be replaced

IllegalArgumentException - if the encoder has incompatible the inbound or the outbound type

NullPointerException - if any of the arguments is null

remove

ICodec<?,?> remove(Object key)

Removes the codec identified by the specified key from this pipeline.

Parameters:

key - the key under which the codec was stored

Returns:

the removed codec

Throws:

NoSuchElementException - if there's no such codec that is identified by the specified key in this pipeline

IllegalArgumentException - if removing of the codec that is identified by the specified key would break the matching of the inbound and outbound types between other codecs in the pipeline.

NullPointerException - if the specified key is null

get

ICodec<?,?> get(Object key)

Returns the codec identified by the specified key in this pipeline.

Parameters:

key - the key under which the codec was stored

Returns:

the codec that is identified by the specified key, or null if there's no such codec in this pipeline.

encoderKeys

List<Object> encoderKeys()

Returns a list of keys that identify all encoders in this pipeline. The keys in the list are in the order they were added to this pipeline.

Returns:

a list of the keys

decoderKeys

List<Object> decoderKeys()

Returns a list of keys that identify all decoders in this pipeline. The keys in the list are in the order they were added to this pipeline.

Returns:

a list of the keys