javax.comm
Class CommPortIdentifier

java.lang.Object
  extended byjavax.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:

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
private static CommDriver commDriver
           
(package private)  java.lang.String copyright_notice
           
(package private)  java.lang.String license
           
private  java.util.Vector listeners
           
private static java.lang.Object lock
           
(package private)  java.lang.String name
           
(package private)  boolean owned
           
(package private)  java.lang.String owner
           
private  CommPort port
           
static int PORT_PARALLEL
           
static int PORT_SERIAL
           
private static java.lang.String portmapFilename
           
private  int portType
           
private static java.lang.String propFilename
           
(package private)  boolean waitingForPortAvailablity
           
 
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.
private static java.lang.String findConfFile(java.lang.String filename)
          Find specified conf file in directory in the specified locations.
(package private)  void fireOwnershipEvent(int type)
          Sends an CommPortOwnershipEvent to registered listeners.
 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.
(package private)  void internalClosePort()
          Internally preceipitated port close operation.
 boolean isCurrentlyOwned()
          Checks whether the port is owned.
private static CommDriver loadDriver(java.lang.String className)
          Given the class name for the driver, attempt to instantiate.
 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

portType

private int portType

commDriver

private static CommDriver commDriver

portmapFilename

private static java.lang.String portmapFilename

propFilename

private static java.lang.String propFilename

lock

private static java.lang.Object lock

port

private CommPort port

listeners

private java.util.Vector listeners

name

java.lang.String name

owner

java.lang.String owner

owned

boolean owned

waitingForPortAvailablity

boolean waitingForPortAvailablity

copyright_notice

java.lang.String copyright_notice

license

java.lang.String license
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

findConfFile

private static java.lang.String findConfFile(java.lang.String filename)
Find specified conf file in directory in the specified locations.

Parameters:
filename -
Returns:
String path to properties file or null if it cannot be located.

loadDriver

private static CommDriver loadDriver(java.lang.String className)
                              throws java.io.IOException
Given the class name for the driver, attempt to instantiate.

Parameters:
className - The fully qualified class name to look up.
Returns:
CommDriver object if found.
Throws:
java.io.IOException

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.

internalClosePort

void internalClosePort()
Internally preceipitated port close operation.


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

fireOwnershipEvent

void fireOwnershipEvent(int type)
Sends an CommPortOwnershipEvent to registered listeners.

Parameters:
type -