Assembly is a construction consisting of a chain of
* {@link Transformer} elements; each wired in pre- or post- transformation
* mode. This chain is terminated by one LoopbackTransformer
* element.
*
* Once constructed, and correctly initialised, the bulk of the methods
* available on the Assembly are delegated to the head of
* the {@link Transformer} chain of the Assembly.
*
* @see Transformer
*/
public class Assembly
{
public static final String DIRECTION = "gnu.crypto.assembly.assembly.direction";
/** Flag that tells if the instance is initialised or not; and if yes how. */
private Direction wired;
/** The first Transformer in the chain. */
private Transformer head;
/**
* Trivial constructor that sets the chain to a
* LoopbackTransformer.
*/
public Assembly()
{
super();
wired = null;
head = new LoopbackTransformer();
}
/**
* Adds the designated {@link Transformer} and signals that it should operate
* in pre-processing mode; i.e. it should apply its internal transformation
* algorithm on the input data stream, before it passes that stream to
* the next element in the chain.
*
* @param t the {@link Transformer} to add at the head of the current chain.
* @throws IllegalArgumentException if the designated {@link Transformer} has
* a non-null tail; i.e. it is already an element of a chain.
*/
public void addPreTransformer(Transformer t)
{
wireTransformer(t, Operation.PRE_PROCESSING);
}
/**
* Adds the designated {@link Transformer} and signals that it should operate
* in post-processing mode; i.e. it should apply its internal transformation
* algorithm on the input data stream, after it passes that stream to
* the next element in the chain.
*
* @param t the {@link Transformer} to add at the head of the current chain.
* @throws IllegalArgumentException if the designated {@link Transformer} has
* a non-null tail; i.e. it is already an element of a chain.
*/
public void addPostTransformer(Transformer t)
{
wireTransformer(t, Operation.POST_PROCESSING);
}
/**
* Initialises the Assembly for operation with specific
* characteristics.
*
* @param attributes a set of name-value pairs that describes the desired
* future behaviour of this instance.
* @throws IllegalStateException if the instance is already initialised.
*/
public void init(Map attributes) throws TransformerException
{
if (wired != null)
throw new IllegalStateException();
Direction flow = (Direction) attributes.get(DIRECTION);
if (flow == null)
flow = Direction.FORWARD;
attributes.put(Transformer.DIRECTION, flow);
head.init(attributes);
wired = flow;
}
/**
* Resets the Assembly for re-initialisation and use with other
* characteristics. This method always succeeds.
*/
public void reset()
{
head.reset();
wired = null;
}
/**
* 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.
*
* @param b the byte to process.
* @return the result of transformation.
* @throws IllegalStateException if the instance is not initialised.
* @throws TransformerException if a transformation-related exception occurs
* during the operation.
* @see #update(byte[], int, int)
*/
public byte[] update(byte b) throws TransformerException
{
return update(new byte[] { b }, 0, 1);
}
/**
* Convenience method that calls the method with same name and three
* arguments. All bytes in in, starting from index position
* 0 are considered.
*
* @param in the input data bytes.
* @return the result of transformation.
* @throws IllegalStateException if the instance is not initialised.
* @throws TransformerException if a transformation-related exception occurs
* during the operation.
* @see #update(byte[], int, int)
*/
public byte[] update(byte[] in) throws TransformerException
{
return update(in, 0, in.length);
}
/**
* Processes a designated number of bytes from a given byte array.
*
* @param in the input data bytes.
* @param offset index of in from which to start considering
* data.
* @param length the count of bytes to process.
* @return the result of transformation.
* @throws IllegalStateException if the instance is not initialised.
* @throws TransformerException if a transformation-related exception occurs
* during the operation.
*/
public byte[] update(byte[] in, int offset, int length)
throws TransformerException
{
if (wired == null)
throw new IllegalStateException();
return head.update(in, offset, length);
}
/**
* Convenience method that calls the method with same name and three arguments
* using a 0-long byte array.
*
* @return the result of transformation.
* @throws IllegalStateException if the instance is not initialised.
* @throws TransformerException if a transformation-related exception occurs
* during the operation.
* @see #lastUpdate(byte[], int, int)
*/
public byte[] lastUpdate() throws TransformerException
{
return lastUpdate(new byte[0], 0, 0);
}
/**
* 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.
*
* @param b the byte to process.
* @return the result of transformation.
* @throws IllegalStateException if the instance is not initialised.
* @throws TransformerException if a transformation-related exception occurs
* during the operation.
* @see #lastUpdate(byte[], int, int)
*/
public byte[] lastUpdate(byte b) throws TransformerException
{
return lastUpdate(new byte[] { b }, 0, 1);
}
/**
* Convenience method that calls the method with same name and three
* arguments. All bytes in in, starting from index position
* 0 are considered.
*
* @param in the input data bytes.
* @return the result of transformation.
* @throws IllegalStateException if the instance is not initialised.
* @throws TransformerException if a transformation-related exception occurs
* during the operation.
* @see #lastUpdate(byte[], int, int)
*/
public byte[] lastUpdate(byte[] in) throws TransformerException
{
return lastUpdate(in, 0, in.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 for this
* Assembly.
*
* @param in the input data bytes.
* @param offset index of in from which to start considering
* data.
* @param length the count of bytes to process.
* @return the result of transformation.
* @throws IllegalStateException if the instance is not initialised.
* @throws TransformerException if a transformation-related exception occurs
* during the operation.
*/
public byte[] lastUpdate(byte[] in, int offset, int length)
throws TransformerException
{
if (wired == null)
throw new IllegalStateException();
byte[] result = head.lastUpdate(in, offset, length);
reset();
return result;
}
private void wireTransformer(Transformer t, Operation mode)
{
if (t.tail != null)
throw new IllegalArgumentException();
t.setMode(mode);
t.tail = head;
head = t;
}
}