|
Sharkysoft home | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
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-
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-
The primary methods for performing text transformations are:
beginTransform -- reset transform (call before processing first symbol)
continueTransform -- consume and produce symbols (call repeatedly)
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.
| 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 |
public void beginTransform()
Details: beginTransform initializes this transform in preparation for processing a new input text stream.
public int continueTransform(java.lang.Object src,
java.lang.Object dest,
int length)
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.
src - the source arraydest - the destination arraylength - number of symbols to processpublic int completeTransform(java.lang.Object dest)
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.
dest - the destination arraypublic int getTransformInputWidth()
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.
public int getTransformOutputWidth()
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.
|
Sharkysoft home | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||