jdk.dio.uart

Interface UART

All Superinterfaces:

java.lang.AutoCloseable, BufferAccess<java.nio.ByteBuffer>, java.nio.channels.ByteChannel, java.nio.channels.Channel, java.io.Closeable, Device<UART>, java.nio.channels.ReadableByteChannel, java.nio.channels.WritableByteChannel

All Known Subinterfaces:

ModemUART

public interface UART
extends Device<UART>, java.nio.channels.ByteChannel, BufferAccess<java.nio.ByteBuffer>

The UART interface provides methods for controlling and accessing a UART (Universal Asynchronous Receiver/Transmitter).

A UART device may be identified by the numeric ID and by the name (if any defined) that correspond to its registered configuration. A UART instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name. When a UART instance is opened with an ad-hoc UARTConfig configuration (which includes its hardware addressing information) using one of the DeviceManager.open(config,...) methods it is not assigned any ID nor name.

Once opened, an application can read the received data bytes and write the data bytes to be transmitted through the UART using methods of the ByteChannel interface.

An application can register a UARTEventListener instance which will get asynchronously notified of input data availability, input buffer overrun and/or empty output buffer conditions. The input and output buffers for which these events may be notified may not necessarily correspond to the transmit and receive FIFO buffers of the UART hardware but may be buffers allocated by the underlying native driver. To register a UARTEventListener instance, the application must call the setEventListener method. The registered listener can later on be removed by calling the same method with a null listener parameter.

When done, an application should call the UART.close method to close the UART. Any further attempt to access or control a UART which has been closed will result in a ClosedDeviceException been thrown.

Buffered I/O and Direct I/O Transfers

A UART may support buffered I/O or direct I/O operations depending on the capabilities of the underlying device hardware and driver.
Buffered input (resp. output) - input (resp. output) in buffering mode - may be requested by setting the input (resp. output) buffer size parameter of the UARTConfig configuration to a value greater than 0 ; whether or not the UART will indeed work in buffering mode and will use an internal input (resp. output) buffer of the size requested is up to the device driver. An application may check whether a UART is working in buffering mode by calling the UARTConfig.getInputBufferSize (resp. UARTConfig.getOutputBufferSize) method.
When a UART is not working in buffering mode, direct I/O may be enabled by providing direct Buffers to the input (resp. output) methods; whether efficient direct input (resp. output) transfers will be used depends on the underlying hardware and driver capabilities and on whether the provided buffers are suitable for such operations (see BufferAccess.prepareBuffer). Input (resp. output) methods using double buffering may only support efficient direct operations if both buffers are suitable for such operations.

Since:

1.0

See Also:

UARTPermission, ClosedDeviceException

Field Summary

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
void	generateBreak(int duration) Generates a line break for the specified duration.
int	getBaudRate() Gets the current baud rate.
int	getDataBits() Gets the current number of bits per character.
int	getFlowControlMode() Gets the current flow control mode.
int	getParity() Gets the current parity.
int	getReceiveTimeout() Gets the current receive timeout.
int	getReceiveTriggerLevel() Gets the current receive trigger level.
int	getStopBits() Gets the current number of stop bits per character.
int	read(java.nio.ByteBuffer dst) Reads a sequence of bytes from this UART into the given buffer.
void	setBaudRate(int baudRate) Sets the baud rate.
void	setDataBits(int dataBits) Sets the number of bits per character.
void	setEventListener(int eventId, UARTEventListener listener) Registers a UARTEventListener instance to monitor input data availability, input buffer overrun and/or empty output buffer conditions.
void	setFlowControlMode(int flowcontrol) Sets the flow control mode.
void	setParity(int parity) Sets the parity.
void	setReceiveTimeout(int timeout) Sets the receive timeout.
void	setReceiveTriggerLevel(int level) Sets the receive trigger level.
void	setStopBits(int stopBits) Sets the number of stop bits per character.
void	startReading(java.nio.ByteBuffer dst1, java.nio.ByteBuffer dst2, InputRoundListener<UART,java.nio.ByteBuffer> listener) Starts asynchronous reading in successive rounds.
void	startReading(java.nio.ByteBuffer dst, InputRoundListener<UART,java.nio.ByteBuffer> listener) Starts asynchronous reading in successive rounds - reading data into the provided buffer.
void	startWriting(java.nio.ByteBuffer src1, java.nio.ByteBuffer src2, OutputRoundListener<UART,java.nio.ByteBuffer> listener) Starts asynchronous writing in successive rounds.
void	startWriting(java.nio.ByteBuffer src, OutputRoundListener<UART,java.nio.ByteBuffer> listener) Starts asynchronous writing in successive rounds - initially writing the data remaining in the provided buffer.
void	stopReading() Stops (cancels) the currently active asynchronous reading session as started by a call to one of the startReading methods.
void	stopWriting() Stops (cancels) the currently active asynchronous writing session as started by a call to one of the startWriting methods.
int	write(java.nio.ByteBuffer src) Writes a sequence of bytes to this UART from the given buffer.

Methods inherited from interface jdk.dio.Device

close, getByteOrder, getDescriptor, isOpen, tryLock, unlock

Methods inherited from interface jdk.dio.BufferAccess

getInputBuffer, getOutputBuffer, prepareBuffer

Method Detail

getBaudRate

int getBaudRate()
                throws java.io.IOException,
                       UnavailableDeviceException,
                       ClosedDeviceException

Gets the current baud rate. If the baud rate was not set previously using setBaudRate the device configuration-specific default value is returned.

Returns:

the current baud rate.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

setBaudRate(int)

getDataBits

int getDataBits()
                throws java.io.IOException,
                       UnavailableDeviceException,
                       ClosedDeviceException

Gets the current number of bits per character. If the bits per character was not set previously using setDataBits the device configuration-specific default value is returned.

Returns:

the number bits per character: UARTConfig.DATABITS_5, UARTConfig.DATABITS_6, UARTConfig.DATABITS_7, UARTConfig.DATABITS_8 or UARTConfig.DATABITS_9.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

setDataBits(int)

getFlowControlMode

int getFlowControlMode()
                       throws java.io.IOException,
                              UnavailableDeviceException,
                              ClosedDeviceException

Gets the current flow control mode. If the flow control mode was not set previously using setFlowControlMode the device configuration-specific default value is returned.

Returns:

the flow control mode: UARTConfig.FLOWCONTROL_NONE if flow control is disabled; or a valid bit-wise OR combination of UARTConfig.FLOWCONTROL_RTSCTS_IN, UARTConfig.FLOWCONTROL_RTSCTS_OUT, UARTConfig.FLOWCONTROL_XONXOFF_IN or UARTConfig.FLOWCONTROL_XONXOFF_OUT.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

setFlowControlMode(int)

getParity

int getParity()
              throws java.io.IOException,
                     UnavailableDeviceException,
                     ClosedDeviceException

Gets the current parity. If the parity was not set previously using setParity the device configuration-specific default value is returned.

Returns:

the speed parity: UARTConfig.PARITY_ODD, UARTConfig.PARITY_EVEN, UARTConfig.PARITY_MARK, UARTConfig.PARITY_SPACE, or UARTConfig.PARITY_NONE.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

setParity(int)

getStopBits

int getStopBits()
                throws java.io.IOException,
                       UnavailableDeviceException,
                       ClosedDeviceException

Gets the current number of stop bits per character. If the stop bit number was not set previously using setStopBits the device configuration-specific default value is returned.

Returns:

the number of stop bits per character: UARTConfig.STOPBITS_1, UARTConfig.STOPBITS_1_5, or UARTConfig.STOPBITS_2.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

setStopBits(int)

setBaudRate

void setBaudRate(int baudRate)
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Sets the baud rate.

Parameters:

baudRate - the baud rate to set (a positive integer).

Throws:

java.lang.IllegalArgumentException - if baudRate is negative or zero.

java.lang.UnsupportedOperationException - if this UART cannot be configured with the requested baud rate.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

getBaudRate()

setDataBits

void setDataBits(int dataBits)
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Sets the number of bits per character.

Parameters:

dataBits - the number bits per character: UARTConfig.DATABITS_5, UARTConfig.DATABITS_6, UARTConfig.DATABITS_7, UARTConfig.DATABITS_8 or UARTConfig.DATABITS_9.

Throws:

java.lang.UnsupportedOperationException - if this UART cannot be configured with the requested number of bits per character.

java.lang.IllegalArgumentException - if dataBits is not one of the defined values.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

getDataBits()

setEventListener

void setEventListener(int eventId,
                    UARTEventListener listener)
                      throws java.io.IOException,
                             ClosedDeviceException

Registers a UARTEventListener instance to monitor input data availability, input buffer overrun and/or empty output buffer conditions. While the listener can be triggered by hardware interrupts, there are no real-time guarantees of when the listener will be called.

A list of event type IDs is defined in UARTEvent.

If this UART is open in DeviceManager.SHARED access mode the listeners registered by all the applications sharing the underlying device will get notified of the events they registered for.

If listener is null then the listener previously registered for the specified event type will be removed.

Only one listener can be registered at a particular time for a particular event type.

Parameters:

eventId - ID of the native event to listen to: UARTEvent.INPUT_DATA_AVAILABLE, UARTEvent.INPUT_BUFFER_OVERRUN, UARTEvent.OUTPUT_BUFFER_EMPTY, UARTEvent.BREAK_INTERRUPT, UARTEvent.FRAMING_ERROR or UARTEvent.PARITY_ERROR.

listener - the UARTEventListener instance to be notified upon occurrence of the designated event.

Throws:

java.lang.IllegalArgumentException - if eventId does not correspond to any of the supported event types.

java.lang.IllegalStateException - if listener is not null and a listener is already registered for the specified event type.

ClosedDeviceException - if the device has been closed.

java.lang.UnsupportedOperationException - if this UART does not support asynchronous event notification of the requested conditions (eg. input data availability, input buffer overrun, empty output buffer and/or error conditions).

java.io.IOException - if some other I/O error occurs.

setFlowControlMode

void setFlowControlMode(int flowcontrol)
                        throws java.io.IOException,
                               UnavailableDeviceException,
                               ClosedDeviceException

Sets the flow control mode.

Parameters:

flowcontrol - the flow control mode: UARTConfig.FLOWCONTROL_NONE if flow control is disabled; or a bit-wise OR combination of UARTConfig.FLOWCONTROL_RTSCTS_IN, UARTConfig.FLOWCONTROL_RTSCTS_OUT, UARTConfig.FLOWCONTROL_XONXOFF_IN or UARTConfig.FLOWCONTROL_XONXOFF_OUT.

Throws:

java.lang.UnsupportedOperationException - if this UART cannot be configured with the requested flow control mode.

java.lang.IllegalArgumentException - if flowcontrol is not in the defined range or if more than one input or more than one output flow control mode is specified.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

getFlowControlMode()

setParity

void setParity(int parity)
               throws java.io.IOException,
                      UnavailableDeviceException,
                      ClosedDeviceException

Sets the parity.

Parameters:

parity - the speed parity: UARTConfig.PARITY_ODD, UARTConfig.PARITY_EVEN, UARTConfig.PARITY_MARK, UARTConfig.PARITY_SPACE, or UARTConfig.PARITY_NONE.

Throws:

java.lang.UnsupportedOperationException - if this UART cannot be configured with the requested parity.

java.lang.IllegalArgumentException - if parity is not one of the defined values.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

getParity()

setStopBits

void setStopBits(int stopBits)
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Sets the number of stop bits per character.

Parameters:

stopBits - the number of stop bits per character: UARTConfig.STOPBITS_1, UARTConfig.STOPBITS_1_5, or UARTConfig.STOPBITS_2.

Throws:

java.lang.UnsupportedOperationException - if this UART cannot be configured with the requested number of stop bits per character.

java.lang.IllegalArgumentException - if stopBits is not one of the defined values.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

getStopBits()

startWriting

void startWriting(java.nio.ByteBuffer src,
                OutputRoundListener<UART,java.nio.ByteBuffer> listener)
                  throws java.io.IOException,
                         UnavailableDeviceException,
                         ClosedDeviceException

Starts asynchronous writing in successive rounds - initially writing the data remaining in the provided buffer. Additional rounds are asynchronously fetched by notifying the provided OutputRoundListener instance once the initial data have been written. The initial data to be written is retrieved from the provided buffer; the data to write during the subsequent rounds is retrieved from that very same buffer upon invocation of the provided OutputRoundListener instance.

Writing can be stopped by a call to stopWriting.

r bytes will be written to this UART, where r is the number of bytes remaining in the buffer (possibly 0), that is, src.remaining(), at the moment this method is initially invoked and then subsequently when the listener is returning.

Suppose that a byte sequence of length n is written, where 0 <= n <= r. This byte sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is initially invoked and then subsequently when the listener is returning; the index of the last byte written will be p + n - 1. Upon invocation of the listener for fetching more data to write the buffer's position will be equal to p + n; its limit will not have changed.
If this channel uses an internal output buffer and is therefore working in buffering mode the listener will only be invoked after all the r bytes have been copied to the internal output buffer; otherwise the listener will only be invoked after all the r bytes have been transferred to the driver/hardware.
The buffer's position upon stopping this asynchronous operation by a call to stopWriting is not predictable unless called from within the listener.

The data will be written according to the current baud rate as returned by getBaudRate. The baud rate and other configuration parameters can be changed by the provided OutputRoundListener instance upon notification of each round.

Upon notification of the provided OutputRoundListener the reference to the provided src buffer can be retrieved from the RoundCompletionEvent using the getBuffer method.
A buffer with 0 bytes remaining to be written (that is a buffer already empty) at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched. The underrun condition resulting from the listener notification returning with an empty buffer will be reported on the subsequent notifications through the RoundCompletionEvent.isOnError method.

Only one write operation (synchronous or asynchronous) can be going on at any time.
Note therefore that while empty output buffer conditions (UARTEvent.OUTPUT_BUFFER_EMPTY) may be notified to the registered UARTEventListener independently to the invocation of the provided OutputRoundListener attempting to call the write method from within the registered UARTEventListener will result in an exception.

Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffer until the operation (or a round thereof) has completed. Interfering with the asynchronous operation by accessing and modifying the provided buffer concurrently may yield unpredictable results.

Parameters:

src - the buffer for the data to be written.

listener - the OutputRoundListener instance to be notified when the all the data remaining in the buffer has been written.

Throws:

java.lang.NullPointerException - if src or listener is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalArgumentException - if the provided buffer src has a zero-capacity.

java.lang.IllegalStateException - if another synchronous or asynchronous output operation is already active.

java.io.IOException - if some other I/O error occurs such as the device is not writable.

startWriting

void startWriting(java.nio.ByteBuffer src1,
                java.nio.ByteBuffer src2,
                OutputRoundListener<UART,java.nio.ByteBuffer> listener)
                  throws java.io.IOException,
                         UnavailableDeviceException,
                         ClosedDeviceException

Starts asynchronous writing in successive rounds.

This method behaves identically to startWriting(ByteBuffer, OutputRoundListener) excepts that it uses double-buffering - the provided buffers must not have a zero-capacity and must not overlap - that is their backing arrays or the memory regions they refer to must not overlap. Notification will happen when all the data remaining in the current working buffer (initially src1) has been written and writing will proceed with the alternate buffer (which will become the current working buffer). Writing will only be suspended if the previous event has not yet been handled. Also, the position of the current working buffer upon stopping this asynchronous operation by a call to stopWriting is not predictable even if called from within the listener.

Upon notification of the provided OutputRoundListener the reference to the current working buffer (initially src1) can be retrieved from the RoundCompletionEvent using the getBuffer method.
A working buffer with 0 bytes remaining to be written (that is a buffer already empty) at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched. The underrun condition resulting from the listener notification returning with an empty buffer will be reported on the subsequent notifications through the RoundCompletionEvent.isOnError method.

Only one write operation (synchronous or asynchronous) can be going on at any time.
Note therefore that while empty output buffer conditions (UARTEvent.OUTPUT_BUFFER_EMPTY) may be notified to the registered UARTEventListener independently from the invocation of the provided OutputRoundListener attempting to call the write method from within the registered UARTEventListener will result in an exception.

Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffers until the operation (or a round thereof) has completed. Interfering with the asynchronous operation by accessing and modifying the provided buffers concurrently may yield unpredictable results.

Parameters:

src1 - the first buffer for the data to be written.

src2 - the second buffer for the data to be written.

listener - the OutputRoundListener instance to be notified when all the data remaining in the working buffer has been written.

Throws:

java.lang.NullPointerException - if src1, src2 or listener is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous output operation is already active.

java.lang.IllegalArgumentException - if any of the buffers src1 and src2 has a zero-capacity or if they are the same or overlap.

java.io.IOException - if some other I/O error occurs such as the device is not writable.

stopWriting

void stopWriting()
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Stops (cancels) the currently active asynchronous writing session as started by a call to one of the startWriting methods.

This method return silently if no writing session is currently active.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

startReading

void startReading(java.nio.ByteBuffer dst,
                InputRoundListener<UART,java.nio.ByteBuffer> listener)
                  throws java.io.IOException,
                         UnavailableDeviceException,
                         ClosedDeviceException

Starts asynchronous reading in successive rounds - reading data into the provided buffer. The provided InputRoundListener is cyclicly notified when the provided buffer has been filled with input data. Reading into the buffer and notification will only resume once the event has been handled. Reading and notification will immediately start and will repeat until it is stopped by a call to stopReading.

r bytes will be read from this UART, where r is the number of bytes remaining in the buffer (possibly 0), that is, dst.remaining(), at the moment this method is initially invoked and then subsequently when the listener is returning.

Suppose that a byte sequence of length n is read, where 0 <= n <= r. This byte sequence will be transferred into the buffer so that the first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position at the moment this method is initially invoked and then subsequently when the listener is returning. Upon invocation of the listener for fetching more data to write the buffer's position will be equal to p + n; its limit will not have changed.
If this channel uses an internal input buffer and is therefore working in buffering mode the listener will only be invoked after all the r bytes have been copied from the internal input buffer; otherwise the listener will only be invoked after all the r bytes have been transferred from the driver/hardware.
The buffer's position upon stopping this asynchronous operation by a call to stopReading is not predictable unless called from within the listener.

The data will be read according to the current baud rate as returned by getBaudRate. The baud rate and other configuration parameters can be changed by the provided InputRoundListener instance upon notification of each round.

Upon notification of the provided InputRoundListener the reference to the provided dst buffer can be retrieved from the RoundCompletionEvent using the getBuffer method.
A buffer with 0 bytes remaining to be read (that is a buffer already full) at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched. The overrun condition resulting from the listener notification returning with an already-full buffer will be reported on the subsequent notifications through the RoundCompletionEvent.isOnError method.

Only one read operation (synchronous or asynchronous) can be going on at any time.
Note therefore that while the availability of new input data (UARTEvent.INPUT_DATA_AVAILABLE) may be notified to the registered UARTEventListener independently from the invocation of the provided InputRoundListener attempting to call the read method from within the registered UARTEventListener will result in an exception.

Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffer until the operation (or a round thereof) has completed. Interfering with the asynchronous operation by accessing and modifying the provided buffer concurrently may yield unpredictable results.

Parameters:

dst - the buffer for the data to be read.

listener - the InputRoundListener instance to be notified when the all remaining space in the buffer has been filled with input data.

Throws:

java.lang.NullPointerException - if src or listener is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalArgumentException - if the provided buffer dst has a zero-capacity.

java.lang.IllegalStateException - if another synchronous or asynchronous input operation is already active.

java.io.IOException - if some other I/O error occurs such as the device is not readable.

startReading

void startReading(java.nio.ByteBuffer dst1,
                java.nio.ByteBuffer dst2,
                InputRoundListener<UART,java.nio.ByteBuffer> listener)
                  throws java.io.IOException,
                         UnavailableDeviceException,
                         ClosedDeviceException

Starts asynchronous reading in successive rounds.

This method behaves identically to startReading(ByteBuffer, InputRoundListener) excepts that it uses double-buffering - the provided buffers must not have a zero-capacity and must not overlap - that is the backing array sections or memory regions they refer to must not overlap. Notification will happen when all the remaining space in the current working buffer (initially dst1) has been filled and reading will proceed with the alternate buffer (which will become the current working buffer). Reading will only be suspended if the previous event has not yet been handled. Also, the position of the current working buffer upon stopping this asynchronous operation by a call to stopReading is not predictable even if called from within the listener.

Upon notification of the provided InputRoundListener the reference to the current working buffer (initially dst1) can be retrieved from the RoundCompletionEvent using the getBuffer method.
A buffer with 0 bytes remaining to be read (that is a buffer already full) at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched. The overrun condition resulting from the listener notification returning with an already-full buffer will be reported on the subsequent notifications through the RoundCompletionEvent.isOnError method.

Only one read operation (synchronous or asynchronous) can be going on at any time.
Note therefore that while the availability of new input data (UARTEvent.INPUT_DATA_AVAILABLE) may be notified to the registered UARTEventListener independently from the invocation of the provided InputRoundListener attempting to call the read method from within the registered UARTEventListener will result in an exception.

Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffers until the operation (or a round thereof) has completed. Interfering with the asynchronous operation by accessing and modifying the provided buffers concurrently may yield unpredictable results.

Parameters:

dst1 - the first buffer for the data to be read.

dst2 - the second buffer for the data to be read.

listener - the InputRoundListener instance to be notified when all the space remaining in the working buffer has been filled with input data.

Throws:

java.lang.NullPointerException - if dst1, dst2 or listener is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous input operation is already active.

java.lang.IllegalArgumentException - if any of the buffers dst1 and dst2 has a zero-capacity or if they are the same or overlap.

java.io.IOException - if some other I/O error occurs such as the device is not readable.

stopReading

void stopReading()
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Stops (cancels) the currently active asynchronous reading session as started by a call to one of the startReading methods.

This method return silently if no reading session is currently active.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

generateBreak

void generateBreak(int duration)
                   throws java.io.IOException,
                          UnavailableDeviceException,
                          ClosedDeviceException

Generates a line break for the specified duration.

The operation will return only after the generation of the line break.

The line break duration is expressed in milliseconds; if the underlying platform or driver does not support a milliseconds resolution or does not support the requested duration value then duration will be rounded down to accommodate the supported resolution or respectively aligned to the closest lower supported discrete duration value.

Parameters:

duration - duration of the line break to generate, in milliseconds.

Throws:

java.lang.IllegalArgumentException - if duration is negative.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.UnsupportedOperationException - if this UART does not support line break generation.

java.io.IOException - if some other I/O error occurs.

setReceiveTriggerLevel

void setReceiveTriggerLevel(int level)
                            throws java.io.IOException,
                                   UnavailableDeviceException,
                                   ClosedDeviceException

Sets the receive trigger level. The UARTEventListener instance registered for UARTEvent.INPUT_DATA_AVAILABLE events (if any) will get notified after the specified number of bytes have been received in the input buffer. If a synchronous read operation is on-going it may then immediately return with the number of bytes already read.

If level is zero then receive trigger is disabled.

Parameters:

level - the trigger level, in bytes.

Throws:

java.lang.IllegalArgumentException - if level is negative.

java.lang.UnsupportedOperationException - if this UART does not support receive trigger.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

getReceiveTriggerLevel()

getReceiveTriggerLevel

int getReceiveTriggerLevel()
                           throws java.io.IOException,
                                  UnavailableDeviceException,
                                  ClosedDeviceException

Gets the current receive trigger level. By default, receive trigger is disabled. If enabled, the value returned may differ from the value previously set using set previously using setReceiveTriggerLevel as it may have been adjusted to account for level values supported by the underlying platform or driver.

Returns:

the trigger level, in bytes; 0 if receive trigger is disabled; -1 if receive trigger is not supported.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

setReceiveTriggerLevel(int)

setReceiveTimeout

void setReceiveTimeout(int timeout)
                       throws java.io.IOException,
                              UnavailableDeviceException,
                              ClosedDeviceException

Sets the receive timeout. The UARTEventListener instance registered for UARTEvent.INPUT_DATA_AVAILABLE events (if any) will get notified if there is at least one byte in the input buffer and the specified timeout has elapsed. If a synchronous read operation is on-going when the timeout has elapsed it will immediately return with the number of bytes already read, possibly zero.

The receive timeout is expressed in milliseconds; if the underlying platform or driver does not support a milliseconds resolution or does not support the requested timeout value then timeout will be rounded down to accommodate the supported resolution or respectively aligned to the closest lower supported discrete timeout value. The resulting, actual timeout can be retrieved by a call to getReceiveTimeout.

If timeout is equal to zero then a synchronous read operation will not block; it will read from the bytes already available (possibly zero) and will return immediately. If timeout is equal to Integer.MAX_VALUE then receive timeout is disabled.

Parameters:

timeout - the timeout, in milliseconds.

Throws:

java.lang.IllegalArgumentException - if timeout is negative.

java.lang.UnsupportedOperationException - if this UART does not support receive timeout.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

getReceiveTimeout()

getReceiveTimeout

int getReceiveTimeout()
                      throws java.io.IOException,
                             UnavailableDeviceException,
                             ClosedDeviceException

Gets the current receive timeout. By default, receive timeout is disabled. If enabled, the value returned may differ from the value previously set using set previously using setReceiveTimeout as it may have been adjusted to account for the timer resolution or discrete timeout values supported by the underlying platform or driver.

Returns:

the timeout, in milliseconds; Integer.MAX_VALUE if receive timeout is disabled; -1 if receive timeout is not supported.

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

See Also:

setReceiveTimeout(int)

read

int read(java.nio.ByteBuffer dst)
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Reads a sequence of bytes from this UART into the given buffer.

r bytes will be read from this device, where r is the number of bytes remaining in the buffer, that is, dst.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is read, where 0 <= n <= r . This byte sequence will be transferred into the buffer so that the first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position at the moment this method is invoked. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

A read operation might not fill the buffer. It is guaranteed, however, that if there is at least one byte remaining in the buffer then this method will block until the requested number of bytes are read or otherwise transferred from the driver/hardware, or the receive trigger level (if set) has been reached, or the receive timeout (if set) has elapsed. If this channel uses an internal input buffer and is therefore working in buffering mode this method will block under the same conditions until the requested number of bytes have been copied from the internal input buffer, or the receive trigger level (if set) has been reached, or the receive timeout (if set) has elapsed.
The availability of new input data may be notified through an UARTEvent with ID UARTEvent.INPUT_DATA_AVAILABLE according to the receive trigger level or receive timeout (if set); if this method is invoked within a listener to handle an INPUT_DATA_AVAILABLE event then care should be taken to account for any concurrent synchronous read operation that may have also been unblocked by that event and that may have already read all or part of the received bytes that triggered the event.

This method may be invoked at any time. If another thread has already initiated a synchronous read upon this device, however, then an invocation of this method will block until the first operation is complete.

Only one read operation (synchronous or asynchronous) can be going on at any time.

Specified by:

read in interface java.nio.channels.ReadableByteChannel

Parameters:

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read into dst, possibly zero.

Throws:

java.lang.NullPointerException - if dst is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if an I/O error occurred such as the device is not readable.

java.lang.IllegalStateException - if an asynchronous reading is already active.

See Also:

setReceiveTriggerLevel, setReceiveTimeout

write

int write(java.nio.ByteBuffer src)
          throws java.io.IOException,
                 UnavailableDeviceException,
                 ClosedDeviceException

Writes a sequence of bytes to this UART from the given buffer.

r bytes will be written to this device, where r is the number of bytes remaining in the buffer, that is, src.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is written, where 0 <= n <= r . This byte sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is invoked; the index of the last byte written will be p + n - 1. Upon return the buffer's position will be equal to p + n; its limit will not have changed.
This operation will block until the requested r bytes have been written or otherwise transferred to the driver/hardware. If this channel uses an internal output buffer and is therefore working in buffering mode this method will block until all the r bytes have been copied to the internal output buffer.
An empty output buffer condition may be notified through an UARTEvent with ID UARTEvent.OUTPUT_BUFFER_EMPTY; if this method is invoked within a listener to handle an OUTPUT_BUFFER_EMPTY event then care should be taken to account for any concurrent synchronous write operation that may have also been unblocked by that same condition and that may have already written bytes filling all or part of the available buffer space.

This method may be invoked at any time. If another thread has already initiated a synchronous write operation upon this device, however, then an invocation of this method will block until the first operation is complete.

Only one write operation (synchronous or asynchronous) can be going on at any time.

Specified by:

write in interface java.nio.channels.WritableByteChannel

Parameters:

src - The buffer from which bytes are to be retrieved

Returns:

The number of bytes written from src, possibly zero.

Throws:

java.lang.NullPointerException - if src is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if an I/O error occurred such as the device is not writable.

java.lang.IllegalStateException - if an asynchronous writing is already active.