Copyright 2003 Sun Microsystems, Inc. All rights reserved.SUN PROPRIETARY\/CONFIDENTIAL. Use is subject to license terms.SerialDemo is a sample program designed to demonstrate some of the features ofthe Java(tm) Communication API (comm api). This document describes how tobuild and run SerialDemo. Building SerialDemoAll the .java files for SerialDemo reside in a single directory and none ofthem have package statements. This makes SerialDemo very easy to build. Followthe directions for installing the comm api on your machine. Make sure that youhave included comm.jar in your classpath. Compiling SerialDemo only requiresa single command. In the same directory that the .java files reside type:javac *.javaThis will produce all the .class files needed to run SerialDemo.Starting SerialDemoRun SerialDemo from the command line, in the directory containing the .classfiles, with the following command:java SerialDemoSerialDemo may also be started with a properties file as an argumentjava SerialDemo serialdemo.propertiesThis properties file is created when a configuration is saved by the userwhile running SerialDemo.SerialDemo DescriptionSerialDemo is a simple two way "talk" type program. I consists of two TextAreas,the top one takes typed input and writes that input to a serial port. Thebottom TextArea displays data received from a serial port. Under the TextAreasis a configuration panel that allows the user to choose a serial port and thesettings for the serial port. At the bottom of SerialDemo are three buttons:"Open Port", "Close Port", and "Send Break". There is one menu consisting ofthree items: "Load", "Save", and "Exit".Hardware SetupSome of the features of SerialDemo will work without any hardware setup, butto use the two way communications feature a null modem cable is required. Thecable can either be looped back between the serial ports on a single machine orused to connect the serial ports on two different machines.Using SerialDemoOnce the program is started, choose the port you want to connect to and thesettings you want for the port on the Configuration Panel. Then press the "Open Port" button. After the port is opened, keystrokes typed into the topTextArea are sent to the port. Data received from the port is displayed inthe bottom TextArea.Port choices can not be changed while a port is open. If a change is attempteda dialog box will appear notifying the user that the port can not be changedand the Configuration Panel port choice will revert to the original setting.Port settings may be changed while the port is open. If a setting is not supported by the platform a dialog box will appear notifying the user that setting is not supported and the setting in the Configuration Panel willrevert to the original setting. Settings may also be changed while the port is closed. If an unsupported setting is chosen no notification will occur until the port is opened. Atthat time the port open will fail, the user will be notified and asked to try different settings.Configurations may be saved to and loaded from files. Configurations may onlybe loaded while a port is closed. To save a configuration, choose the "Save"item from the menu. A file dialog will appear allowing the file to be saved.A default name for the file is "serialdemo.properties". This name can be changed in the file dialog. To load configurations, choose the "Load" item from the menu. A file dialog will appear. Choose the file that contains the configuration that you wantto load. SerialDemo can load configurations that may not work on the platformon which the program is running. If a configuration contains unsupportedsettings or an incorrect port name the port will not open.Configurations may also be loaded from a file at start up. To use a configuration file at start up, pass the name of the file to the program asan argument. Example:java SerialDemo serialdemo.propertiesA break signal can be sent to serial port by pressing the "Send Break" button.If a break signal is received the message "--- BREAK RECEIVED ---" is printedin the bottom TextArea. Some platforms do not reliably report break signalsto the comm api. If the break signal is not correctly reported then the comm api and SerialDemo will interpret the signal as a byte of value 0. Inthis case the break received message will not be displayed.Port Contention ResolutionSerilDemo implements the comm api port contention resolution feature. This feature allows an application to request a port that is use and have the application that is using the port make a choice on whether to give up the port or not. On some platforms, such as Windows, this resolution can occurbetween separate Virtual Machines. On other platforms, such as Solaris, resolution can only occur within the same Virtual Machine.If you are running on a platform that supports contention resolution between different Virtual Machines SerialDemo can demonstrate port conflict resolution.To see port conflict resolution do the following steps.1) Start two instances of SerialDemo and have both instances showing on the screen.2) Open a port in one of the instances.3) Attempt to open the same port in the other instance. A dialog box shouldappear over the first instance telling the user that an other applicationhas requested the port and asking if they will give the port up. If the userpresses the "Yes" button, the first instance will close the port and the second instance will open the port. The port open calls in SerialDemo have a 30 second timeout. If the instancecontrolling the port does not give it up within 30 seconds then the openwill fail and the instance requesting the port will be notified that theport is in use.Features To Look For In the Code* Opening, closing, and setting serial ports -- SerialConnection.java* Event driven I/O - SerialConnection.java* Event driven ownership resolution -- SerialConnection.java* Comm port exception handling -- SerialConnection.java* Saving and loading configuration files -- SerialDemo.java