nu.dll.lyskom
Class HollerithStream

java.lang.Object
  |
  +--nu.dll.lyskom.KomToken
        |
        +--nu.dll.lyskom.Hollerith
              |
              +--nu.dll.lyskom.HollerithStream

All Implemented Interfaces:

java.io.Serializable

public class HollerithStream

extends Hollerith

A HollerithStream provides an InputStream from which the contents of a Hollerith sent from the server can be read. It's main purpose is to enable effecient handling of very large texts, where it is not desirable to allocate the entire text contents in memory. The provided InputStream is a direct interface to the LysKOM server stream, which means that care must be taken not to interfere with the regular protocol parsing. When a HollerithStream has been retreived, all further reads from the server are blocked until the object's setExhausted() method has been called, signalling to the server reader that the stream has been read and that it may continue normal parsing. The InputStream returned by getStream() MUST NOT be closed through its close() method. Also it MUST NOT be read beyond the size of the HollerithStream as reported by the HollerithStream object's getSize() method. If an application does not want to read the entire contents of the Hollerith, it MUST call the cancel() method of the HollerithStream in order to let the rest of the contents to be discarded.

Author:

Rasmus Sten

See Also:

Serialized Form

Field Summary

Fields inherited from class nu.dll.lyskom.KomToken

ARRAY, COMPL, HOLLERITH, PRIMITIVE

Method Summary

void	cancel() Equal to cancel(0).
void	cancel(int offset) Discards any remaining bytes in the InputStream, then marks the stream as exhausted.
byte[]	getContents() Returnes a byte-array containing all data in the hollerith.
int	getSize() Returns the size of the represented hollerith.
java.io.InputStream	getStream() Returns an InputStream from which the contents can be read.
boolean	isExhausted() Returns true if the provided InputStream is exhausted.
void	setExhausted() Marks the stream as exhausted.

Methods inherited from class nu.dll.lyskom.Hollerith

getContentString, toNetwork, toString

Methods inherited from class nu.dll.lyskom.KomToken

equals, getType, intValue, isEol, setContents, toInt, toInteger

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getSize

public int getSize()

Returns the size of the represented hollerith.

getStream

public java.io.InputStream getStream()

Returns an InputStream from which the contents can be read. The returned InputStream must be treated carefully in order not to bring other server I/O out of sync. All other server read operations are blocked until the stream has been read and marked as such by calling setExhausted(). If an application wants to abort reading of the InputStream, (for example, upon recognization that the data type contained therein isn't supported), it must 1) keep track of the number of bytes written so far, and 2) call the cancel() method to let the HollerithStream discard the remaining data and mark the stream as exhausted. Failure in calling setExhausted() or cancel() WILL cause LatteKOM to block indefinitely. Calling setExhausted() prematurely (before the entire contents of the hollerith has been read) WILL cause LatteKOM to loose track of the server stream and corrupt subsequent incoming data. This method may not be called once the stream has been exhausted.

Throws:

java.lang.IllegalStateException - if the stream has already been marked as exhausted

cancel

public void cancel()
            throws java.io.IOException

Equal to cancel(0). Convenience method to cancel a stream from which nothing has been read.

java.io.IOException

cancel

public void cancel(int offset)
            throws java.io.IOException

Discards any remaining bytes in the InputStream, then marks the stream as exhausted.

java.io.IOException

setExhausted

public void setExhausted()

Marks the stream as exhausted. LatteKOM will resume regular server I/O as soon as this method has been called. The application MUST NOT perform any further I/O on the supplied InputStream after this method has been called.

isExhausted

public boolean isExhausted()

Returns true if the provided InputStream is exhausted.

getContents

public byte[] getContents()

Returnes a byte-array containing all data in the hollerith. This method may only be called once, since it reads and exhausts the InputStream. If it is called on an already exhausted stream, IllegalStateException will be thrown.

Overrides:

getContents in class KomToken