...For 1.0.2 Gemstone is a Rich Client application built on the XULRunner platfrom from Mozilla. Developing new functionality for Gemstone requires many of the same skills used for typical Web development


The relationship between XULRunner and Gemstone is similar to that of the Java JRE and a Java application. XULRunner provides a robust, cross-platform core as well as support for a wide array of Web standards including CSS, DOM, HTML, SVG, XPath, XSLT and many others. With XULRunner however, these same Web standards can be used to build a full-fledged desktop application like Gemstone.


The Gemstone client can be installed on Windows, Unix and Mac platforms. Macs can be Intel-based or PowerPC with at least OS X 10.2.8. A ZIP utility is required as well as a text editor or JavaScript capable IDE.

You should have some faimiliarity with JavaScript and HTML at the very least. Although, HTML itself will not be used, it is very similar to XUL which is the predominate markup language used in Gemstone. Familiarity with typical Gemstone usage is also essential. Documentation can be found here

Related material

Additional reference materials and tutorials for technologies Gemstone uses are available here:

Getting Started

This section will explain the general layout of the Gemstone file hierarchy.

Installing Gemstone

See this

Application Layout

The top level directory will be called Gemstone under both Linux and Windows; under this
will be the following:

The same can be found under for a Mac. gemstone.jar is a zip file that should be unziped before proceeding.   application.ini, chrome.manifest, and prefs.js are configuration files for XULRunner to properly invoke Gemstone.   More information can be found here. Most application files are located in the chrome/contents directory.

Changing For Development

To convert a release version of Gemstone requires a few slight changes. First, unzip gemstone.jar and remove it. Next, replace the contents of chrome.manifest with the following:

content gemstone content/
overlay chrome://pippki/content/domainMismatch.xul chrome://gemstone/content/overlays/bypassOverlay.xul
locale gemstone en-US locale/en-US/
locale branding locale locale/

This tells XULRunner to look for interface files in a normal file hierarchy rather than inside the jar file. Finally, in prefs.js change the value of pref( "app.update.enabled" , true ); to false. This will stop Gemstone from automatically installing updates and overwriting changes that you have made.

The Registry

The registry is contained in a single file, local-registry.rdf. This is the only registry file that can be prefixed with chrome. Additional local registries can be located anywhere but should use a full file path (file://) when typed into the URL bar. Remotely stored registries can use either standard HTTP or SSL + HTTP and require no special configuration to host; the file can be dropped into any open and accessible location.


A registry has two main sections: one for describing service categories, and one for describing services. Each service must belong to a single category. A category entry looks like:

 <rdf:Seq rdf:about="" s:category="<Materials Science>">
   <rdf:li rdf:resource=""/>

Only the "Category Name" will be seen by the user, "matsci" is a developer created identifier for the category. Each service in the category is identified by it's category id and a unique number. In the example above, there is one service which has the id "matsci/0" in the category named "Materials Science". This service id is used when creating the service entry seen below:

<s:service rdf:about=""

There are four possible attributes for every service entry, three of which are required.

Creating An Interface

Be sure to to look at the tutorials in the reference pages before continuing with this section. Each service should have a directory with the same name in the services/ directory. Gemstone will assume your service's main XUL file will be of the form [service name]Main.xul (see the "url" attribute of the registry example in the last section).

Required Elements

The template XUL panel shows what is required for a proper service panel. There are three main parts to the service template (noted in the file):

  1. The "Header": specifies a few default CSS stylesheets for the panel. These can be added to or changed. window is the required top-level XUL element of any service. The onload attribute dictates a single JavaScript function that should be called once the entire panel has loaded.
  2. This section is for including any number of external JavaScript files that provide functionality for the service. The first six are standard files that should not ordinarily be removed. The final <script> include is a place holder for a JavaScript file you will write. The <description> elements can be used to display useful information about the service to the user.
  3. This section will contain the bulk of your user interface

Writing JavaScript

Service panels must be associated with a JavaScript file to respond to user action, interact with the Gemstone APIs, and run Web services. The template here: can be used as the basis for a new service .

Global Variables

Every service panel has access to the following global objects :

Required Functions

At a minimum, Gemstone expects the following functions to be present --even if they are empty "stubs"-- in any service's main JavaScript file:

Gemstone APIs

The Gemstone APIs fall into two categories: functions used to interface with the framework, and functions performing commmon tasks useful to the developer. Javadoc style API documentation can be found here


File.js Contains a collection of functions for dealing with Files and Directories. To open and read a file do the following:

var aFile = new File( "/Users/someone/Desktop/readme.txt" ); // on a mac
var aFile2 = new File( "C:\readme.txt" ); // on Windows "r" ); // open for reading
var text = ); // read the entire file
aFile.close(); "w"); // open the file for writing
aFile.write( "I'm a readme file" );

This example used platform specific path strings to create the object but in most cases file paths will come from user input or from the Filesystem display. For more complex examples look at JavaScript files in the services directory. Other useful file handling routines are located in common.js.


Common.js contains globally accessible variables and functions that accomplish a variety of tasks. For a complete reference of global variables please see the source. Some features include:


Job.js is an abstraction that holds all the necessary information to run a Web service. The Job object is currently designed for use with Opal-style services (see this for information on Opal), however, support for arbitrary services will be included in future. The following is typical of how to setup a Job:

var env = createInput( ); // 1.
if( jobManager != null ) {
  job = jobManager.createJob( ); // 2.
else job = new Job( ); SERVICEURI , true, "opal" , "Psize"); // 3.
job.addListener( "onjoblaunched" , responseHandler) ; // 4.
job.addListener( "onjobquery" , responseHandler) ;
job.addListener( "onjobcompletion" , responseHandler) ;
job.addListener( "onjoberror" , responseHandler) ;
job.addListener( "onjobaborted" , responseHandler) ;
job.addNamespace( "default" , "" ); // 5.
var rv;
if( jobManager != null ) {
  rv = jobManager.addJob( job );
  if( rv )
   job.launch( env ); // 6.
else job.launch( env )
  1. Create the Job's input according to the Web service's WSDL description. In this case a support function, createInput() does the actual work.
  2. If the jobManager global variable is present, use it to create the Job object. Since jobManager always exists, A Job object created this way will continue to run even if the service panel it belongs to is closed.
  3. Initialize the Job (in order): the Web service endpoint, whether to query for status automatically, the type of Web service (usually "opal") and the name of the Web service.
  4. Add callbacks to listen for events during the job's lifecycle. Each of the five possible events listed can be handled by seperate functions or by a single all-purpose function as in this example.
  5. Add a namespace to use with the Web service calls. Each operation (launch, status, etc) might have a different namespace however only a "default" is required.
  6. If the jobManager global variable is present and you want to use it to manage execution, use the addJob()

For applications that are known to take a very long time to run, it may be useful to set a higher value for the interval between status queries using setQueryInterval which takes one argument in milliseconds. The default value is 10000 (10 seconds).


The Job Manager is used to persist Job information when Gemstone is closed so that execution can be resumed when it's next started. The addJob() function does all the neccesary work to persist a Job's information as well as to make it viewable in the Job Manager panel (View-->Job Manager). The figures below show the Manager panel (left) and the first job's stored information (right)

Job Manager Job Properties

The Job Manager can be enabled/disabled by the user by using the "Preferences" menu. If disabled, calling addJob() as in step 6. of the Job.js example has no effect and is not an error.

Once a job has been launched and is under control of the Job Manager, a service panel can be safely closed. The Job's information will continue to appear in the Manager panel and will be updated with every status query.

It is also possible to use the stored information to re-open a service panel. This ability is experimental and will be enhanced in future releases.

The gemstone project can be contacted through the mailing list or the member list.
Copyright © 2000-2018. All rights reserved. Terms of Use & Privacy Policy.