javax.comm
Class CommPortIdentifier

java.lang.Object
  javax.comm.CommPortIdentifier

public class CommPortIdentifier

extends Object

Communications port management. CommPortIdentifier is the central class for controlling access to communications ports. It includes methods for:

• Determining the communications ports made available by the driver.
• Opening communications ports for I/O operations.
• Determining port ownership.
• Resolving port ownership contention.
• Managing events that indicate changes in port ownership status.

An application first uses methods in CommPortIdentifier to negotiate with the driver to discover which communication ports are available and then select a port for opening. It then uses methods in other classes like CommPort, ParallelPort and SerialPort to communicate through the port.

See Also:

CommPort, CommPortOwnershipListener, ParallelPort, SerialPort

Field Summary

static int	PORT_PARALLEL IEEE 1284 parallel port
static int	PORT_SERIAL RS-232 serial port

Method Summary

static void	addPortName(String portName, int portType, CommDriver driver) Adds portName to the list of ports.
void	addPortOwnershipListener(CommPortOwnershipListener listener) Registers an interested application so that it can receive notification of changes in port ownership.
String	getCurrentOwner() Returns the owner of the port.
String	getName() Returns the name of the port.
static CommPortIdentifier	getPortIdentifier(CommPort port) Obtains the CommPortIdentifier object corresponding to a port that has already been opened by the application.
static CommPortIdentifier	getPortIdentifier(String portName) Obtains a CommPortIdentifier object by using a port name.
static Enumeration	getPortIdentifiers() Obtains an enumeration object that contains a CommPortIdentifier object for each port in the system.
int	getPortType() Returns the port type.
boolean	isCurrentlyOwned() Checks whether the port is owned.
CommPort	open(FileDescriptor fd) Opens the communications port using a FileDescriptor object on platforms that support this technique.
CommPort	open(String appname, int timeout) Opens the communications port.
void	removePortOwnershipListener(CommPortOwnershipListener listener) Deregisters a CommPortOwnershipListener registered using addPortOwnershipListener

Methods inherited from class java.lang.Object

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

Field Detail

PORT_SERIAL

public static final int PORT_SERIAL

RS-232 serial port

See Also:

Constant Field Values

PORT_PARALLEL

public static final int PORT_PARALLEL

IEEE 1284 parallel port

See Also:

Constant Field Values

Method Detail

getPortIdentifiers

public static Enumeration getPortIdentifiers()

Obtains an enumeration object that contains a CommPortIdentifier object for each port in the system.

Returns:

an Enumeration object that can be used to enumerate all the ports known to the system

See Also:

Enumeration

getPortIdentifier

public static CommPortIdentifier getPortIdentifier(String portName)
                                            throws NoSuchPortException

Obtains a CommPortIdentifier object by using a port name. The port name may have been stored in persistent storage by the application.

Parameters:

portName - name of the port to open

Returns:

a CommPortIdentifier object

Throws:

NoSuchPortException - if the port does not exist

getPortIdentifier

public static CommPortIdentifier getPortIdentifier(CommPort port)
                                            throws NoSuchPortException

Obtains the CommPortIdentifier object corresponding to a port that has already been opened by the application.

Parameters:

port - a CommPort object obtained from a previous open

Returns:

a CommPortIdentifier object

Throws:

NoSuchPortException - if the port object is invalid

addPortName

public static void addPortName(String portName,
                               int portType,
                               CommDriver driver)

Adds portName to the list of ports.

Parameters:

portName - The name of the port being added

portType - The type of the port being added

driver - The driver representing the port being added

Since:

CommAPI 1.1

See Also:

CommDriver

getName

public String getName()

Returns the name of the port. The port name should be identifiable by the user. Ideally, it should be the label on the hardware. For example, "COM1" and "COM2" on PCs; "Serial A" and "Serial B" on Sun Ultra workstations. The port name may be stored by an application and subsequently used to create a CommPortIdentifier object using getPortIdentifier(String portName) method.

Returns:

the name of the port

getPortType

public int getPortType()

Returns the port type.

Returns:

e.g. PORT_SERIAL or PORT_PARALLEL

getCurrentOwner

public String getCurrentOwner()

Returns the owner of the port.

Returns:

current owner of the port.

isCurrentlyOwned

public boolean isCurrentlyOwned()

Checks whether the port is owned.

Returns:

true if the port is owned by some application, false if the port is not owned.

open

public CommPort open(String appname,
                     int timeout)
              throws PortInUseException

Opens the communications port. open obtains exclusive ownership of the port. If the port is owned by some other application, a PORT_OWNERSHIP_REQUESTED event is propagated using the CommPortOwnershipListener event mechanism. If the application that owns the port calls close during the event processing, then this open will succeed.

There is one InputStream and one OutputStream associated with each port. After a port is opened with open, then all calls to getInputStream will return the same stream object until close is called.

Parameters:

appname - Name of application making this call. This name will become the owner of the port. Useful when resolving ownership contention.

timeout - time in milliseconds to block waiting for port open.

Returns:

a CommPort object

Throws:

PortInUseException - if the port is in use by some other application that is not willing to relinquish ownership

open

public CommPort open(FileDescriptor fd)
              throws UnsupportedCommOperationException

Opens the communications port using a FileDescriptor object on platforms that support this technique.

Parameters:

fd - The FileDescriptor object used to build a CommPort.

Returns:

a CommPort object.

Throws:

UnsupportedCommOperationException - is thrown on platforms which do not support this functionality.

addPortOwnershipListener

public void addPortOwnershipListener(CommPortOwnershipListener listener)

Registers an interested application so that it can receive notification of changes in port ownership. This includes notification of the following events:

• PORT_OWNED: Port became owned
• PORT_UNOWNED: Port became unowned
• PORT_OWNERSHIP_REQUESTED: If the application owns this port and is willing to give up ownership, then it should call close now.

The ownershipChange method of the listener registered using addPortOwnershipListener will be called with one of the above events.

Parameters:

listener - a CommPortOwnershipListener callback object

removePortOwnershipListener

public void removePortOwnershipListener(CommPortOwnershipListener listener)

Deregisters a CommPortOwnershipListener registered using addPortOwnershipListener

Parameters:

listener - The CommPortOwnershipListener object that was previously registered using addPortOwnershipListener