Transformer

A Transformer is an abstract representation of a two-way transformation that can be chained together with other instances of this type. Examples of such transformations in this library are:

• CascadeTransformer that adapts an instance of a Cascade,
• PaddingTransformer that adapts an instance of gnu.crypto.pad.IPad, and finally
• DeflateTransformer that adapts a ZLib-based deflater/inflater algorithm implementation.

The special type LoopbackTransformer is also available and is implicitly (and silently) added to each instance of an Assembly.

A Transformer is characterized by the followings:

• It can be chained to other instances, to form an Assembly.
• When configured in an Assembly, it can be set to apply its internal transformation on the input data stream before (pre-processing) or after (post-processing) passing the input data to the next element in the chain. Note that the same type Transformer can be used in either pre-processing, or post-processing modes.
• A special transformer -LoopbackTransformer- is used to close the chain.
• A useful type of Transformer -one we're interested in- has internal buffers. The distinction between a casual push (update) operation, and the last one, allows to correctly flush any intermediate bytes that may exist in those buffers.

To allow wiring Transformer instances together, a minimal output size in bytes is necessary. The trivial case of a value of 1 for such attribute practically means that no output buffering, from the previous element, is needed -which is independent of buffering the input if the Transformer implementation itself is block-based.

This class exposes one class attribute and three Factory methods. They are:

String DIRECTION

Variable

The name of a property in the attributes map that is passed to the init method, representing the transformation's desired wiring direction. The mapped value should be a valid Direction value. If this attribute is omitted, Direction.FORWARD is used.

Transformer getCascadeTransformer (Cascade cascade)

Function

Returns the designated cascade instance wrapped in an Adapter for use as a Transformer.

Transformer getPaddingTransformer (IPad padding)

Function

Returns the designated padding instance wrapped in an Adapter for use as a Transformer.

Transformer getDeflateTransformer ()

Function

Returns a Transformer that underlies an implementation of the ZLib algorithm, able to deflate (compress) and inflate (decompress) data.

Concrete class instances of this abstract class, also expose the following instance methods:

void setMode (final Operation mode)

Function

Sets the operational mode of this Transformer to the designated mode value. Throws IllegalStateException if this instance has already been assigned an operational mode.

boolean isPreProcessing ()

Function

Returns true if this Transformer has been wired in pre-processing mode; returns false otherwise. Throws an IllegalStateException if this instance has not yet been assigned an operational mode.

boolean isPostProcessing ()

Function

Returns true if this Transformer has been wired in post-processing mode; returns false otherwise. Throws an IllegalStateException if this instance has not yet been assigned an operational mode.

void init (java.util.Map attributes) throws TransformerException

Function

Initializes the Transformer for operation with specific characteristics, indicated by the designated attributes. The latter being a set of name-value pairs that describes the desired future behavior of this instance. Throws an IllegalStateException if the instance is already initialized.

int currentBlockSize ()

Function

Returns the block-size of this Transformer. A value of 1 indicates that this instance is block-agnostic.

void reset ()

Function

Resets the Transformer for re-initialization and use with other characteristics. This method always succeeds.

byte [] update (byte b) throws TransformerException

Function

Convenience method that calls the method with same name and three arguments, using a byte array of length 1 whose contents are the designated byte b. Returns the result of transformation. Throws an IllegalStateException if the instance is not yet initialized. Throws an TransformerException if a transformation-related exception occurs during the operation.

byte [] update (byte[] in) throws TransformerException

Function

Convenience method that calls the same method with three arguments. All bytes in in, starting from index position 0 are considered. Returns the result of transformation. Throws an IllegalStateException if the instance is not yet initialized. Throws a TransformerException if a transformation-related exception occurs during the operation.

byte [] update (byte[] in, int offset, int length) throws TransformerException

Function

Returns the result of processing a designated length bytes from a given in byte array, starting at position offset. Throws an IllegalStateException if the instance is not yet initialized. Throws an TransformerException if a transformation-related exception occurs during the operation.

byte [] lastUpdate () throws TransformerException

Function

Convenience method that calls the same method with three arguments. A zero-long byte array is used. Returns the result of transformation. Throws an IllegalStateException if the instance is not yet initialized. Throws an TransformerException if a transformation-related exception occurs during the operation.

byte [] lastUpdate (byte b) throws TransformerException

Function

Convenience method that calls the method with same name and three arguments, using a byte array of length 1 whose contents are the designated byte b. Returns the result of transformation. Throws an IllegalStateException if the instance is not yet initialized. Throws an TransformerException if a transformation-related exception occurs during the operation.

byte [] lastUpdate (byte[] in) throws TransformerException

Function

Convenience method that calls the same method with three arguments. All bytes in in, starting from index position 0 are considered. Returns the result of transformation. Throws an IllegalStateException if the instance is not yet initialized. Throws an TransformerException if a transformation-related exception occurs during the operation.

byte [] lastUpdate (byte[] in, int offset, int length) throws TransformerException

Function

Returns the result of processing a designated length bytes from the given in byte array, starting at index position offset and signals, at the same time, that this is the last push operation on this Transformer. Throws an IllegalStateException if the instance is not yet initialized. Throws an TransformerException if a transformation-related exception occurs during the operation.