Top Description Fields Constructors Methods
org.codehaus.stax2.ri.typed

public abstract Class AsciiValueEncoder

extends Object
Class Inheritance
Known Direct Subclasses
org.codehaus.stax2.ri.typed.ValueEncoderFactory.ScalarEncoder, org.codehaus.stax2.ri.typed.ValueEncoderFactory.ArrayEncoder, org.codehaus.stax2.ri.typed.ValueEncoderFactory.Base64Encoder
This base class defines interface used for efficient encoding of typed values, by stream writers. The abstraction is necessary to reduce amount of duplicated code while avoiding significant additional overhead. The idea is that the low-level stream writer backend supplies encoder with the result buffer, while encoder itself knows the data and state. Together these allow for efficient serialization with light coupling.

General contract for encoding is that caller must call things in following sequence:

  1. First, bufferNeedsFlush is called once; and if indicated by return value of true, caller must flush its buffer so it is completely empty (buffer also must have size of at at least MIN_CHARS_WITHOUT_FLUSH)
  2. Then, one of encodeMore methods is to be called
  3. After this call, isCompleted should be called to determine if encoding was complete: if it was, there is nothing more to do.
  4. Otherwise caller should flush its buffer (since encoder has encoded as much as it can without flushing), and repeat cycle of calls to encodeMore followed by a call to isCompleted and flushing, as long as necessary to complete encoding.

Main restrictions for use are that value serializations must produce only 7-bit ascii characters, and that the value can be produced incrementally using limited size buffers. This is true for all current value types of the Typed Access API.

Finally, details of how encoders are created and/or reused is outside scope of this public interface. Stax2 reference implementation handles this using an encoder factory that knows construction details.

Since
3.0

Field Summary

Modifier and TypeField and Description
protected static final int
MIN_CHARS_WITHOUT_FLUSH

Constant used to determine when caller should flush buffer before calling encode methods.

Constructor Summary

AccessConstructor and Description
protected
AsciiValueEncoder()

Method Summary

Modifier and TypeMethod and Description
public final boolean

Returns:

True if encoder still has data to output and specified amount of free space is insufficient for encoding any more data
bufferNeedsFlush(int
Amount of free space (in characters) in the output buffer
freeChars)

Method called by writer to check if it should flush its output buffer (which has specified amount of free space) before encoder can encode more data.

public abstract int

Returns:

Value of pointer after all remaining data (which may be "none") that can be encoded (as constrained by buffer length) has been encoded. Has to exceed 'ptr' value sent in; will be equal to it if nothing was encoded (which should only occur when everything has been encoded, as long as bufferNeedsFlush is appropriately called once before calling this method)
encodeMore(char[] buffer, int ptr, int end)

public abstract int

Returns:

Value of pointer after all remaining data (which may be "none") that can be encoded (as constrained by buffer length) has been encoded. Has to exceed 'ptr' value sent in; will be equal to it if nothing was encoded (which should only occur when everything has been encoded, as long as bufferNeedsFlush is appropriately called once before calling this method)
encodeMore(byte[] buffer, int ptr, int end)

public abstract boolean
isCompleted()

Method that can alternatively be called to determine whether encoder has encoded all data it has.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

MIN_CHARS_WITHOUT_FLUSHback to summary
protected static final int MIN_CHARS_WITHOUT_FLUSH

Constant used to determine when caller should flush buffer before calling encode methods. Strict minimum would be something like 22 (for floating point numbers), but let's pad it a bit.

Constructor Detail

AsciiValueEncoderback to summary
protected AsciiValueEncoder()

Method Detail

bufferNeedsFlushback to summary
public final boolean bufferNeedsFlush(int freeChars)

Method called by writer to check if it should flush its output buffer (which has specified amount of free space) before encoder can encode more data. Flushing is only needed if (a) encoder has more data to output, and (b) free space is not enough to contain smallest segment of encoded value (individual array element or encoded primitive value).

Parameters
freeChars:int

Amount of free space (in characters) in the output buffer

Returns:boolean

True if encoder still has data to output and specified amount of free space is insufficient for encoding any more data

encodeMoreback to summary
public abstract int encodeMore(char[] buffer, int ptr, int end)
Returns:int

Value of pointer after all remaining data (which may be "none") that can be encoded (as constrained by buffer length) has been encoded. Has to exceed 'ptr' value sent in; will be equal to it if nothing was encoded (which should only occur when everything has been encoded, as long as bufferNeedsFlush is appropriately called once before calling this method)

encodeMoreback to summary
public abstract int encodeMore(byte[] buffer, int ptr, int end)
Returns:int

Value of pointer after all remaining data (which may be "none") that can be encoded (as constrained by buffer length) has been encoded. Has to exceed 'ptr' value sent in; will be equal to it if nothing was encoded (which should only occur when everything has been encoded, as long as bufferNeedsFlush is appropriately called once before calling this method)

isCompletedback to summary
public abstract boolean isCompleted()

Method that can alternatively be called to determine whether encoder has encoded all data it has. Generally called right after a call to encodeMore, to figure out whether buffer flush is needed (there is more data), or encoding is complete.