Device (Device I/O API 1.1)

Type Parameters:
P - the device type the descriptor is defined for.

All Superinterfaces:

java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable

All Known Subinterfaces:

ADCChannel, ATDevice, ATModem, DACChannel, GenericBufferIODevice, GenericDevice, GPIOPin, GPIOPort, I2CDevice, MMIODevice, ModemUART, PulseCounter, PWMChannel, SPIDevice, UART, WatchdogTimer, WindowedWatchdogTimer

All Known Implementing Classes:

AbstractDevice
```
public interface Device<P extends Device<? super P>>
extends java.nio.channels.Channel
```
The Device interface represents devices in the system. This interface provides generic methods for handling devices.
All devices must implement the Device interface.
When a device is open in shared mode then access synchronization may be performed by invoking tryLock and unlock. Device locks are held on a per Device instance basis. When the same device is open twice in shared access mode by the same application, locking one of the Device instances will prevent the other form being accessed/used.

Device Byte Order

Devices that perform multi-byte value I/O operations have a "native" byte order (see getByteOrder). Passing to such a device a buffer with a byte order different from its native byte order may result in byte re-ordering (byte order conversion). These byte re-ordering may have an impact on performance, memory consumption and I/O throughput. On resource-constrained platforms a device driver may throw an UnsupportedByteOrderException when a byte re-ordering may induce a detrimental loss of quality or performance.

Platform Dependencies of the Locking Facility

The tryLock and unlock methods are primarily intended to prevents other concurrently-running Java applications and threads from accessing a device locked for exclusive access, provided the device is accessed through this API. The tryLock and unlock methods may not necessarily map directly to any native locking facility of the underlying operating system. Thus a lock held on a device may not necessarily be visible to all programs that have access to the device, regardless of the language in which those programs are written. Whether or not a lock acquire through this API actually prevents another program from accessing a locked device is implementation-dependent as well as system-dependent and therefore unspecified. A compliant implementation of this specification MUST nevertheless ensure that a lock held on a device accessed through this API is visible to other threads running in the same instance of the Java virtual machine (JVM) as well to other Java applications concurrently running in different instances of that same JVM.

Since:

1.0

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`BIG_ENDIAN` Big-endian byte or bit ordering.
`static int`	`LITTLE_ENDIAN` Little-endian byte or bit ordering.
`static int`	`MIXED_ENDIAN` Mixed-endian (non-standard) byte ordering.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`close()` Closes this device, relinquishing the underlying device resource and making it available to other applications.
`java.nio.ByteOrder`	`getByteOrder()` Retrieves this device's byte order.
`<U extends P> DeviceDescriptor<U>`	`getDescriptor()` Retrieves the identifying and descriptive information of this device.
`boolean`	`isOpen()` Indicates whether or not this device is open/available to the calling application.
`void`	`tryLock(int timeout)` Attempts to lock for exclusive access the underlying device resource.
`void`	`unlock()` Releases from exclusive access the underlying device resource.

- Field Detail
  - BIG_ENDIAN
```
static final int BIG_ENDIAN
```
    Big-endian byte or bit ordering.
    
    See Also:
    Constant Field Values
  - LITTLE_ENDIAN
```
static final int LITTLE_ENDIAN
```
    Little-endian byte or bit ordering.
    
    See Also:
    Constant Field Values
  - MIXED_ENDIAN
```
static final int MIXED_ENDIAN
```
    Mixed-endian (non-standard) byte ordering.
    
    See Also:
    Constant Field Values
- Method Detail
  - tryLock
```
void tryLock(int timeout)
             throws UnavailableDeviceException,
                    ClosedDeviceException,
                    java.io.IOException
```
    Attempts to lock for exclusive access the underlying device resource. This method will block until the designated device resource becomes available for exclusive access by this Device instance or the specified amount of real time has elapsed. A timeout of 0 means to wait forever.
    This method returns silently if the underlying device resource is open in exclusive access mode or is already acquired for exclusive access (locked).
    
    Parameters:
    timeout - the timeout in milliseconds.
    
    Throws:
    
    java.lang.IllegalArgumentException - if timeout is negative.
    
    UnavailableDeviceException - if this device is still not available after the specified timeout has expired.
    
    ClosedDeviceException - if this device has been closed.
    
    java.io.IOException - if any other I/O error occurred.
  - close
```
void close()
           throws java.io.IOException
```
    Closes this device, relinquishing the underlying device resource and making it available to other applications. Upon closing the underlying device resource MUST be set to the state (power state and configuration) it was in prior to opening it.
    Once closed, subsequent operations on that very same Device instance will result in a ClosedDeviceException being thrown.
    This method has no effects if the device has already been closed.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Specified by:
    
    close in interface java.nio.channels.Channel
    
    Specified by:
    
    close in interface java.io.Closeable
    
    Throws:
    
    java.io.IOException - if an I/O error occurs.
  - isOpen
```
boolean isOpen()
```
    Indicates whether or not this device is open/available to the calling application.
    
    Specified by:
    
    isOpen in interface java.nio.channels.Channel
    
    Returns:
    true if, and only if, this device is open; false otherwise.
  - unlock
```
void unlock()
            throws java.io.IOException
```
    Releases from exclusive access the underlying device resource.
    This method returns silently if the underlying device resource is either open in exclusive access mode or is not currently acquired for exclusive access (locked) or has already been closed.
    
    Throws:
    
    java.io.IOException - if any other I/O error occurred.
  - getDescriptor
```
<U extends P> DeviceDescriptor<U> getDescriptor()
```
    Retrieves the identifying and descriptive information of this device.
    
    Type Parameters:
    U - this Device type or a subtype of it (allows for subclassing Device types - see UART and ModemUART).
    
    Returns:
    the DeviceDescriptor which encapsulates the identifying and descriptive information of this device.
  - getByteOrder
```
java.nio.ByteOrder getByteOrder()
                                throws java.io.IOException,
                                       UnavailableDeviceException,
                                       ClosedDeviceException
```
    Retrieves this device's byte order.
    The byte order is used when performing multi-byte value I/O operations.
    
    Returns:
    this buffer's byte order.
    
    Throws:
    
    java.io.IOException - if some other I/O error occurs.
    
    UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.
    
    ClosedDeviceException - if the device has been closed.
    Since:
    
    1.1

Interface Device<P extends Device<? super P>>

Device Byte Order

Platform Dependencies of the Locking Facility

Field Summary

Method Summary

Field Detail

BIG_ENDIAN

LITTLE_ENDIAN

MIXED_ENDIAN

Method Detail

tryLock

close

isOpen

unlock

getDescriptor

getByteOrder