C H A P T E R 5 - Managing Properties and Constants

C H A P T E R 5

Managing Properties and Constants

You manage properties and constants in Java Wireless Client software with a tool called the configurator. This chapter covers the tool's design, how to use it to manage properties and constant values, and how to use its output.

Note - You do not port the configurator.

Introduction

The configurator is a development tool that runs on the desktop, not on the device. The configurator maintains properties and constants. It assures that they are defined the same in both the Java layer and the native platform layer.

Any Java Wireless Client software service or subsystem that calls the System.getProperty or Configuration.getProperty methods depends on the configurator. Any subsystem that uses at least one constant value in both the Java platform and native layers also depends on the configurator. The configurator is is also used to manage localized strings. Each locale has an XML file that contains localized strings. These XML files are processed by the configurator at build time, generating C and Java programming language files and providing localized strings at runtime.

The build system automatically runs the configurator.

Design

Two of Java Wireless Client software's goals are seemingly in conflict: It must be highly configurable and must have a minimal runtime footprint. The configurator tool reconciles these goals by providing the ability to set the property and constant values for a particular platform, and then generate only those values.

The configurator provides the following advantages:

Flexibility - The configurator is able to process input files on a subsystem-by-subsystem (or service-by-service) basis.

Maintainability - The configurator uses a number of files that fully describe Java Wireless Client software's properties, constants, and localized string resources. The input files of the configurator are divided by content type, platform dependence, and functional principles. The input files are maintained in known locations, so the values defined there are not scattered throughout the code base or build system.

Improved Performance and Minimal Size - The configurator enables the CLDC HotSpot Implementation ROMizer to compact and quicken the Java platform byte codes for Java Wireless Client software. The ROMizer runs static initializers at runtime, then compacts the final ROM image. However, the ROMizer cannot compact or quicken any class with a static initializer that calls native methods, nor can it compact or quicken any of that class's subclasses. The configurator makes these calls unnecessary by ensuring that the Java platform and native values for properties and constants are the same.

The configurator is critical to the optimization of Java Wireless Client software. It works with the CLDC HotSpot Implementation ROMizer, which compacts and quickens the Java platform byte codes for Java Wireless Client software. The ROMizer enables classes for the Java platform classes (Java classes) to be linked directly in the virtual machine. For information on the ROMizer utility, see the CLDC HotSpot Implementation Porting Guide.

As shown in FIGURE 5-1, the configurator reads data from input files, processes that data, then writes files to be used at later stages of compilation or release. It generates Java classes and associated native methods to support retrieving property and constant values.

Note - Because the configurator generates source files, if you add a property or constant or update an existing value, you must rebuild the system before accessing the new data.

FIGURE 5-1 Configurator Work Flow for Constants and Properties

Diagram shows the how work flows through the configurator

Input Files

The configurator finds input files in one of two ways.

First, you can add input file names to the INT_XML_FILES build variable.

The second method is to list the input file names in src/configuration/configuration_xml/platform/files.lst, which is read at build time.

You can examine an existing copy of files.lst to understand how constants are defined. For example, src/configuration/configuration_xml/javacall/files.lst references constants.xml, properties.xml, and rawimage.xml.

As shown in FIGURE 5-1, input can be provided for properties, constants, AUI technology skin properties (if AUI technology is used), and localized strings. The various types of input can be combined into a single file or multiple files, and can be mixed and matched as you wish. Input files can also be based on platform type or any other criteria you wish to create. For example, REPEAT_TIMEOUT and REPEAT_PERIOD are applicable only to the linux_fb version of Java Wireless Client software because repeated key events on other platforms are supported by the underlying native system.

These input files must be organized in subdirectories of the directory configuration_xml. For example:

src/

configuration/

configuration_xml/

armsd/

linux_fb/

linux_qte/

stubs/

win32

share

chameleon/

l10n/

The share/ directory contains configurator input common to all of the platforms. The share/ directory and any of the other platform directories can contain alternative versions of the constants in constants_open and constants_fixed. They are selected based on the build resource policy defined by the USE_FIXED build option.

In addition, the TARGET_DEVICE build option can be used to select alternate versions of input files within a specific platform. For example, the linux_qte directory contains constants, constants_omap730, and constants_x86. Setting the TARGET_DEVICE build option to omap730 or x86 during the build will cause the corresponding file to be used.

Note that input items must be unique in the merged XML file. If you provide different item values based on build flags, you must define these items in alternative input XML files.

The configurator tool expects its input files to be in XML format. The following characteristics of Java Wireless Client software and its data make XML a good solution:

The structure of the data is simple, so the DTD can be in the file with the data itself, or in a separate file that the subsystems can share.

The structures are flat, so a simple SAX parser with rudimentary error checking can be used instead of a full XML schema or DOM parser.

XML is flexible enough that any style and format differences can be unified with XSL transformations, yet each subsystem can extend the DTD according to its needs.

Because Java Wireless Client software requires JDK software version 1.4.1_01 or later, which includes a SAX parser, you do not need to install extra software on build machines.

For constants, the configurator uses the input to generate the Java programming language and native source code to access the constants. It generates one class for each unique package-class pair in the input XML file. It also generates corresponding native header files that define the constants in #define statements. These are the files named Constants.java and midp_constants_data.h in FIGURE 5-1.

For properties, the configurator uses the input to generate one of the following types of files:

Source code - The file midp_properties_static_data.h is shown in FIGURE 5-1.

Property files - These are the files named system.config (for properties with a scope of system) and internal.config (for properties with a scope of internal) in FIGURE 5-1.

With the property files, the configurator also provides a default implementation of the Configuration class and correspondingly, the native files that read the properties from the .config files.

Using the configurator to generate the property files is a fall-back mechanism for maximum flexibility during porting. Due to the speed and size impact of processing property files at runtime, however, do not make this part of a deployed solution.

Properties

The configurator requires the following information for properties:

Property name

Value

A setting that specifies whether the property is internal (only available to the Java Wireless Client software implementation) or system (also available to MIDlets)

A system callout to retrieve a default value

A comment (optional)

The configurator uses a DTD shown to describe the input data for properties because the required information is diverse.

Modifying Properties

To change the value of an existing property, update the property's XML element (the element's value attribute) in your properties input file.

Adding Properties

The following steps describe how to add a new property.

1. Determine the attributes of the property.

The attributes are the property's name, value, and scope. Optionally, you might also have as attributes a callout function name and a comment. If you define a callout function, you must also write a corresponding native function that has a name identical to the callout function name and a return type of char*.

For more information on the attributes, see the DTD.

2. Add a new element your properties input file.

For example:

CODE EXAMPLE 5-1 Adding a New Element to a Property File
<property Key="com.company.getDynamicValue" Value="" Scope="internal" Callout="getDynamicValue"/>

Constants

The configurator requires the following information for constants:

The name of the package and class that contain the constant

The scope of the class that contains the constant

The comment associated with the class (optional)

The name of the constant

The data type

The value

The scope of the constant itself, as opposed to the class that holds it

The comment associated with the constant itself, as opposed to the comment associated with the class that holds it (optional)

In addition, you can specify JavaOnly or NativeOnly attributes to restrict the generation of a constant.

The configurator tool uses a DTD to describe the input data for global variables.

Modifying Constants

Most constants define platform-specific values, such as the screen size of the device, the number of supported colors, and so on. Internal constants are also used. They are clearly marked with internal in the comment attribute. You must update the platform-specific values to match your device, but can safely ignore the values of internal constants.

Follow this step to change the value of an existing constant:

Update the constant's XML element (the element's Value attribute) in your constants input file.

Adding Constants

Use the configurator to maintain consistency between the Java platform and native layers. If you need a new constant in only the native layer or Java layer (but not both), do not to add it to the configurator. Define the constant in your code. If you use the configurator for every constant, even those used in only one layer, you needlessly increase Java Wireless Client software's footprint.

The following steps describe how to add a new constant.

1. Determine the attributes of the class from which the constant is accessed in the Java platform.

The attributes are the class's package, name, and scope. Optionally, the class can also have a comment associated with it. All Java Wireless Client software constants are accessed in the Java layer from the com.sun.midp.configurator package's Constants class.

For more information on the attribute values, see the DTD.

2. Determine the attributes of the constant.

The attributes are the constant's name, value, and scope. Optionally, the constant can also have a type (the default is int) and a comment.

For more information on the attributes, see the DTD.

3. Add a constant_class element to your constants input file if an element with the same package and class is not already in the file.

For example:

CODE EXAMPLE 5-2 `constant_class` Element in Constants Input File
<constant_class Package="com.company.midp.Configurator" Name="Constants" Scope="public"> </constant_class>

4. Add a new constant element to the appropriate constant_class element of your constants input file.

For example:

CODE EXAMPLE 5-3 `constant` Element in `constant_class` Element of Input File
<constant_class Package="com.company.midp.Configurator" Name="Constants" Scope="public"> `<constant Name="MyPlatformNewConstant"` `Value="123"` `Vscope="public"` `Comment="This is a comment to keep track of my` `MyPlatformNewConstant constant"/>` </constant_class>

CODE EXAMPLE 5-3 constant Element in constant_class Element of Input File

<constant_class Package="com.company.midp.Configurator"

                Name="Constants"

                Scope="public">

  <constant Name="MyPlatformNewConstant"

            Value="123"

            Vscope="public"

            Comment="This is a comment to keep track of my

                  MyPlatformNewConstant constant"/>

</constant_class>

Changing the Output Format of Constants

If you must change the way constants are specified, modify the eXtensible Stylesheet Language (XSL) files contantsJava.xsl and constantsNative.xsl located in the src/tool/configurator/xsl directory. The configurator uses the XSL files to create the code for constants. Do not edit the XSL files if you want to use the default settings to generate the source code.