# Java(tm) Communications API Users Guide

Version 2.0

License

This document provides an overview of the components of the Java(tm) communications API, which is a standard extension to the Java platform. It is not a tutorial; readers should know the basics of serial and parallel port programming, and be comfortable reading the Java communications API reference pages.

Like all Java standard extensions, the Java communications API is intended to be implementable from specification by third parties.

## `javax.comm` Extension Package

There are three levels of classes in the Java communications API:

- High-level classes like `CommPortIdentifier` and `CommPort` manage access and ownership of communication ports.
- Low-level classes like `SerialPort` and `ParallelPort` provide an interface to physical communications ports. The current release of the Java communications API enables access to serial (RS-232) and parallel (IEEE 1284) ports.
- Driver-level classes provide an interface between the low-level classes and the underlying operating system. Driver-level classes are part of the implementation but not the Java communications API. They should not be used by application programmers.

The `javax.comm` package provides the following basic services:

- Enumerate the available ports on the system. The static method `CommPortIdentifier.getPortIdentifiers` returns an enumeration object that contains a `CommPortIdentifier` object for each available port. This `CommPortIdentifier` object is the central mechanism for controlling access to a communications port.
- Open and claim ownership of communications ports by using the high level methods in their `CommPortIdentifier` objects.
- Resolve port ownership contention between multiple Java applications. Events are propagated to notify interested applications of ownership contention and allow the port's owner to relinquish ownership. `PortInUseException` is thrown when an application fails to open the port.
- Perform asynchronous and synchronous I/O on communications ports. Low-level classes like `SerialPort` and `ParallelPort` have methods for managing I/O on communications ports.
- Receive events describing communication port state changes. For example, when a serial port has a state change for Carrier Detect, Ring Indicator, DTR, etc. the `SerialPort` object propagates a `SerialPortEvent` that describes the state change.

## A Simple Reading Example

`SimpleRead.java` opens a serial port and creates a thread for asynchronously reading data through an event callback technique.

## A Simple Writing Example

`SimpleWrite.java` opens a serial port for writing data.

## Solaris Notes

The Solaris implementation of the Java communications API requires the Solaris Native Threads Pack for JDK 1.1.x.

Here's how to test the `SimpleRead.java` example above on Solaris:

1. Attach a null-modem cable between two serial ports.
2. Start `tip`(1) on one of the serial ports:

    % tip -9600 /dev/term/b

3. Compile `SimpleRead.java`:

    % javac SimpleRead.java

4. Run `SimpleRead`:

    % java -native SimpleRead

5. Type text into the `tip`(1) window.

Copyright © 1998 Sun Microsystems, Inc.
All Rights Reserved.