Class 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

      Nested Classes 
      Modifier and Type Class Description
      static class  CharacterStreamDescriptor.Builder
      The builder for the CharacterStreamDescriptor class.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      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.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
    • 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