javax.comm
Class CommPortIdentifier

java.lang.Object
  javax.comm.CommPortIdentifier

public class CommPortIdentifier

extends java.lang.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.

Author:

Jagane Sundar, Paul Klissner - Substantially re-written in 3.0

See Also:

CommPort, CommPortOwnershipListener, ParallelPort, SerialPort

Field Summary

static int	PORT_PARALLEL
static int	PORT_SERIAL

Constructor Summary

CommPortIdentifier(java.lang.String name, CommPort port, int type, CommDriver driver)
Constructor

Method Summary

static void	addPortName(java.lang.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.
java.lang.String	getCurrentOwner() Returns the owner of the port.
java.lang.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(java.lang.String portName) Obtains a CommPortIdentifier object by using a port name.
static java.util.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(java.io.FileDescriptor fd) Opens the communications port using a FileDescriptor object on platforms that support this technique.
CommPort	open(java.lang.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

See Also:

Constant Field Values

PORT_PARALLEL

public static final int PORT_PARALLEL

See Also:

Constant Field Values

Constructor Detail

CommPortIdentifier

public CommPortIdentifier(java.lang.String name,
                          CommPort port,
                          int type,
                          CommDriver driver)

Constructor

Parameters:

name - Name to give this port

port - Instantiaton of CommPort implementation

type - PORT_SERIAL or PORT_PARALLEL

driver - Driver assosciated with this port.

See Also:

CommPortIdentifier

Method Detail

getPortIdentifiers

public static java.util.Enumeration getPortIdentifiers()

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

Returns:

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

getPortIdentifier

public static CommPortIdentifier getPortIdentifier(java.lang.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:

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:

CommPortIdentifier object

Throws:

NoSuchPortException - if the port object is invalid

addPortName

public static void addPortName(java.lang.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

open

public CommPort open(java.lang.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:

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(java.io.FileDescriptor fd)
              throws UnsupportedCommOperationException

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

Parameters:

fd - The FileDescriptor associated with this CommPort.

Returns:

CommPort object.

Throws:

UnsupportedCommOperationException - on platforms which do not support this functionality.

getName

public java.lang.String getName()

Returns the name of the port.

Returns:

the name of the port

getPortType

public int getPortType()

Returns the port type.

Returns:

portType - PORT_SERIAL or PORT_PARALLEL

getCurrentOwner

public java.lang.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:

boolean true if port is owned by an application, false if port is not owned.

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 - 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