Lesson 5 Overview

The files for this lesson are located in the directories:

%RTHOME%\java\tutorial\lesson5 

$RTHOME/java/tutorial/lesson5 

This lesson describes RTclient option databases, as well as techniques for loading and manipulating options programmatically. SmartSockets uses these options extensively for configuring a Java RTclient’s behavior. While many of the options an RTclient may care to set can easily be "hard-coded," the use of option databases allows a more flexible, dynamic method of program setup and control.

The options available to Java RTclients are described in Setting RTclient Options on page 137. Remember that these options and their values are case sensitive.

Option (Property) Databases

SmartSockets options are retrieved from Java Properties databases. These databases take the form of text files containing key-value pairs, one entry per line. The "key" string may contain periods (.) to indicate property hierarchies, and all SmartSockets options reside in the "ss." hierarchy. For example, two of the standard SmartSockets option properties are defined in the property database like this:

ss.server_auto_connect: false 
ss.project: foo 

Note that option names and values are case sensitive and can be presented in any order. Option properties should appear only once in the property database; if multiple instances of an option appear with conflicting properties, the last key-value pair in the database is used, overriding any earlier settings. Option databases can contain values for the standard RTclient options, as well as for user-defined settings.

Utility Methods for Handling Options

The basic option-handling methods are contained in the Tut utility class. Individual options are also often represented by instances of the TipcOption class.

When using multiple RTserver connections created by the TipcSvc.createSrv factory method, use the TipcSrv option-handling methods to change the option setting for a TipcSrv object. If an option is not set for a TipcSrv object, the option’s default value is used or the value set by the Tut option-handling methods is used.

This table summarizes the relevant Tut and TipcSrv methods:

See the online documentation for the Tut, TipcOption, TipcConnClient, and TipcSrv classes for full usage details.

Setting Simple RTclient Options

RTclient options can be set to specific values by defining them in an option database and loading them, or by explicitly setting them. To set common options (that can be represented by a string) use the Tut.setOption convenience method or get the option and manipulate it with TipcOption’s methods. An example of setting an option, in this case, ss.project, with the convenience method is:

Tut.setOption("ss.project", "myProject"); 

To accomplish this more formally with the TipcOption class, use this code:

TipcOption proj = Tut.getOption("ss.project"); 
proj.setValue("myProject"); 

Note that TipcOption objects are not to be directly instantiated by your code; they are created as necessary by Tut’s createOption, getOption, and removeOption and returned to your application at that time.

See the online documentation for detailed information about the specific standard options recognized by the SmartSockets Java Class Library, as well as for valid values for all options.

Working with Enumerated Options

Often it is useful to have enumerated options, where the allowed values for an option are specified as a set of strings. The TipcOption class provides for enumerated options with automatic legal-value checking, as well as allowing the enumerated string values to be mapped onto integers. Individual enumerations may support integer mapping or simply strings, but not both. Mapped enumerations must have corresponding integer values provided for each of its string values; unmapped enumerations do not allow any corresponding integers to be specified.

This example creates an unmapped (simple) enumerated option, sets the legal values, and then sets and gets the option. Note that the second time getValueEnum() is called, an exception is thrown, because the value "orange" is not a legal enumeration value.

TipcOption enum = Tut.createOption("ss.col", "red"); 
enum.addEnumLegalValue("green"); 
enum.addEnumLegalValue("blue"); 
enum.setValue("green"); 
try { 
   System.out.println("ss.col = " + enum.getValueEnum()); 
   enum.setValue("orange"); 
   System.out.println("ss.col = " + enum.getValueEnum()) 
}catch (TipcException te) { 
   Tut.warning(te); 
} 

If you want to use a mapped enumeration, the code would look like:

TipcOption enum = Tut.createOption("ss.col", "red"); 
enum.addEnumMapLegalValue("red", 0); 
enum.addEnumMapLegalValue("green", 1); 
enum.addEnumMapLegalValue("blue", 2); 
enum.setValue("green"); 
try { 
   System.out.println("ss.col = " + enum.getValueEnumMap()); 
   enum.setValue("orange"); 
   System.out.println("ss.col = " + enum.getValueEnumMap()); 
}catch (TipcException te) { 
   Tut.warning(te); 
} 

Loading RTclient Options from a File or URL

Option settings may be loaded from a local file or a URL, depending on security restrictions. Applets are generally not allowed access to the local file system, and typically retrieve options from a URL on the same web server from which the applet was downloaded.

To load options from a local file, use Tut.loadOptionsFile. Use Tut.loadOptionsURL to load options from a remote file using a URL. If your program has a different source for options that implements the InputStream interface, you can also use the Tut.loadOptionsStream method. All of these methods load all of the options immediately, overriding any existing settings for all of the options that appear in the file.

Options are also loaded from the System property table (the table returned by the standard Java library call System.getProperties). Option settings loaded from a file take precedence over settings that appear in the System table. All of the standard options have a default setting that is used if a setting does not appear in either the System table or a loaded file.

For example, examine this options file, local.opt:

ss.booleanValue1: true 
ss.booleanValue2: false 
 
ss.doubleValue1: 1.23456 
ss.doubleValue2: 65432.1 
ss.doubleValue3: -1.0 
ss.doubleValue4: 100.0 
 
ss.intValue1: 1 
ss.intValue2: -16384 
ss.intValue3: 2 
ss.intValue4: -2 
ss.intValue5: 32767 
 
ss.bulb: on 
ss.stringValue1: The quick red fox jumped over the lazy dog. 
ss.stringValue2: Value1, value_2, VALUE-3, Value4, etc. 
ss.charA: A 
ss.charB: B 
ss.charC: C 
ss.charZ: Z 
 
ss.project: foo_project 
ss.server_names: _node, rocky, bullwinkle 
ss.user_name: javauser 

As you can see, the format is simply that of a Java property database, key-value pairs in ASCII, one pair to a line.

The following program, getOptions.java (see the "examples" directory on the distribution media) will load and interpret some of the values from such a file. Specifying a URL on the command line to getOptions allows loading of a file like the above from a remote location such as a web server.

The files for this lesson are located in the directories:

%RTHOME%\java\tutorial\lesson5 

$RTHOME/java/tutorial/lesson5 
// getOptions.java 
// Example of retrieving SmartSockets and user-defined options 
// settings from a file, URL, or InputStream 
 
1 import java.io.*; 
2 import java.util.*; 
3 import com.smartsockets.*; 
 
4 public class getOptions { 
 
5   static public void main(String[] argv) { 
6      final String optionFile = "local.opt"; 
 
    // must create enumerated map option BEFORE loading! 
7   TipcOption bulb = null; 
     try { 
8      bulb = Tut.createOption("ss.bulb", "off"); 
     } 
9    catch (TipcException te) { 
       Tut.fatal(te); 
     } // catch 
10   bulb.addEnumMapLegalValue("on", 1); 
11   bulb.addEnumMapLegalValue("off", 0); 
12   bulb.addEnumMapLegalValue("broken", -1); 
 
13   System.out.print("Getting options from "); 
 
     // if argument was supplied, assume it's a URL to properties 
14   if (0 < argv.length) { 
15     System.out.println("URL " + argv[0]); 
16     Tut.loadOptionsURL(argv[0]); 
     }  
     else { 
       // no argument, so use local options file 
17     System.out.println("local file " + optionFile); 
18     Tut.loadOptionsFile(optionFile); 
    } // else 
 
    try { 
19    String project = Tut.getOptionStr("ss.project"); 
20    System.out.println("ss.project = " + project); 
 
21    String server_names = Tut.getOptionStr("ss.server_names"); 
22    System.out.println("ss.server_names = " + server_names); 
 
23    String user_name = Tut.getOptionStr("ss.user_name"); 
24    System.out.println("ss.user_name = " + user_name); 
 
      // get some user-defined options 
      // these would be meaningful to this particular program 
25    boolean bv = Tut.getOptionBool("ss.booleanValue1"); 
26    System.out.println("ss.booleanValue1 = " + bv); 
 
27    double dv = Tut.getOptionDouble("ss.doubleValue1"); 
28    System.out.println("ss.doubleValue1 = " + dv); 
 
29    int iv = Tut.getOptionInt("ss.intValue1"); 
30    System.out.println("ss.intValue1 = " + iv); 
 
31    String sv = Tut.getOptionStr("ss.stringValue1"); 
32    System.out.println("ss.stringValue1 = " + sv); 
 
33     TipcOption so = Tut.getOption("ss.stringValue2"); 
34     Vector ov = so.getValueList(); 
35     if (null == ov) { 
36       System.out.println("Can't parse stringValue2!"); 
       } 
       else { 
         // use an Enumeration object to move through parsed list 
37       Enumeration en = ov.elements(); 
38       for (int i=0; en.hasMoreElements(); i++) { 
39         String el = (String)en.nextElement(); 
40         System.out.println("ss.stringValue2[" + i + "] = " + el); 
        } // for 
      }  // else 
 
41    TipcOption sw = Tut.getOption("ss.bulb"); 
42    System.out.println("ss.bulb(string) = " + sw.getValueEnum()); 
43    int ev = sw.getValueEnumMap(); 
44    System.out.println("ss.bulb(mapped) = " + ev); 
     }  
45   catch (TipcException te) { 
46     Tut.warning(te); 
     } // catch 
    } // main 
   } // getOptions 

Let’s examine the key lines of this program:

Step 1

Compile the getOptions.java program

Compile the options program, getOptions.java, program using the command:

$ javac getOptions.java 

Step 2

Start the options program

Make sure the local.opt file is present in the working directory, and start the options program using the command:

$ java getOptions 

When you start the options program, this output is displayed:

Getting options from local file local.opt 
 
ss.project = foo_project 
ss.server_names = _node, rocky, bullwinkle 
ss.user_name = javauser 
ss.booleanValue1 = true 
ss.doubleValue1 = 1.23456 
ss.intValue1 = 1 
ss.stringValue1 = The quick red fox jumped over the lazy dog. 
ss.stringValue2[0] = Value1 
ss.stringValue2[1] = value_2 
ss.stringValue2[2] = VALUE-3 
ss.stringValue2[3] = Value4 
ss.stringValue2[4] = etc. 
ss.bulb(string) = on 
ss.bulb(mapped) = 1 

Included with this example on the SmartSockets distribution media is an applet version, named getOptionsApplet.java. The applet version loads its options from the same web server (or applet viewer) it was downloaded from, but from the file remote.opt.

Making Custom Options Read-Only

For the custom options that you add, it is also possible to set the optional flag read-only. This will prevent the option from being reset during another loadOptions method or as part of your program. For example:

try { 
 TipcOption ro = Tut.createOption("read-only", "false"); 
 ro.setValue("true"); 
 ro.setReadOnly(true); 
 ro.setValue("changed"); 
} 
catch (TipcException te) { 
 Tut.warning(te); 
} 

The above code creates a new option, sets its value while it is still read-write, and then changes it to be a read-only value. When the code attempts to set the value a second time, an exception is thrown.

Java-Specific Options

There are several options only for Java RTclients. In Java, messages are read into the message queue by a reader thread. If the Java RTclient receives many large messages rapidly, it is possible for the Java Virtual Machine (JVM) to run out of memory. An alternative to increasing the Java heap size, the ss.max_read_queue_length or ss.max_read_queue_size can be modified to limit the number of messages read into the message queue at one time. The ss.max_read_queue_length limits the number of individual messages in the message queue and the ss.max_read_queue_size limits the total number of bytes in the message queue. A value of 0 indicates unlimited length or size. The ss.min_read_queue_percentage indicates to what point the message queue threshold must fall before messages are read into the message queue again. These values are changed only under unusual circumstances.