com.ziesemer.utils.codec

Interface ICoder<IN extends Buffer,OUT extends Buffer>

Type Parameters:

IN - The type of Buffer being read from.

OUT - The type of Buffer being written to.

All Superinterfaces:

Cloneable, Serializable

All Known Subinterfaces:

IByteToCharEncoder, ICharToByteDecoder

All Known Implementing Classes:

Base64Decoder, Base64Encoder, BaseCoder, ByteToCharEncoder, CharToByteDecoder, HexDecoder, HexEncoder, URLDecoder, URLEncoder

public interface ICoder<IN extends Buffer,OUT extends Buffer>
extends Cloneable, Serializable

Base API for high-performance encoding and decoding between various Buffers. Supports conversions between ByteBuffers and CharBuffers through the IByteToCharEncoder and ICharToByteDecoder child interfaces, e.g. URL/Percent and Base64 codecs.

This API is similar in design to CharsetEncoder and CharsetDecoder.

Author:

Mark A. Ziesemer <www.ziesemer.com>

Method Summary

Modifier and Type	Method and Description
ICoder<IN,OUT>	clone() Another means for obtaining a configured instance copy from another.
OUT	code(IN in) Convenience method that encodes the passed-in input Buffer to a returned output Buffer.
CoderResult	code(IN in, OUT out, boolean endOfInput) Encodes as many units as possible from the given input buffer, writing the results to the given output buffer.
ICoder<IN,OUT>	config(ICoder<IN,OUT> base) Configures this instances based upon another.
CoderResult	flush(OUT out) Writes any final output after the entire input has been processed.
float	getAverageOutPerIn() Heuristic value of the average number of output units generated per input unit.
float	getMaxOutPerIn() Heuristic value of the maximum number of output units generated per input unit.
float	getMinInPerOut() Heuristic value of the minimum number of input units required to produce one or more output units.
ICoder<IN,OUT>	reset() Resets the coder, allowing it to be reused against new input and output, while keeping the same configuration.

Method Detail

config

ICoder<IN,OUT> config(ICoder<IN,OUT> base)

Configures this instances based upon another. The passed-in parameter must be an instance of the current implementation, or an IllegalArgumentException will be thrown.

Parameters:

base - The instance to copy the configuration from.

Returns:

The current instance, supporting the builder pattern.

Throws:

IllegalArgumentException - If the passed-in parameter is not a class-compatible instance of the current implementation.

clone

ICoder<IN,OUT> clone()
              throws CloneNotSupportedException

Another means for obtaining a configured instance copy from another. Typically utilizes config(ICoder).

Returns:

A copy of the current instance with the same configuration.

Throws:

CloneNotSupportedException

getMinInPerOut

float getMinInPerOut()

Heuristic value of the minimum number of input units required to produce one or more output units.

Similar to getAverageOutPerIn() and getMaxOutPerIn().

getAverageOutPerIn

float getAverageOutPerIn()

Heuristic value of the average number of output units generated per input unit.

Similar to CharsetEncoder.averageBytesPerChar() and CharsetDecoder.averageCharsPerByte().

getMaxOutPerIn

float getMaxOutPerIn()

Heuristic value of the maximum number of output units generated per input unit.

Similar to CharsetEncoder.maxBytesPerChar() and CharsetDecoder.maxCharsPerByte().

reset

ICoder<IN,OUT> reset()

Resets the coder, allowing it to be reused against new input and output, while keeping the same configuration.

code

OUT code(IN in)
  throws CharacterCodingException

Convenience method that encodes the passed-in input Buffer to a returned output Buffer.

Functions similar to CharsetEncoder.encode(java.nio.CharBuffer) and CharsetDecoder.decode(java.nio.ByteBuffer).

Parameters:

in - The input Buffer to read from.

Returns:

The output Buffer written to.

Throws:

CharacterCodingException

code

CoderResult code(IN in,
                 OUT out,
                 boolean endOfInput)

Encodes as many units as possible from the given input buffer, writing the results to the given output buffer.

Functions similar to CharsetEncoder.encode(java.nio.CharBuffer, java.nio.ByteBuffer, boolean) and CharsetDecoder.decode(java.nio.ByteBuffer, java.nio.CharBuffer, boolean).

Parameters:

in - The input Buffer to read from.

out - The output Buffer to write to.

endOfInput - true if, and only if, the invoker can provide no additional input characters beyond those in the given buffer.

flush

CoderResult flush(OUT out)

Writes any final output after the entire input has been processed. Should be called after code(Buffer, Buffer, boolean) is called for the final time.

Functions similar to CharsetEncoder.flush(java.nio.ByteBuffer) and CharsetDecoder.flush(java.nio.CharBuffer).

Parameters:

out - The output Buffer to write to.