Class Loading in General Interface

General Interface Builder uses dynamic class loading for increased performance and accelerated load time. Dynamic class loading causes classes to be loaded as they're needed at the last possible moment. Since only statically loaded classes are loaded at application startup, the application loads much faster.

The classes distributed with General Interface are partitioned into two categories:

• Statically loaded classes that are always loaded by General Interface at application startup
• Dynamically loaded classes

For a list of statically loaded system classes, see General Interface Framework Classes.

How Classes are Loaded

As a General Interface application loads, General Interface Framework statically loads a subset of the system classes. Next, application classes and application code using the Auto Load option are statically loaded. Finally, all other classes are loaded using the dynamic class loading mechanism. The following table provides an overview of how classes are loaded.

General Interface Framework Classes

The General Interface runtime system, General Interface Framework, always statically loads the classes listed in the following table as the application initializes.

All other system classes, such as Matrix, must be loaded dynamically using the require() method or through deserialization. See jsx3.require() Method.

Application Classes

To statically load your application class files as the application loads, enable the Auto Load option for the JavaScript files in the Project Files palette. For more information, see Enabling the Auto Load Option.

To dynamically load custom application classes when the Auto Load option is off, classes must meet the following requirements:

• The classes must be on the class path, so the system class loader can find the classes. See Specifying Class Paths.
• The jsx3.require() method must be used to load classes explicitly that are not loaded automatically by the component through deserialization. See jsx3.require() Method.

Application Code

To statically load your application code as the application initializes, enable Auto Load for the JavaScript files in the Project Files palette. For more information, see Enabling the Auto Load Option.

If you don't want the application code statically loaded, you can load it dynamically using the Server.loadResource() method. This method looks up a resource registered with the application by its id. The resource must be registered in the config.xml file of the application. For more information, see General Interface API Reference.

Enabling the Auto Load Option

To statically load JavaScript files as the application initializes, you can enable the Auto Load option for individual JavaScript files in your project. When a JavaScript file is set to auto load, the file is statically loaded after the Framework classes are loaded.

To enable the Auto Load option for one or more JavaScript files in your project, complete these steps:

1. Right-click a JavaScript file in the Project Files palette.
2. Choose Auto Load from the context menu. The file name now displays in bold in the Project Files palette.
   

When you enable the Auto Load option, the onLoad attribute for the JavaScript file is set to true in the application configuration file (config.xml).

<record jsxid="1" type="map">
  <record jsxid="id" type="string">main_js</record>
  <record jsxid="type" type="string">script</record>
  <record jsxid="onLoad" type="boolean">true</record>
  <record jsxid="src" type="string">js/logic.js</record>
</record>

jsx3.require() Method

The jsx3.require() method can be used to load classes explicitly. Use the fully qualified class name when using the jsx3.require() method. For example,

jsx3.require("jsx3.net.Form");

Only classes that can be found by the system class loader are loaded. Custom classes can be added on the Classpath panel of the Project Settings dialog. See Specifying Class Paths.

When a component file is deserialized, the class of each object encountered in the file is dynamically loaded if it's not already loaded. Therefore, it's often not necessary to use the jsx3.require() method with classes that descend from jsx3.app.Model. However, if JavaScript code references these classes and if the code executes before a deserialization automatically loads the class, you must use the jsx3.require() method to explicitly load the class.

The jsx3.require() method must be called at least once before making these types of references:

• A static reference to a class descending from jsx3.gui.Model (typically jsx3.gui.**).
• Any references to subclasses of Model that execute before the class is loaded through object deserialization.

Specifying Class Paths

If you've created custom classes, you need to specify the class paths, so the system class loader can find the classes. Class paths are set on the Classpath panel of the Project Settings dialog. Class paths are saved as settings in the application configuration file, config.xml, and are deployed with the project.

For specifics on setting class paths, see Classpath Panel.

Classes must be located in the same directory structure as the package name. See Class Naming Conventions.

Class Naming Conventions

The following file and directory naming conventions for classes are required only for dynamic class loading. For classes that aren't dynamically loaded, these naming conventions are a recommendation only.

The JavaScript class file name should be identical to the class name with a .js extension. For example, a class named SomeClass would be saved as SomeClass.js. The directory structure of the class file must match the package name that the class is in. For example, if SomeClass.js is in a com.tibco package and is saved to a js directory in the project, the class file location should be js/com/tibco/SomeClass.js.