Sharkysoft home

lava.security
Interface ITextTransform

All Known Implementing Classes:
IdentityTextTransform, DesEcbCoder, DesFbCoder, DesCbcCoder

public interface ITextTransform

Input/output interface for abstract text transforms.

Details: An ITextTransform is a filter with the following basic properties:

Symbols are basically integers, or bit vectors. The meaning that an ITextTransform assigns to them is not specified by this interface and is implementation-specific. It is common to refer to a stream of symbols as "text"; please don't confuse this usage with the more generic meaning of the same word.

Some common examples of text transforms include:

Most text transforms consume bytes and produce bytes. However, there are a few transforms, such as DES in OFB or CFB mode, which can actually be configured to process symbols streams whose widths vary from 1 to 64 bits. Hence, this interface allows input and output symbols to be represented with bytes, shorts, ints, or longs.

All input and output text is communicated by means of arrays of these basic integer types (i.e., byte[], short[], int[], or long[]). In order to support efficient buffering, the client must supply both the source/input and destination/output arrays when calling the methods of this interface.

A valid ITextTransform implementation must accept, as input, any array whose base type is wide enough to hold a whole input symbol. Similarly, a valid ITextTransform must also be willing to accept, as an output destination, any array whose base type is wide enough to store a complete output symbol. Neither input symbols nor output symbols are ever split among multiple elements or packed into single elements. Hence, if the input or output text is comprised of 8-bit symbols, it is wasteful to use int[] arrays as buffers, but it nevertheless allowed. Similarly, if a transformation's output text is comprised of 64-bit symbols, a valid implementation may refuse to store the symbols in byte[] buffers.

If the input array's base type is wider than the input symbol width, a valid implementation may assume that the unused MSBs are 0. Similarly, if the output array's base type is wider than the output symbol width, a valid implementation is required to place 0s in the unused MSBs when storing output in the provided destination array.

For any given text transform, the symbol widths of the input and output text can be discovered by calling, respectively, getTransformInputWidth and getTransformOutputWidth.

Because the state of an ITextTransform instance may depend on previous input history, in general is not advisable to transform multiple streams in parallel through the same instance. However, because the beginTransform method makes it possible to reset a given ITextTransform instance for a new data stream, processing multiple streams in serial with the same instance is acceptable. Implementations are not required to be thread-safe.

The primary methods for performing text transformations are:

  1. beginTransform -- reset transform (call before processing first symbol)
  2. continueTransform -- consume and produce symbols (call repeatedly)
  3. completeTransform -- finish delayed symbol processing (call after all symbols have been processed)

To perform an abstract text transformation correctly, these three methods should be called in the order listed.

Clip-source:

Since:
1999.08.08
Version:
1999.08.18

Method Summary
 void beginTransform()
          Resets transform.
 int completeTransform(java.lang.Object dest)
          Completes transform.
 int continueTransform(java.lang.Object src, java.lang.Object dest, int length)
          Processes text.
 int getTransformInputWidth()
          Returns input symbol width.
 int getTransformOutputWidth()
          Returns output symbol width.
 

Method Detail

beginTransform

public void beginTransform()
Resets transform.

Details: beginTransform initializes this transform in preparation for processing a new input text stream.


continueTransform

public int continueTransform(java.lang.Object src,
                             java.lang.Object dest,
                             int length)
Processes text.

Details: continueTransform consumes input text and produces output text. Input is retrieved from the provided source array (src), while output is stored in the provided destination array (dest). The return value normally indicates the number of symbols written into the destination array (see note below).

Depending on the particular transformation represented by this implementation, the number of output symbols produced per call may always be equal to the number of input symbols consumed (for example, if the transformation performs text compression). Similarly, a call to this method may cause the production of more elements than the supplied destination array can store. It is the caller's responsibility to make sure the supplied destination array is large enough to receive the symbols produced.

If the destination array is too short, the implementation may, at its option, discard the overflow. However, an implementation may also choose to retain the overflow portion and make it available in a subsequent call to this method. (Check the implementation documentation to see which approach is taken.) If the overflow is discarded, the return value must indicate the number of symbols written into the array plus the number of overflow symbols discarded.

It is legal to call this method with src set to null so long as length is also set to 0. This might be useful in situations where a transform is expected to produce output symbols even when the caller has no input symbols to supply (i.e., to recover buffered overflow from a previous call).

continueTransform always writes as much data into dest as can be computed from the current input history. However, because some data may not be computable until the transformation sees the last symbol (such as in checksum algorithms), it may be necessary to obtain the rest of the output data by calling completeTransform.

The results of continueTransform are undefined if it is called after completeTransform but before beginTransform.

Parameters:
src - the source array
dest - the destination array
length - number of symbols to process
Returns:
number of elements written into dest or discarded

completeTransform

public int completeTransform(java.lang.Object dest)
Completes transform.

Details: completeTransform signals to the implementation that there are no more input symbols to consume. This method completes the transform and gives the implementation an opportunity to perform final processing that may produce output symnbols. If output symbols are generated, they are stored in the supplied destination array (dest). The return value indicates the number output symbols stored.

Buffer overflow similar to what was described in continueTransform may also occur with completeTransform. Again, it is up to the caller to make sure that dest is large enough to hold the result, and the implementation may discard the remainder. If overflow occurs and symbols are discarded, the return value is the total number of stored and discarded symbols. Optionally, an implementation may also capture overflow and make it available to the caller through repeated calls to this method. No more symbols are available when completeTransform returns 0.

Parameters:
dest - the destination array
Returns:
number of elements written into dest or discarded

getTransformInputWidth

public int getTransformInputWidth()
Returns input symbol width.

Details: This method returns the width, in bits, of the transform's input symbol. Use this method to determine what array types can be used for storing input.

Returns:
input symbol width
Since:
1999.08.18

getTransformOutputWidth

public int getTransformOutputWidth()
Returns output symbol width.

Details: This method returns the width, in bits, of the transform's output symbol. Use this method to determine what array types can be used for storing output.

Returns:
output symbol width
Since:
1999.08.18

Sharkysoft home