tcl.lang.channel
Class Channel

java.lang.Object
  tcl.lang.channel.Channel

Direct Known Subclasses:

AbstractSocketChannel, PipelineChannel, ReadInputStreamChannel, ResourceChannel, SeekableChannel, StdChannel, TclByteArrayChannel

public abstract class Channel
extends Object

The Channel class provides functionality that will be needed for any type of Tcl channel. It performs generic reads, writes, without specifying how a given channel is actually created. Each new channel type will need to extend the abstract Channel class and override any methods it needs to provide a specific implementation for.

Field Summary

protected boolean	blocking Set to false when channel is in non-blocking mode.
protected int	buffering Buffering (full,line, or none)
protected int	bufferSize Buffer size, in bytes, allocated for channel to store input or output
protected String	encoding Name of Java encoding for this Channel.
protected tcl.lang.channel.EofInputFilter	eofInputFilter The EOF input filter for this channel, which translates the EOF character.
protected tcl.lang.channel.EofOutputFilter	eofOutputFilter This OutputStream writes the EOF character, and prevents this Chanel's getOutputStream() from being closed by the chain.
protected tcl.lang.channel.EolInputFilter	eolInputFilter The EOL input filter for this channel.
protected tcl.lang.channel.EolOutputFilter	eolOutputFilter This Writer translates EOL characters on output, and performs BUFF_LINE flushes
protected InputStream	finalInputStream This InputStream is the source of processed bytes for Channel.read()
protected Reader	finalReader This Reader is the source of processed characters for Channel.read()
protected OutputStream	firstOutputStream This OutputStream is the Channel's entry into the output chain for efficient byte writes
protected Writer	firstWriter This Writer is the Channel's entry into the output chain
protected tcl.lang.channel.InputBuffer	inputBuffer The input buffer for this channel.
protected char	inputEofChar If nonzero, use this as a signal of EOF on input.
protected int	inputTranslation Input translation mode for end-of-line character
protected tcl.lang.channel.MarkableInputStream	markableInputStream Allows backtracking in the stream for this channel
protected int	mode The read, write, append and create flags are set here.
protected tcl.lang.channel.NonBlockingOutputStream	nonBlockingOutputStream This OutputStream prevents outputs from blocking on a non-blocking channel
protected tcl.lang.channel.OutputBuffer	outputBuffer This OutputStream buffers output data for the Channel
protected char	outputEofChar If nonzero, append this to a writeable channel on close.
protected int	outputTranslation Output translation mode for end-of-line character
protected InputStream	rawInputStream The underlying input stream offered by the implementation
protected OutputStream	rawOutputStream The underlying output stream offered by the implementation
static int	READ_OWNERSHIP Indicate that thread wants read ownership
int	refCount How many interpreters hold references to this IO channel?
protected tcl.lang.channel.UnicodeDecoder	unicodeDecoder The unicode decoder for reading characters on this channel
protected tcl.lang.channel.UnicodeEncoder	unicodeEncoder This Writer translates Unicode to bytes for output
static int	WRITE_OWNERSHIP Indicate tht thread wants write ownership

Method Summary

protected void	checkRead(Interp interp) Tests if this Channel was opened for reading
protected void	checkWrite(Interp interp) Tests if this Channel was opened for writing
void	close() Close the Channel.
boolean	eof() Returns true if the last read reached the end of file.
void	flush(Interp interp) Flush the Channel.
boolean	getBlocking()
int	getBuffering()
int	getBufferSize()
String	getChanName() Get the channel name
String	getEncoding() Query this Channel's encoding
char	getInputEofChar()
protected abstract InputStream	getInputStream() This method should be overridden in the subclass to provide a channel specific InputStream object.
int	getInputTranslation()
char	getOutputEofChar()
protected abstract OutputStream	getOutputStream() This method should be overridden in the subclass to provide a channel specific OutputStream object.
int	getOutputTranslation()
protected void	initInput() Setup the input stream chain on the first read
protected void	initOutput() Setup output stream chain on the first write
boolean	isBlocked(Interp interp) Tests if last read was incomplete due to a blocked channel
boolean	isClosed() Returns true of close() has been called
boolean	isReadOnly()
boolean	isReadWrite()
boolean	isWriteOnly()
int	read(Interp interp, TclObject tobj, int readType, int numBytes) Tcl_ReadChars -> read Read data from this Channel into the given TclObject.
void	seek(Interp interp, long offset, int mode) Move the current file pointer.
void	setBlocking(boolean inBlocking) Set blocking mode.
void	setBuffering(int inBuffering) Set buffering mode
void	setBufferSize(int size) Tcl_SetChannelBufferSize -> setBufferSize Sets the buffer size
void	setEncoding(String inEncoding) Set new Java encoding.
void	setInputEofChar(char inEof) Set new input eof character, if channel is readable
void	setInputTranslation(int translation) Set new input translation if this channel is not write-only
void	setOutputEofChar(char outEof) Set new output eof character if this channel is writeable
void	setOutputTranslation(int translation) Set new output translation if this channel is writeable
boolean	setOwnership(boolean takeOwnership, int type) Ask for or give up ownership to channel
boolean	setOwnership(boolean takeOwnership, int type, long threadId) Ask for or give up ownership to channel
long	tell()
void	waitForOwnership(int type) Block until ownership to this channel is granted to the current thread
void	write(Interp interp, String outStr) Tcl_WriteChars -> write Write string data to the Channel.
void	write(Interp interp, TclObject outData) Tcl_WriteObj -> write Write data to the Channel

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mode

protected int mode

The read, write, append and create flags are set here. The variables used to set the flags are found in the class TclIO.

refCount

public int refCount

How many interpreters hold references to this IO channel?

blocking

protected boolean blocking

Set to false when channel is in non-blocking mode.

inputBuffer

protected tcl.lang.channel.InputBuffer inputBuffer

The input buffer for this channel.

rawInputStream

protected InputStream rawInputStream

The underlying input stream offered by the implementation

rawOutputStream

protected OutputStream rawOutputStream

The underlying output stream offered by the implementation

eolInputFilter

protected tcl.lang.channel.EolInputFilter eolInputFilter

The EOL input filter for this channel.

eofInputFilter

protected tcl.lang.channel.EofInputFilter eofInputFilter

The EOF input filter for this channel, which translates the EOF character.

unicodeDecoder

protected tcl.lang.channel.UnicodeDecoder unicodeDecoder

The unicode decoder for reading characters on this channel

finalInputStream

protected InputStream finalInputStream

This InputStream is the source of processed bytes for Channel.read()

markableInputStream

protected tcl.lang.channel.MarkableInputStream markableInputStream

Allows backtracking in the stream for this channel

finalReader

protected Reader finalReader

This Reader is the source of processed characters for Channel.read()

eolOutputFilter

protected tcl.lang.channel.EolOutputFilter eolOutputFilter

This Writer translates EOL characters on output, and performs BUFF_LINE flushes

unicodeEncoder

protected tcl.lang.channel.UnicodeEncoder unicodeEncoder

This Writer translates Unicode to bytes for output

outputBuffer

protected tcl.lang.channel.OutputBuffer outputBuffer

This OutputStream buffers output data for the Channel

eofOutputFilter

protected tcl.lang.channel.EofOutputFilter eofOutputFilter

This OutputStream writes the EOF character, and prevents this Chanel's getOutputStream() from being closed by the chain.

nonBlockingOutputStream

protected tcl.lang.channel.NonBlockingOutputStream nonBlockingOutputStream

This OutputStream prevents outputs from blocking on a non-blocking channel

firstWriter

protected Writer firstWriter

This Writer is the Channel's entry into the output chain

firstOutputStream

protected OutputStream firstOutputStream

This OutputStream is the Channel's entry into the output chain for efficient byte writes

buffering

protected int buffering

Buffering (full,line, or none)

bufferSize

protected int bufferSize

Buffer size, in bytes, allocated for channel to store input or output

encoding

protected String encoding

Name of Java encoding for this Channel. A null value means use no encoding (binary).

inputTranslation

protected int inputTranslation

Input translation mode for end-of-line character

outputTranslation

protected int outputTranslation

Output translation mode for end-of-line character

inputEofChar

protected char inputEofChar

If nonzero, use this as a signal of EOF on input.

outputEofChar

protected char outputEofChar

If nonzero, append this to a writeable channel on close.

READ_OWNERSHIP

public static final int READ_OWNERSHIP

Indicate that thread wants read ownership

See Also:

Constant Field Values

WRITE_OWNERSHIP

public static final int WRITE_OWNERSHIP

Indicate tht thread wants write ownership

See Also:

Constant Field Values

Method Detail

read

public int read(Interp interp,
                TclObject tobj,
                int readType,
                int numBytes)
         throws IOException,
                TclException

Tcl_ReadChars -> read Read data from this Channel into the given TclObject.

Parameters:

interp - is used for TclExceptions.

tobj - the object that data will be added to.

readType - specifies if the read should read the entire input (TclIO.READ_ALL), the next line without the end-of-line character (TclIO.READ_LINE), or a specified number of bytes (TclIO.READ_N_BYTES).

numBytes - the number of bytes/chars to read. Ignored unless readType is TclIO.READ_N_BYTES.

Returns:

the number of bytes read. Returns -1 on EOF or on error.

Throws:

TclException - is thrown if read occurs on WRONLY channel.

IOException - is thrown when an IO error occurs that was not correctly tested for. Most cases should be caught.

write

public void write(Interp interp,
                  TclObject outData)
           throws IOException,
                  TclException

Tcl_WriteObj -> write Write data to the Channel

Parameters:

interp - is used for TclExceptions.

outData - the TclObject that holds the data to write.

Throws:

IOException

TclException

write

public void write(Interp interp,
                  String outStr)
           throws IOException,
                  TclException

Tcl_WriteChars -> write Write string data to the Channel.

Parameters:

interp - is used for TclExceptions.

outStr - the String object to write.

Throws:

IOException

TclException

setOwnership

public boolean setOwnership(boolean takeOwnership,
                            int type)

Ask for or give up ownership to channel

Parameters:

takeOwnership - if true, give Channel ownership to the current thread if no other thread owns it; otherwise, give up ownership if the current thread owns it

type - Either READ_OWNERSHIP or WRITE_OWNERSHIP

Returns:

If takeOwnership is true, returns true if the current thread successfully received ownership. If takeOwnership is false, returns true if the current thread was the owner of the channel.

setOwnership

public boolean setOwnership(boolean takeOwnership,
                            int type,
                            long threadId)

Ask for or give up ownership to channel

Parameters:

takeOwnership - if true, give Channel ownership to the current thread if no other thread owns it; otherwise, give up ownership if the current thread owns it

type - Either READ_OWNERSHIP or WRITE_OWNERSHIP

threadId - Thread.getId() of thread that should own the channel

Returns:

If takeOwnership is true, returns true if the current thread successfully received ownership. If takeOwnership is false, returns true if the current thread was the owner of the channel.

waitForOwnership

public void waitForOwnership(int type)
                      throws InterruptedException

Block until ownership to this channel is granted to the current thread

Parameters:

type - Either READ_OWNERSHIP or WRITE_OWNERSHIP

Throws:

InterruptedException

close

public void close()
           throws IOException

Close the Channel. The channel is only closed, it is the responsibility of the "closer" to remove the channel from the channel table. Channel subclass specific closing is done is impClose(), which is called on behalf of this method by nonBlockingOutputStream for writable channels. Note that any thread can close the channel, even if it is not the owner.

Throws:

IOException

flush

public void flush(Interp interp)
           throws IOException,
                  TclException

Flush the Channel.

Throws:

TclException - when attempting to flush a read only channel.

IOException - for all other flush errors.

seek

public void seek(Interp interp,
                 long offset,
                 int mode)
          throws IOException,
                 TclException

Move the current file pointer. Channels that support seek and tell should use SeekableChannel.

Parameters:

interp - currrent interpreter.

offset - The number of bytes to move the file pointer.

mode - where to begin incrementing the file pointer; beginning, current, end.

Throws:

TclException - if channel does not support seek

IOException

tell

public long tell()
          throws IOException

Returns:

the current file position. If tell is not supported on the given channel then -1 will be returned. Subclasses should use the SeekableChannel class to provide tell() capability.

Throws:

IOException

initInput

protected void initInput()
                  throws IOException

Setup the input stream chain on the first read

Throws:

IOException

initOutput

protected void initOutput()
                   throws IOException

Setup output stream chain on the first write

Throws:

IOException

eof

public boolean eof()

Returns true if the last read reached the end of file.

isClosed

public boolean isClosed()

Returns true of close() has been called

getInputStream

protected abstract InputStream getInputStream()
                                       throws IOException

This method should be overridden in the subclass to provide a channel specific InputStream object.

Throws:

IOException

getOutputStream

protected abstract OutputStream getOutputStream()
                                         throws IOException

This method should be overridden in the subclass to provide a channel specific OutputStream object.

Throws:

IOException

getChanName

public String getChanName()

Get the channel name

Returns:

the channel name that is the key for the chanTable hash table

isReadOnly

public boolean isReadOnly()

Returns:

true if this Channel is read-only

isWriteOnly

public boolean isWriteOnly()

Returns:

true if this channel is write-only

isReadWrite

public boolean isReadWrite()

Returns:

true if this channel is read and write accessible

checkRead

protected void checkRead(Interp interp)
                  throws TclException

Tests if this Channel was opened for reading

Parameters:

interp - the current interpreter

Throws:

TclException - if this channel was not opened for reading

checkWrite

protected void checkWrite(Interp interp)
                   throws TclException

Tests if this Channel was opened for writing

Parameters:

interp - the current interpreter

Throws:

TclException - if this Channel was not opened for writing

getBlocking

public boolean getBlocking()

Returns:

false if Channel is in non-blocking mode , true otherwise

setBlocking

public void setBlocking(boolean inBlocking)

Set blocking mode.

Parameters:

inBlocking - True for blocking mode, false for non-blocking mode.

getBuffering

public int getBuffering()

Returns:

buffering mode - TclIO.BUFF_FULL, TclIO.BUFF_LINE or TclIO.BUFF_NONE.

setBuffering

public void setBuffering(int inBuffering)

Set buffering mode

Parameters:

inBuffering - One of TclIO.BUFF_FULL, TclIO.BUFF_LINE, or TclIO.BUFF_NONE

getBufferSize

public int getBufferSize()

Returns:

the current buffer size

setBufferSize

public void setBufferSize(int size)

Tcl_SetChannelBufferSize -> setBufferSize Sets the buffer size

Parameters:

size - new buffer size. Resize request is ignored if size < 1 or > 1 Mbyte

isBlocked

public boolean isBlocked(Interp interp)
                  throws TclException

Tests if last read was incomplete due to a blocked channel

Parameters:

interp - current interpreter

Returns:

true if input if the last read on this channel was incomplete because input was blocked

Throws:

TclException - if this channel is not opened for reading

getEncoding

public String getEncoding()

Query this Channel's encoding

Returns:

Name of Channel's Java encoding (null if no encoding)

setEncoding

public void setEncoding(String inEncoding)

Set new Java encoding.

Parameters:

inEncoding - Java-style encoding string

getInputTranslation

public int getInputTranslation()

Returns:

input translation (TclIO.TRANS_*)

setInputTranslation

public void setInputTranslation(int translation)

Set new input translation if this channel is not write-only

Parameters:

translation - one of the TclIO.TRANS_* constants

getOutputTranslation

public int getOutputTranslation()

Returns:

output translation - one of the TclIO.TRANS_* constants

setOutputTranslation

public void setOutputTranslation(int translation)

Set new output translation if this channel is writeable

Parameters:

translation - one of the TclIO.TRANS_* constants

getInputEofChar

public char getInputEofChar()

Returns:

input eof character, or 0 if none defined

setInputEofChar

public void setInputEofChar(char inEof)

Set new input eof character, if channel is readable

Parameters:

inEof - new EOF character, or 0 if none

getOutputEofChar

public char getOutputEofChar()

Returns:

output eof character, or 0 if none

setOutputEofChar

public void setOutputEofChar(char outEof)

Set new output eof character if this channel is writeable

Parameters:

outEof - new EOF character, or 0 if none