Transformer (GNU cryptographic primitives and tools)
Keywords: gnu.crypto.assembly.Transformer,Transformer class

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| For the latest news and information visit The GNU Crypto project
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## gnu.crypto.assembly
Class Transformer

    java.lang.Object
      |
      +--gnu.crypto.assembly.Transformer

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.

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`.
`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.
`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`.
`void` | `reset()` Resets the `Transformer` for re-initialisation and use with other characteristics.
`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.

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.

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| For the latest news and information visit The GNU Crypto project
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001, 2002, 2003, 2004 Free Software Foundation, Inc.