VM Startup Settings Engineering Specification

RFE: 4523283 Author: Steven Katz
Date: 07-Jan-2002

1 Project Description

1.1 Overview

There exists a set of values, that the plugin passes to the VM at startup. Lets call this set of values S.

For each platform (Windows or UNIX) S is composed of two subsets. The first is the set of values that are unique to that platform. The second is the set of values common to both platforms.

Lets call the unique sets Sw and Su, for Windows and UNIX respectivly.

Lets call the common set Sc.

On Windows S is the UNION of Sw and Sc. On UNIX S is the UNION of Su and Sc.

The problem is that at this time the proper contents of set Sc are undefined. Additionally, the proper contents of both Sw and Su are not well defined.

It is a goal of this project to define the current contents of Su, Sw and Sc.

It is a goal of this project to insure that, as new startup options are needed, it will be simple to add them such that the proper contents of Sw, Su and Sc are maintanted.

It is a goal of this project that any plugin developer wishing to aquire the set of startup options for a particular platform be able to do so with a single, consistent and cross-platform interface.

1.2 Project Dependencies

This project depends, to some extent, on the work to consolidate the two seperate code bases into one. Also, on the work to switch from nmake to gnumake on Windows.

1.3 OS and Browser Compatibility and Interoperability

In order to properly support the current Windows and UNIX implementation of the plugin, any solution must support both a C and C++ interface. Given that C++ is capable of supporting a C solution, it might be sufficent to produce only a C interface.

It is possible that, in the future, the method of staring the VM on UNIX will change from exec'ing a custom program to exec'ing the "java" command. Any solution will need to support this possibility.

1.4 Performance and Scalability

Unknown at this time.

1.5 Security

Since part of the determination of the start up values includes the inclusion of users specified values in the control panel, security can not be guaranteed.

1.6 Internationalization (I18N) / Localization (L10N)

N/A

1.7 Packaging

N/A

1.8 Usability

N/A

1.9 Quality

1.9.1 Unit or Functional Tests to be Delivered
Testing of this project will require the ability to determine if the set of values expected to be given to the VM are actually being given to the VM. This can be accomplished to a limited degree by providing a value tracing mechanism in the solution. That is, a way to display to the tester the set of values the plugin has decided to pass to the VM.
1.9.2 Additional Testing Notes

2 Technical Description

2.1 Architecture

The members of set S are strings of characters of a particular format.   The format is that of a "switch", a hyphen followed by at least one  alphanumeric character.

Some "switches" convey information mearly by their being present.  For example: -verbose

Some "switches" constitute a name/value pair.  For example: -DtrustProxy=true where "trustProxy" is the name and "true" is the value.  Another example of this type: -Xverify:remote where "verify" is the name and "remote" is the value.

A switch shall be considered a member of the set Sc if:

1) It is of the first type and is specified on both Windows and UNIX

2) It is of the second type and differs only in the value, between its Windows and UNIX specification.

Based on above, the members of the set are defined as:

Sc:
 
-DtrustProxy=true On UNIX/Windows: The switch is set, as is,  unconditionally.
-Xverify:remote On UNIX/Windows: The switch is set, as is,  unconditionally.
-Djava.protocol.handler.pkgs=sun.plugin.net.protocol On UNIX/Windows:  The properties file/registry is checked for user supplied definition of this switch and the supplied value is appened with "|sun.plugin.net.protocol".  If the user does not specifiy the switch then it is passed as shown.
-Xbootclasspath/a:VALUE On UNIX: The value is set to:
%1/lib/javaplugin.jar:%1/lib/javaplugin_l10n.jar:%1/libjsse.jar:%1/lib/jce.jar:%1/lib/sunrsasign.jar:
where %1 is set to the path where Java is installed.  The filename of the first jar file is conditionalized to account for the debug and non-debug builds (ie. an _g is added to the filename: javaplugin_g.jar).
On Windows: The value is set to:
All the files that end in ".jar" that can be found in the "lib" subdirectory below the
directory where Java is installed (as determined by a registery key).
-Djavaplugin.nodotversion=VALUE On UNIX/Windows: The value is set to the no-dot representation of the version number of the JRE.  The value is aquired from a header file as a CPP define.
-Djavaplugin.version=VALUE On UNIX/Windows: The value is set to the version number of the JRE.  The value is aquired from a header file as a CPP define.
-Djavaplugin.user.profile=VALUE On UNIX/Windows: The value is set only if the environment variable, USER_JPI_PROFILE is set.  The value is then set to same value as the environment variable.   
-Djava.class.path=VALUE
On UNIX: The name and value are set only if the user specifies either the -cp
or the -classpath switch via the Control Panel.  If either of these switches are present then their
value becomes the value for this switch.  If no value is given, this switches value is set to ".".
On Windows: The same as on UNIX only if not value is given for this switches value is not defaulted to "."

Sw:
 
-XmxVALUEm The algorithm currently implement in the code makes no sense and does match the comments supplied.  At the end the value will either be 64 or 96.
-Djavaplugin.maxHeapSize=VALUEm The value is set using the algorithm for the above switch.
-Dapplication.home=VALUE The value is set to the installation path of Java that is stored in the registry.
-Xdebug The switch is set if a value in the registry indicates that the plugin should be run in debug mode.
-Xnoagent The switch is set if a value in the registry indicates that the plugin should be run in debug mode.
-Xrunjdwp:transport=dt_shem,address=VALUE1VALUE2,server=y,suspend=n The switch is set if a value in the registry indicates that the plugin should be run in debug mode.

Su:
 
-Dmozilla.workaround=true The value is set only if the environment variable MOZILLA_WORKAROUND is set.  Currently, this is only done in the navig5 codebase.
-Djavaplugin.lib=VALUE
The value is set to: %1/lib/%2/libjavaplugin_jni.so
where %1 is set to the path where Java is installed and %2 is set to the architecture specific subdirectory.  The value is also conditionalized to account for the debug and non-debug builds (ie. an _g is added to the filename: libjavaplugin_jni_g.so).

The ControlPanel provides the user of the Plugin the ability to specify additional "switches".  On Windows, this information gets stored in the Registry.  On UNIX it is stored in the properties file in the users home directory.  These additional "switches" can alter the contents of set S for each platform.

In general, any "switch" the user specifies via the ControlPanel is added to the Contents of set S verbatium, with the following exceptions:

On Windows:

These "switches" are not added to the set:
-green
-native
-client
-server
-classic
-hotspot
-Xoldjava

These "switches" are replaced by a switch of the same name prepended with a -X (assuming they have a value, otherwise they are removed):
-ss
-oss
-ms
-mx 

These "switches" are  passed on only if they have a value:
-Xss
-Xoss

These switches are passed on, but their presents indicates the need for a console window.
-verbose
-Xprof

On UNIX:

These "switches" are not added to the set:
-help
-h
-?
-checksource
-cs
-noasyncgc
-classic
-client
-server
-native
-hotspot
-green
-Xoldjava

These "switches" are converted into differnt "switches":
-verbosegc -> verbose:gc
-trace -> -Xt
-noclassgc -> -Xnoclassgc
-verify -> -Xverify:all
-verifyremote -> -Xverify:remote
-noverify -> -Xverify:none
-ss -> -Xss
-oss -> -Xoss
-ms -> -Xms
-mx -> -Xmx

All this information and logic will be encapsulated inside a single class, call "VMOptions".  The source code for this class will be located in the workspace at:

ext/plugin/src/share/VMOptions
ext/plugin/src/win32/VMOptions
ext/plugin/src/solaris/VMOptions

The build system will be responsible for taking the source code located in these areas and producing a static library (platform specific) that exports the interfaces (platform independent) needed to aquire the set of startup options.

Under ".../share/VMOptions" will be the header file that declares the class as well as the header file that declares the functions exported from the static library.  Also, this directory will contain one or more cpp files that contain the implementation of members of the class that are not platform specific.  Such as the function which determins the contents of set Sc.

Under ".../win32/VMOptions" and "../solaris/VMOptions" will be the cpp files that contain the implementation of member functions that are platform specific, such as the function which determins the contents of the sets Sw and Su.

2.2 Exported Interfaces/API

int getVMOptions(JavaVMOptions ** p);
This function will return the number of options found.  Also p will be set to point at the set of options.

int getVMOptionsExec(char ** p);
This function will return the number of elements in the array pointed to by the value returned in p.  This array will be suitable for use in a call to execv() for starting the VM though the "command line" (ie. the "java" command) interface.

2.3 Imported Interfaces/API

2.4 User Interface

The user of the end result of this project will be other plugin developers.  As such, the "user interface" they will see will consist of a set of functions conatined in a single static libary.  They will have to link their code against this library and proceed according to the above specification.

3 Marketing

3.1 Justification

3.2 Customer Request

3.3 Competitive Analysis

4 Management and Planning

4.1 Scope/Priority

4.2 Target Release

4.3 Resources

4.3.1 Development
4.3.2 Quality Assurance/Testing
4.3.3 Documentation
4.3.4 Technical Support
4.3.4 Special Hardware/Software

4.4 Schedule

Start Date End Date Activity Owner Status
       
 
         
Complete Started Not Started Difficulties Trouble

 

Appendices (as needed, suggestions below)

A. Background Information

"The Java Native Interface: Programmer's Guide and Specification", by Liang, Addison Wesley 1999

B. Interface Specifications

C. Notes and Additional Details

D. Miscellaneous

E. Tracking

E.1 Final Webrev
E.2 Bugtraq
Bugid P S Subcategory Type Engineer Synopsis
  4523283            

 
 

Revision History

Date Version Author Description
 07-Jan-2002 0.1 smk Initial Version
16-Jan-2002 0.2 smk Modified to incorperate mike c. comments; architecture section
31-Jan-2002
0.3
smk
Struck out parts based on stanley h. comments; completed discription of value determination