gnu.crypto.assembly
Class Transformer

java.lang.Object
  gnu.crypto.assembly.Transformer

Direct Known Subclasses:

CascadeTransformer, DeflateTransformer, LoopbackTransformer, PaddingTransformer

public abstract class Transformer

extends java.lang.Object

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: Cascade cipher, IPad algorithm, and a ZLib-based deflater/inflater algorithm. A special implementation of a Transformer to close a chain is also provided.

A Transformer is characterised 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 as either in pre-processing or a 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 independant of buffering the input if the Transformer implementation itself is block-based.

Version:

$Revision: 1.2 $

See Also:

CascadeTransformer, PaddingTransformer, DeflateTransformer

Field Summary

static java.lang.String	DIRECTION
protected java.io.ByteArrayOutputStream	inBuffer
protected Operation	mode
protected java.io.ByteArrayOutputStream	outBuffer
protected Transformer	tail
protected Direction	wired

Constructor Summary

protected

Transformer() Trivial protected constructor.

Method Summary

int	currentBlockSize() Returns the block-size of this Transformer.
(package private) abstract int	delegateBlockSize()
static Transformer	getCascadeTransformer(Cascade cascade)
static Transformer	getDeflateTransformer()
static Transformer	getPaddingTransformer(IPad padding)
void	init(java.util.Map attributes) Initialises the Transformer for operation with specific characteristics.
(package private) abstract void	initDelegate(java.util.Map attributes)
boolean	isPostProcessing() Returns true if this Transformer was wired in post-processing mode; false otherwise.
boolean	isPreProcessing() Returns true if this Transformer was wired in pre-processing mode; false otherwise.
byte[]	lastUpdate() Convenience method that calls the same method with three arguments.
byte[]	lastUpdate(byte b) 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.
byte[]	lastUpdate(byte[] in) Convenience method that calls the same method with three arguments.
byte[]	lastUpdate(byte[] in, int offset, int length) Processes a designated number of bytes from a given byte array and signals, at the same time, that this is the last push operation on this Transformer.
(package private) abstract byte[]	lastUpdateDelegate()
void	reset() Resets the Transformer for re-initialisation and use with other characteristics.
(package private) abstract void	resetDelegate()
void	setMode(Operation mode) Sets the operational mode of this Transformer.
byte[]	update(byte b) 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.
byte[]	update(byte[] in) Convenience method that calls the same method with three arguments.
byte[]	update(byte[] in, int offset, int length) Processes a designated number of bytes from a given byte array.
(package private) abstract byte[]	updateDelegate(byte[] in, int off, int len)

Methods inherited from class java.lang.Object

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

Field Detail

DIRECTION

public static final java.lang.String DIRECTION

See Also:

Constant Field Values

wired

protected Direction wired

mode

protected Operation mode

tail

protected Transformer tail

inBuffer

protected java.io.ByteArrayOutputStream inBuffer

outBuffer

protected java.io.ByteArrayOutputStream outBuffer

Constructor Detail

Transformer

protected Transformer()

Trivial protected constructor.

Method Detail

getCascadeTransformer

public static final Transformer getCascadeTransformer(Cascade cascade)

getPaddingTransformer

public static final Transformer getPaddingTransformer(IPad padding)

getDeflateTransformer

public static final Transformer getDeflateTransformer()

setMode

public void setMode(Operation mode)

Sets the operational mode of this Transformer.

Parameters:

mode - the processing mode this Transformer is required to operate in.

Throws:

java.lang.IllegalStateException - if this instance has already been assigned an operational mode.

isPreProcessing

public boolean isPreProcessing()

Returns true if this Transformer was wired in pre-processing mode; false otherwise.

Returns:

true if this Transformer has been wired in pre-processing mode; false otherwise.

Throws:

java.lang.IllegalStateException - if this instance has not yet been assigned an operational type.

isPostProcessing

public boolean isPostProcessing()

Returns true if this Transformer was wired in post-processing mode; false otherwise.

Returns:

true if this Transformer has been wired in post-processing mode; false otherwise.

Throws:

java.lang.IllegalStateException - if this instance has not yet been assigned an operational type.

init

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

Initialises the Transformer for operation with specific characteristics.

Parameters:

attributes - a set of name-value pairs that describes the desired future behaviour of this instance.

Throws:

java.lang.IllegalStateException - if the instance is already initialised.

TransformerException

currentBlockSize

public int currentBlockSize()

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

Returns:

the current minimal required block size.

reset

public void reset()

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

update

public byte[] update(byte b)
              throws TransformerException

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.

Parameters:

b - the byte to process.

Returns:

the result of transformation.

Throws:

java.lang.IllegalStateException - if the instance is not initialised.

TransformerException - if a transformation-related exception occurs during the operation.

See Also:

update(byte[], int, int)

update

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

Convenience method that calls the same method with three arguments. All bytes in in, starting from index position 0 are considered.

Parameters:

in - the input data bytes.

Returns:

the result of transformation.

Throws:

java.lang.IllegalStateException - if the instance is not initialised.

TransformerException - if a transformation-related exception occurs during the operation.

See Also:

update(byte[], int, int)

update

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

Processes a designated number of bytes from a given byte array.

Parameters:

in - the input data bytes.

offset - index of in from which to start considering data.

length - the count of bytes to process.

Returns:

the result of transformation.

Throws:

java.lang.IllegalStateException - if the instance is not initialised.

TransformerException - if a transformation-related exception occurs during the operation.

lastUpdate

public byte[] lastUpdate()
                  throws TransformerException

Convenience method that calls the same method with three arguments. A zero-long byte array is used.

Returns:

the result of transformation.

Throws:

java.lang.IllegalStateException - if the instance is not initialised.

TransformerException - if a transformation-related exception occurs during the operation.

See Also:

lastUpdate(byte[], int, int)

lastUpdate

public byte[] lastUpdate(byte b)
                  throws TransformerException

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.

Parameters:

b - the byte to process.

Returns:

the result of transformation.

Throws:

java.lang.IllegalStateException - if the instance is not initialised.

TransformerException - if a transformation-related exception occurs during the operation.

See Also:

lastUpdate(byte[], int, int)

lastUpdate

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

Convenience method that calls the same method with three arguments. All bytes in in, starting from index position 0 are considered.

Parameters:

in - the input data bytes.

Returns:

the result of transformation.

Throws:

java.lang.IllegalStateException - if the instance is not initialised.

TransformerException - if a transformation-related exception occurs during the operation.

See Also:

lastUpdate(byte[], int, int)

lastUpdate

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

Processes a designated number of bytes from a given byte array and signals, at the same time, that this is the last push operation on this Transformer.

Parameters:

in - the input data bytes.

offset - index of in from which to start considering data.

length - the count of bytes to process.

Returns:

the result of transformation.

Throws:

java.lang.IllegalStateException - if the instance is not initialised.

TransformerException - if a transformation-related exception occurs during the operation.

initDelegate

abstract void initDelegate(java.util.Map attributes)
                    throws TransformerException

Throws:

TransformerException

delegateBlockSize

abstract int delegateBlockSize()

resetDelegate

abstract void resetDelegate()

updateDelegate

abstract byte[] updateDelegate(byte[] in,
                               int off,
                               int len)
                        throws TransformerException

Throws:

TransformerException

lastUpdateDelegate

abstract byte[] lastUpdateDelegate()
                            throws TransformerException

Throws:

TransformerException