org.apache.derby.iapi.jdbc
Class CharacterStreamDescriptor

java.lang.Object
  extended by org.apache.derby.iapi.jdbc.CharacterStreamDescriptor

public class CharacterStreamDescriptor
extends java.lang.Object

A description of a byte stream representing characters. The description is used by decoders to properly configure themselves. Note that encoding is not included in the description, because all internal byte streams are expected to be using the modified UTF-8 encoding (see DataInput).

The information in the description is only guaranteed to be valid at the moment it is passed to the decoder object. As the decoder works on the stream, the information in the descriptor will be outdated.

To create a stream descriptor, obtain a Builder instance and set the required parameters.

See Also:
CharacterStreamDescriptor.Builder

Nested Class Summary
static class CharacterStreamDescriptor.Builder
          The builder for the CharacterStreamDescriptor class.
 
Field Summary
static long BEFORE_FIRST
          Constant for the character position, when it is positioned before the first character in the stream (i.e. at the very beginning of the stream or in the header).
private  boolean bufferable
          Tells if the stream can be buffered or not.
private  long byteLength
          The byte length of the stream, 0 if unknown.
private  long charLength
          The character length of the stream, 0 if unknown.
private  long curBytePos
          The current byte position.
private  long curCharPos
          The current character position.
private  long dataOffset
          First data byte in the byte stream.
private  long maxCharLength
          The maximum allowed character length.
private  boolean positionAware
          Tells if the stream is aware of its own position.
private  java.io.InputStream stream
          Reference to the stream we are describing.
 
Constructor Summary
private CharacterStreamDescriptor(CharacterStreamDescriptor.Builder b)
          Creates a character stream descriptor, using the supplied builder.
 
Method Summary
 long getByteLength()
           
 long getCharLength()
           
 long getCurBytePos()
           
 long getCurCharPos()
          Returns the current character position.
 long getDataOffset()
          Returns the first index of the described stream that contains real data.
 long getMaxCharLength()
          Returns the imposed maximum character length on the described stream.
 PositionedStream getPositionedStream()
          Returns the associated positioned stream, if the stream is position aware.
 java.io.InputStream getStream()
          Returns the associated stream.
 boolean isBufferable()
          Tells if the described stream should be buffered or not.
 boolean isPositionAware()
          Tells if the described stream is aware of its own position, and that it can reposition itself on request.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

BEFORE_FIRST

public static final long BEFORE_FIRST
Constant for the character position, when it is positioned before the first character in the stream (i.e. at the very beginning of the stream or in the header).

See Also:
Constant Field Values

dataOffset

private final long dataOffset
First data byte in the byte stream.


curBytePos

private final long curBytePos
The current byte position.


curCharPos

private final long curCharPos
The current character position.


byteLength

private final long byteLength
The byte length of the stream, 0 if unknown.


charLength

private final long charLength
The character length of the stream, 0 if unknown.


maxCharLength

private final long maxCharLength
The maximum allowed character length.


bufferable

private final boolean bufferable
Tells if the stream can be buffered or not.


positionAware

private final boolean positionAware
Tells if the stream is aware of its own position.


stream

private final java.io.InputStream stream
Reference to the stream we are describing.

Constructor Detail

CharacterStreamDescriptor

private CharacterStreamDescriptor(CharacterStreamDescriptor.Builder b)
Creates a character stream descriptor, using the supplied builder.

Use the builder to create instances of this class.

Parameters:
b - object builder
See Also:
CharacterStreamDescriptor.Builder
Method Detail

isBufferable

public boolean isBufferable()
Tells if the described stream should be buffered or not.

Some of the reasons a stream should not be buffered at this level, are the stream is already buffered, or it serves bytes directly from a byte array in memory.

Returns:
true if the stream should be buffered for improved performance, false if it should not be buffered.

isPositionAware

public boolean isPositionAware()
Tells if the described stream is aware of its own position, and that it can reposition itself on request.

Returns:
true if the stream is position aware, @{code false} otherwise.

getByteLength

public long getByteLength()

getCharLength

public long getCharLength()

getCurBytePos

public long getCurBytePos()

getCurCharPos

public long getCurCharPos()
Returns the current character position.

Returns:
The current character position, where the first character is at position 1, or BEFORE_FIRST if the stream is positioned before the first character.

getDataOffset

public long getDataOffset()
Returns the first index of the described stream that contains real data.

The information is typically used to filter out meta data at the head of the stream, and to correctly reset the stream.

Returns:
The first position in the stream containing real data.

getMaxCharLength

public long getMaxCharLength()
Returns the imposed maximum character length on the described stream.

The default value is Long.MAX_VALUE.

Returns:
The max allowed character length of the stream, or 0 if no limit has been set.

getStream

public java.io.InputStream getStream()
Returns the associated stream.

Returns:
An InputStream reference.

getPositionedStream

public PositionedStream getPositionedStream()
Returns the associated positioned stream, if the stream is position aware.

Returns:
A PositionedStream reference.
Throws:
java.lang.ClassCastException - if the stream cannot be cast to PositionedStream
java.lang.IllegalArgumentException - if the method is called and the assoicated stream isn't described as position aware.
See Also:
isPositionAware()

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

Built on Thu 2010-12-23 20:49:13+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.