javax.comm
Class CommPort

java.lang.Object
  javax.comm.CommPort

Direct Known Subclasses:

ParallelPort, SerialPort

public abstract class CommPort

extends java.lang.Object

A communications port. CommPort is an abstract class that describes a communications port made available by the underlying system. It includes high-level methods for controlling I/O that are common to different kinds of communications ports. SerialPort and ParallelPort are subclasses of CommPort that include additional methods for low-level control of physical communications ports.

There are no public constructors for CommPort. Instead an application should use the static method CommPortIdentifier.getPortIdentifiers to generate a list of available ports. It then chooses a port from this list and calls CommPortIdentifier.open to create a CommPort object. Finally, it casts the CommPort object to a physical communications device class like SerialPort or ParallelPort.

After a communications port has been identified and opened it can be configured with the methods in the low-level classes like SerialPort and ParallelPort. Then an IO stream can be opend for reading and writing data. Once the application is done with the port, it must call the close method. Thereafter the application must not call any methods in the port object. Doing so will cause a java.lang.IllegalStateException to be thrown.

Version:

1.12, 09 Mar 1998

Author:

Jagane Sundar

See Also:

CommPortIdentifier, ParallelPort, SerialPort

Field Summary

protected java.lang.String

name

Method Summary

void	close() Closes the communications port.
abstract void	disableReceiveFraming() Disables receive framing.
abstract void	disableReceiveThreshold() Disables receive threshold.
abstract void	disableReceiveTimeout() Disables receive timeout.
abstract void	enableReceiveFraming(int framingByte) Enables receive framing, if this feature is supported by the driver.
abstract void	enableReceiveThreshold(int thresh) Enables receive threshold, if this feature is supported by the driver.
abstract void	enableReceiveTimeout(int rcvTimeout) Enables receive timeout, if this feature is supported by the driver.
abstract int	getInputBufferSize() Gets the input buffer size.
abstract java.io.InputStream	getInputStream() Returns an input stream.
java.lang.String	getName() Gets the name of the communications port.
abstract int	getOutputBufferSize() Gets the output buffer size.
abstract java.io.OutputStream	getOutputStream() Returns an output stream.
abstract int	getReceiveFramingByte() Gets the current byte used for receive framing.
abstract int	getReceiveThreshold() Gets the integer value of the receive threshold.
abstract int	getReceiveTimeout() Gets the integer value of the receive timeout.
abstract boolean	isReceiveFramingEnabled() Checks if receive framing is enabled.
abstract boolean	isReceiveThresholdEnabled() Checks if receive threshold is enabled.
abstract boolean	isReceiveTimeoutEnabled() Checks if receive timeout is enabled.
abstract void	setInputBufferSize(int size) Sets the input buffer size.
abstract void	setOutputBufferSize(int size) Sets the output buffer size.
java.lang.String	toString() Returns a String representation of this communications port.

Methods inherited from class java.lang.Object

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

Field Detail

name

protected java.lang.String name

Method Detail

getName

public java.lang.String getName()

Gets the name of the communications port. This name should correspond to something the user can identify, like the label on the hardware.

Returns:

name of the port

toString

public java.lang.String toString()

Returns a String representation of this communications port.

Returns:

String representation of the port

getInputStream

public abstract java.io.InputStream getInputStream()
                                            throws java.io.IOException

Returns an input stream. This is the only way to receive data from the communications port. If the port is unidirectional and doesn't support receiving data, then getInputStream returns null.

The read behaviour of the input stream returned by getInputStream depends on combination of the threshold and timeout values. The possible behaviours are described in the table below:

Threshold		Timeout		Read Buffer Size	Read Behaviour
State	Value	State	Value
disabled	-	disabled	-	n bytes	block until any data is available
enabled	m bytes	disabled	-	n bytes	block until min(m,n) bytes are available
disabled	-	enabled	x ms	n bytes	block for x ms or until any data is available
enabled	m bytes	enabled	x ms	n bytes	block for x ms or until min(m,n) bytes are available

Note, however, that framing errors may cause the Timeout and Threshold values to complete prematurely without raising an exception.

Enabling the Timeout OR Threshold with a value a zero is a special case. This causes the underlying driver to poll for incoming data instead being event driven. Otherwise, the behaviour is identical to having both the Timeout and Threshold disabled.

Returns:

InputStream object that can be used to read from the port

Throws:

java.io.IOException - if an I/O error occurred

getOutputStream

public abstract java.io.OutputStream getOutputStream()
                                              throws java.io.IOException

Returns an output stream. This is the only way to send data to the communications port. If the port is unidirectional and doesn't support sending data, then getOutputStream returns null.

Returns:

OutputStream object that can be used to write to the port

Throws:

java.io.IOException - if an I/O error occurred

close

public void close()

Closes the communications port. The application must call close when it is done with the port. Notification of this ownership change will be propagated to all classes registered using addPortOwnershipListener.

enableReceiveThreshold

public abstract void enableReceiveThreshold(int thresh)
                                     throws UnsupportedCommOperationException

Enables receive threshold, if this feature is supported by the driver. When the receive threshold condition becomes true, a read from the input stream for this port will return immediately.

enableReceiveThreshold is an advisory method which the driver may not implement. By default, receive threshold is not enabled.

An application can determine whether the driver supports this feature by first calling the enableReceiveThreshold method and then calling the isReceiveThresholdEnabled method. If isReceiveThresholdEnabled still returns false, then receive threshold is not supported by the driver. If the driver does not implement this feature, it will return from blocking reads at an appropriate time.

See getInputStream for description of exact behaviour.

Parameters:

thresh - when this many bytes are in the input buffer, return immediately from read.

Throws:

UnsupportedCommOperationException - is thrown if receive threshold is not supported by the underlying driver.

disableReceiveThreshold

public abstract void disableReceiveThreshold()

Disables receive threshold.

isReceiveThresholdEnabled

public abstract boolean isReceiveThresholdEnabled()

Checks if receive threshold is enabled.

Returns:

boolean true if the driver supports receive threshold.

Since:

CommAPI 1.1

getReceiveThreshold

public abstract int getReceiveThreshold()

Gets the integer value of the receive threshold. If the receive threshold is disabled or not supported by the driver, then the value returned is meaningless.

Returns:

number of bytes for receive threshold

enableReceiveTimeout

public abstract void enableReceiveTimeout(int rcvTimeout)
                                   throws UnsupportedCommOperationException

Enables receive timeout, if this feature is supported by the driver. When the receive timeout condition becomes true, a read from the input stream for this port will return immediately.

enableReceiveTimeout is an advisory method which the driver may not implement. By default, receive timeout is not enabled.

An application can determine whether the driver supports this feature by first calling the enableReceiveTimeout method and then calling the isReceiveTimeout method. If isReceiveTimeout still returns false, then receive timeout is not supported by the driver.

See getInputStream for description of exact behaviour.

Parameters:

rcvTimeout - when this many milliseconds have elapsed, return immediately from read, regardless of bytes in input buffer.

Throws:

UnsupportedCommOperationException - is thrown if receive timeout is not supported by the underlying driver.

disableReceiveTimeout

public abstract void disableReceiveTimeout()

Disables receive timeout.

isReceiveTimeoutEnabled

public abstract boolean isReceiveTimeoutEnabled()

Checks if receive timeout is enabled.

Returns:

boolean true if the driver supports receive timeout.

getReceiveTimeout

public abstract int getReceiveTimeout()

Gets the integer value of the receive timeout. If the receive timeout is disabled or not supported by the driver, then the value returned is meaningless.

Returns:

number of milliseconds in receive timeout

enableReceiveFraming

public abstract void enableReceiveFraming(int framingByte)
                                   throws UnsupportedCommOperationException

Enables receive framing, if this feature is supported by the driver. When the receive framing condition becomes true, a read from the input stream for this port will return immediately.

enableReceiveFraming is an advisory method which the driver may not implement. By default, receive framing is not enabled.

An application can determine whether the driver supports this feature by first calling the enableReceiveFraming method and then calling the isReceiveFramingEnabled method. If isReceiveFramingEnabled still returns false, then receive framing is not supported by the driver.

Note: As implemented in this method, framing is not related to bit-level framing at the hardware level, and is not associated with data errors.

Parameters:

framingByte - this byte in the input stream suggests the end of the received frame. Blocked reads will return immediately. Only the low 8 bits of framingByte are used while the upper 24 bits are masked off. A value outside the range of 0-255 will be converted to the value of its lowest 8 bits.

Throws:

UnsupportedCommOperationException - is thrown if receive timeout is not supported by the underlying driver.

disableReceiveFraming

public abstract void disableReceiveFraming()

Disables receive framing.

isReceiveFramingEnabled

public abstract boolean isReceiveFramingEnabled()

Checks if receive framing is enabled.

Returns:

boolean true if the driver supports receive framing.

getReceiveFramingByte

public abstract int getReceiveFramingByte()

Gets the current byte used for receive framing. If the receive framing is disabled or not supported by the driver, then the value returned is meaningless. The return value of getReceiveFramingByte is an integer, the low 8 bits of which represent the current byte used for receive framing.

Note: As implemented in this method, framing is not related to bit-level framing at the hardware level, and is not associated with data errors.

Returns:

integer current byte used for receive framing

setInputBufferSize

public abstract void setInputBufferSize(int size)

Sets the input buffer size. Note that this is advisory and memory availability may determine the ultimate buffer size used by the driver.

Parameters:

size - size of the input buffer

getInputBufferSize

public abstract int getInputBufferSize()

Gets the input buffer size. Note that this method is advisory and the underlying OS may choose not to report correct values for the buffer size.

Returns:

input buffer size currently in use

setOutputBufferSize

public abstract void setOutputBufferSize(int size)

Sets the output buffer size. Note that this is advisory and memory availability may determine the ultimate buffer size used by the driver.

Parameters:

size - size of the output buffer

getOutputBufferSize

public abstract int getOutputBufferSize()

Gets the output buffer size. Note that this method is advisory and the underlying OS may choose not to report correct values for the buffer size.

Returns:

output buffer size currently in use