Java(tm) Communications API Portmapping

                                Version 3.0

                                                                            License


INTRODUCTION TO PORTMAPPING:

Portmapping configuration allows administrators to customize how the CommPortIdentifier list is populated, and therefore which devices are available to applications. Through the portmap.conf file the administrator can create descriptive aliases to replace default names that are otherwise assigned to ports.  Portmapping is an implementation specific feature that is not defined in the API.  Currently this portmapping scheme it is only offered in Sun's implementation of javax.comm for Solaris and Linux.  It is possible that at some point a Java Specification Request (JSR) can be created to expand the CommAPI to allow a pluggable portmapping strategy in a future release.

The portmap.conf file consists of lines.  Each non-commented line is referred to as a portmapping entry. One of the more powerful types of portmapping entry is the Automatic Logical Name (ALN), which is a shorthand notation used to refer to ports on USB-to-Serial converters (AKA 'dongles') that can be connected to Sun Rays to provide them RS-232 interfaces.  ALNs allow the administrator to refer to a dongle's ports without having to specify the filesystem-specific path to the device, and without having to create softlinks in the filesystem.  Besides making configuration much simpler, ALNs also make DTU replacement easier.

Other portmap entries are provided to allow server ports to be visible in Sun Ray sessions, as by default a Sun Ray can only see ports on connected dongles, and only via the port's default name.

The format of portmap.conf has changed substantially in version 3.0.  In previous releases, the portmapping configuration file was called portmap.properties, however starting javax.comm 3.0 it is called portmap.conf.  All of the previous portmapping functionality has been subsumed into the new feature set and is now embodied in the DTU Assigned portmap entry type.

Each portmap entry type in portmap.conf has a disposition, syntax and privilege.  These qualities describe how a portmap entry is identified, under which circumstances such an entry will be active, and when the represented port is visible to the application.  Generally when a portmap entry is active (ie. meets all criteria to enable it), the alias provided for the represented port will be offered in the port list instead of a physical path or default name for the port.

There are two broad catagories of portmap file entries:  session dependent, and session independent.  These refer to whether a rule applies to a Sun Ray sessions or not. Session dependent entries are active only if the javax.comm JVM is running in a SunRay session, otherwise session independent entries are activated.  Therefore, if javax.comm is not running in a Sun Ray environment,  session dependent entries have no function.

The following types of processes are not considered Sun Ray sessions: 
  •     Processes running as daemons
  •     Processes logged into the system console
  •     Processes logged in via ssh, rsh, or telnet.


DEFAULT BEHAVIOR:

If portmap.conf is not present, cannot be located, is empty, or contains unusable information, javax.comm uses a default portmapping strategy.  Default behavior differs depending upon whether javax.comm is run in a Sun Ray session or not.  If the JVM is running outside of a Sun Ray session, the locations searched for comm. port devices are specified in the platform-specific javax.comm.properties file.  That required configuration file is distributed with defaults port paths setup to locate commonly used ports for the represented platform.  (This is a new feature in the Sun distribution as of javax.comm 3.0).

 Note: See the comments in javax.comm.properties file if you need to modify, add or delete port paths to javax.comm for any reason

Default behavior when the JVM is running in a Sun Ray session is to list all the ports on all dongles attached to the current Sun Ray.

Default Port Names:

If no portmap entry exists to override the default name assigned to ports, the default name is used.  Default port names are the names given to CommPortIdentifiers, and are created differently by javax.comm depending on whether the port is on the server chassis (or serial port expansion card plugged into a server bus), or if the port is on a dongle attached to a Sun Ray.   The default name used for server ports is the full device path to the port device node.  The name given to Sun Ray dongle ports is the final namespace element in the dongle device path, which is typically the dongle's vendor name as represented to the filesystem by the dongle driver.


LOCATING portmap.conf:

When the CommPortIdentifiers.getPortIdentifiers() method is initially invoked by the application, javax.comm first attempts to locate and parse a file called portmap.conf .

 Note:
  In previous releases portmap.conf was called portmap.properties


An example of this portmap.conf can be found here

In javax.comm 3.0 the following search order is used to locate portmap.conf (If the search fails,
default portmapping is used):

            1.  Current directory. 
            2.  Each directory in ${java.classpath}   (ie.  $CLASSPATH or -classpath setting).
            3. <java installation dir>/lib. 
            4. <java installation dir>/jre/lib. 

NOTE: <java installation dir> refers to the directory the JVM is launched from. 
It is not necessarily the value of $JAVA_HOME.


PARSING portmap.conf:

If portmap.conf is located, it's contents will modify portmapping behavior accordingly.  During parsing of portmap.conf, any text that is commented with '#' is ignored.  A comment begins as soon as a '#' character is encountered and remains in effect until the end of the line.  Blank lines are ignored.

This document describes the format and action of each type of portmap entry allowed.  Parsing errors are not displayed by default.  Each rejected line in portmap.conf is silently discarded, unless the administrator enables the debugging option to log portmap parsing errors.
 
Please see this usage example (PDF) of portmap.conf for more information.

DEBUGGING the portmapping configuration file:

The debug_portmap property is used to enable logging of portmap.conf errors when launching the JVM.

Example:  $ java  -Ddebug_portmap  myTargetApplicationClassFile

When debug_portmap is enabled, portmapping errors and portmap path translation during CommPort.open() are displayed on stderr.  An even more informative dump is enabled with -Ddebug_portmap=all, which additionally displays how successfully parsed entries were interpreted.


ALNs (Automatic Logical Names):

The purpose of an ALN is to be able to refer to a port on a dongle without the application or administrator ever needing to know the device path in the filesystem.  ALNs are designed to greatly simplify configuration, and make Sun Ray (DTU) replacement very easy.  When ALNs are used, all that is required to swap out a DTU is to update the Terminal ID in the corresponding  DTU Alias  entry in portmap.conf.

ALNs are automatic in the sense that they are automatically translated into the full path of the of dongle port by javax.comm when when  getCommPortIdentifer()  or  getCommPortIdentifiers()  are called.   portmap.conf is loaded only once and parsed when javax.comm is loaded.  If portmap.conf is modified, the JVM must be re-started for the changes to take effect.

Examples of ALNs:

         utcom1      - Refers to the first serial port on the target dongle.
         utcom2      - Refers to the 2nd serial port on the target dongle.
              ...
         utcom<n> - Refers to the nth serial port on the target dongle.


         utprt1        - Refers to the first parallel port on the target dongle.
         utprt2        - Refers to the 2nd parallel port on the target dongle.
              ...
         utprt<n>    - Refers to the nth parallel port on the target dongle.


See Session Local ALN and DTU Specific ALN for more information on ALNS. 


Summary of portmap.conf entry types:

Path Alias Create an a descriptive name (alias) for a port path.
DTU Alias Name a DTU  (ie. assign a name to a Sun Ray Terminal ID).
DTU Assigned Make a server port available to a particular Sun Ray DTU.
Globally Visible
Make a workstation or server port available to all Sun Ray DTUs.
Session Local ALN Refer to port on a dongle connected to session's current DTU.
DTU Specific ALN Refer to port on a dongle connected to arbitrary DTU.
Hidden Omit a path from commPort identifier list.



        DTU alias  - 
Assign alias to a Sun Ray DTU

Syntax:
<alias>  =  <Terminal ID>        
<alias>  =  <DTU Mac Addr>

Disposition: Session Independent
Privilege: None
Examples: Teller1   =   02:5f:39:93:ab:92
Kiosk     =   IEEE802.5abc2309fc29

A DTU must be given a name in order to make reference it in portmap.conf, and after the alias is assigned, all references to th Sun Ray DTU must thereafter made using its alias. 
 
The reason for thes restriction is to enforce the policy of clarity, simplicity and ease of DTU replacement.

DERIVING TERMINAL ID:

Chord method:

The easiest way to derive the MAC address of a Sun Ray DTU, which  is used on Sun Ray to form the terminal ID, is to press the 'chord' (three buttons) simultaneously. The 'chord' is comprised of the leftmost three buttons in a row of four buttons above the numeric keypad.  These three buttons are mute, volume +, and volume -, respectively  (each has an icon of a speaker device).

Directory lookup method:

An alternative way to determine the MAC address of a DTU is to login on the DTU and type at the shell prompt echo $DISPLAY (using only the part of the number that precedes the dot.  For example DISPLAY = :21.0 meands the display number is '21'.  Assuming the display number is 21, the following will display the terminal ID:

      % ls -l /tmp/SUNWut/sessions/21/unit

This will display a link to a path whose final path element is the DTU terminal ID




       
DTU Assigned  Bind server side port to a particular DTU

Syntax: <alias> = DTU Alias : <physical path to server port>
Disposition: Session Dependent
Privilege: None
Examples: Central Printer = Joes_SunRay:/dev/term/a
DTU Assigned aliases allow the administrator to make a server port to show up in the  CommPortIdentifier list of a specific DTU, and only on the specified DTU.  

By default server ports are not available to Sun Ray session.  DTU Assigned aliases are NOT the recommended method for referring to dongle ports as that requires cluttering the environment with device links which are difficult to administer and maintain.   The preferred way to configure dongle ports is with
Session Local ALNs, and DTU Specific ALNs.

DTU Assigned aliases enable applications running on a Sun Rays to access a devices connected to a server port as if the devices were physically connected to a Sun Ray dongle port.  




       
Globally Visible  Make server side port available to all DTUs

Syntax: <alias> = * : <physical path to server port>
Disposition: Session Dependent
Privilege: None
Examples: Central_Logger = *:/dev/term/a
shared_printer  = *:/dev/ecpp0
Globally Visible aliases allow the administrator to make a server port to show up in the CommPortIdentifier list within sessions running on all Sun Ray DTUs.  In all other ways, Globally Visible aliases are identical to DTU Assigned aliases.

Globally Visible aliases are called 'Session Dependent' because, even though they are visible to all Sun Ray sessions, the alias is not active unless inside a Sun Ray session.  To provide an alias that goes into effect for a port outside of a Sun Ray session, use a Path Alias.




        Path Alias  Define alias to substitute for pathname reference

Syntax: <alias> = <filesystem path to comm. port>
Disposition: Session Independent
Privilege: None
Examples: Central_Logger = /dev/term/a
shared_printer  = /dev/ecpp0

Path Aliases allows descriptive names to be given to device paths that javax.comm locates during its default device search.  The alias is offered in lieu of the path name, and applies only to applications running on a  workstation or server.  They Path Aliases do not appear in Sun Ray sessions.  The proper way to use an alias to be seen in a Sun Ray session is with a DTU Assigned entry or a Globally Visible entry. 

A Path Alias cannot be used to refer to arbitrary devices. The mechanism used to define new devices for javax.comm to be aware of is by adding them to the javax.comm.properties file.  The format of that file is described in the comments of the one that comes with the distribution.





       Hidden
   Omit port path from CommPortIdentifier list

Syntax: [hide]   <filesystem path to comm. port>
Disposition: Session Independent
Privilege: None
Examples:
[hide] /dev/term/a
[hide] /dev/cua/b

Hidden aliases are kept them from appearing in the  CommPortIdentifier  list.  This type of portmap entry is similar to path alias, except that rather than providing a different name for a device the device is not shown.

   


        Session local ALN
   - 
Assign alias to dongle port on session's local DTU

Syntax: <alias> = ALN

Session Dependent
Privilege: None
Examples: local_printer = utprt1
cashdrawer  = utcom1
A Session Local ALN provides an abbreviated way to access ports on a dongle connected to the local DTU.  If the session migrates to a new DTU, the ALN will refer to the corresponding port on the dongle of the new DTU, if any.  This eliminates the need for the administrator to create device links in order to be able to access Sun Ray dongle ports, or have to specify device paths to dongle ports in portmap.conf.

By connecting peripherals to dongles consistently among DTUs, the administrator can simplify the application.  For example, if it is known that a printer is physically connected to the 1st serial port of the the on each Sun Ray, and a cash drawer on the 2nd port, then by assigning corresponding logical names to utcom1 and utcom2, respectively, the application can refer to those logical names and know that it is communicating with a printer or cash drawer without having to consider which Sun Ray the application's Sun Ray session is running on.

If a Session Local ALN portmap entry refers to a valid port on a supported dongle, the alias appears in the port list when  getCommPortIdentifiers()  is called, in place of default name of the dongle port.

Each
Session Local ALN is referred to by the administrator according to the port it represents on the dongle).  For example, utcom1 refers to the 1st serial port on the dongle,  utcom2 refers to the 2nd port on the dongle, and so on.   Similarly, utprt1 refers to the first parallel port.

If the ALN port number exceeds the number of ports on the first dongle found connected to the DTU, for example, referring to port #5 on a 4-port dongle, the ALN reference will 'spill over' to the next dongle, that is, if any other dongle are connected to the Sun Ray, and would refer to the first port on the subsequent dongle.  This is because the ALN port number reference is really just an index into the list of device links in the Sun Ray device directory.

Hotdesking:

Session Local ALNs  always follow the session and are not tied to a specific device.  DTU Specific ALNs are used to alternatively refer to dongles on specific DTUS as though from a bird's eye view.

When a session moves to a new DTU (that kind of session migration is known as hotdesking in Sun Ray terminology), javax.comm throws an exception for any ports opened on the previous DTU.   Once the session has migrated to the new DTU, the next time comm. ports are enumerated by the application, the logical names specificed in those ALN entries in portmap.conf will then map to corresponding port on the dongle on the new DTU, and those ports will need to be openned in order to use.

There are two types of the Session Local ALN, to accommodate different application strategies.

The alias
will appear in the CommPortIdentifier list only if the dongle is attached and the port exists at the time getCommPortIdentifer() or getCommPortIdentifiers() are called.   Unless debugging is enabled, such erroneous or unresolvable aliases are silently dropped.





        DTU-Specific ALN    -   Assign alias to a dongle port on specific DTU

Syntax: <alias>  = DTU Alias : ALN

                NoteThe syntax of this entry looks similar to the DTU Assigned alias,
             but
each serves an entirely different purpose.   This type of definition
             refers to Sun Ray dongle ports and always ends in  utcom1, utcom2, utprt1, etc..
             A DTU Assigned alias always ends in a device path, such as /dev/term/a.

Disposition: Session Independent
Privilege: root

Examples:

hallway_printer   =  hallway_dtu:utprt2
retina_scanner    =  entrance:utcom1

The purpose of the DTU Specific ALN is to access a dongle port on an arbitrary Sun Ray DTU, without the administrator needing to know, nor having directly refer to the the dongle port's filesystem device path.  Root privilege is required to view ports on other DTUs.  Without root privilege, Sun Ray devices is only accessible from sessions running on the DTUs devices are locally attached to.  DTU Specific ALNs are provided primarily to provide a means for daemons (running as root) to be able access devices on any Sun Ray, requiring minimal configuration effort.

A DTU Specific ALN is used to make a static reference to a particular serial port on a specific Sun Ray, regardless of whether javax.comm is run from inside or outside of a session.  In contrast, Session Local ALNs always refer to the local DTU.

The alias will appear in the CommPortIdentifier list only if the the target DTU is online and available, there is a compatible dongle is attached to the DTU, and the specified port is present on the dongle at the time getCommPortIdentifer() or getCommPortIdentifiers() are called.   Unless debugging is enabled, erroneous or unresolvable ALN aliases are silently dropped.


ALN spillover:

Intuitively, utcom3 is not a valid specifier for a dongle with only 2 serial ports.  On a dongle with two ports,  only utcom1 and utcom2 are valid. 

 If a dongle has two ports, a reference
to utcom3  'spills over' to the next dongle if another dongle is attached to the DTU.  That is, if there are subsequent dongles attached, thst spillover will refer to the first available port on the subsequent dongle. If there are no additional dongles, the reference to utcom3 is silently discarded as an error.  Consider a case where two 2-port dongles are attached to one Sun Ray; utcom4 would refer to the 2nd port on the 2nd dongle.  The problem with using 'spill over' is in determining which dongle is dongle 1, and which is dongle 2, as the order of enumeration is not obvious unless the USB connector and hub enumeration order is carefully analyzed by the administrator.  For that reason, and the fact that unwary user's might move the USB conectors, the multi-dongle per DTU scenario is probably best avoided.

ALNs work by indexing into the list of files in the Sun Ray device directories.  The order in which the dongles are listed is based on dongle type and to which USB ports/hubs the dongles are connected.  Therefore, the easiest way to guarantee a 1:1 mapping between ALNs and dongle ports, is to ensure that one dongle is ever attached to a given DTU and that the dongle has sufficient number of ports.  In other words, if 4 ports are needed, get a 4-port dongle;  if 7-ports are needed, use an 8-port dongle.   If multiple dongles are used, great care needs to be taken to determine the enumeration order and keep the hardware and portmap.conf file in sync with one another.  Therefore multiple dongles per DTU is not in the spirit of ALNs.