Required Steps for 3.0 to 3.4 Migration

Complete the following steps to migrate your General Interface 3.0 projects to 3.1.x. After you migrate to 3.1.x, you need to migrate to 3.3 and 3.4.

1. Open all projects and project files in General Interface Builder 3.1.x to update all component files to the new 3.1.x package structure. Component files are automatically converted to the new 3.1.x GUI package structure and the serialization files are also updated.
2. Modify all class names and constructors in your JavaScript logic files to the new 3.1.x package structure. For more information, see Package Reorganization in General Interface Release Notes.
3. Modify JavaScript code due to changes in 3.1.x. Read the following topics to see if you need to modify your code:
   
   • Class Hierarchy Related to jsx3.gui.BlockX
     
   • Checking for Equality against Model.getInstanceOf()
     
   • Model.findDescendants() Results Order
     
   • List.selectRecord() and Model Events
4. If your projects use data mapping, update the project as described in Data Mapping for 3.0 to 3.4 Migration.
5. Migrate the updated 3.1.x projects to 3.3 and 3.4 as described in Migrating Projects from 3.1.x to 3.4.

Data Mapping for 3.0 to 3.4 Migration

This section explains the steps for migrating General Interface 3.0 projects that use data mapping to General Interface 3.1.x.

For data mapping, there are two steps to updating your project:

1. Update rules files.
2. Update JavaScript code.

Updating Rules Files

Update mapping rules files to the 3.1.x format. Simply open each rules file in the XML Mapping Utility (formerly SOAP Mapping Utility) in General Interface Builder 3.1.x and save. The rules file is automatically updated to the 3.1.x format. To open the XML Mapping Utility, choose Tools > Communication > XML Mapping Utility. You'll also need to do this in General Interface Builder 3.2 or 3.3.

Updating JavaScript Code

There are two steps for updating JavaScript code to 3.1.x:

1. Update the function code that calls the service.
2. Update method calls that are associated with GUI objects.

Updating the Function Code

The code for calling the jsx3.Service has changed and needs to be updated to use the new jsx3.net.Service.

To update the function code that invokes the service, complete these steps:

1. Open the mapping rules file in General Interface 3.1.x.
2. Click the Generate button on the XML Mapping Utility toolbar and choose the operation from the drop-down list.
3. Replace the 3.0 function code in the JavaScript logic file with the new 3.1.x function code.

Updating Method Calls

You also need to replace any method calls in your JavaScript code that are associated with GUI objects with the new method calls.

Class Hierarchy Related to jsx3.gui.BlockX

In General Interface 3.0, jsx3.List, jsx3.Select, jsx3.Tree, and jsx3.chart.ChartComponent all extended jsx3.BlockX. These classes inherited the methods for storing XML and XSL data in the application cache from BlockX.

In 3.1.x, these methods have been moved to the mixin interface, jsx3.xml.Cacheable. Therefore, jsx3.gui.List, jsx3.gui.Select, jsx3.gui.Tree, and jsx3.chart.ChartComponent no longer extend jsx3.gui.BlockX. Any code that relied on this specific 3.0 class hierarchy will not work in 3.3. For example, the following code will not work:

function alertIfCDF(objControl) {
  if (objControl.isInstanceOf("jsx3.gui.BlockX"))
      objControl.getServer().alert("Alert", objControl.getName() +
      " is a CDF control");
}

It should be changed to:

function alertIfCDF(objControl) {
  if (objControl.instanceOf(jsx3.xml.CDF))
      objControl.getServer().alert("Alert", objControl.getName() +
      " is a CDF control");
}

The method isSubclassOf() is similarly affected.

Checking for Equality against Model.getInstanceOf()

The jsx3.Model.getInstanceOf() method has been deprecated in 3.1. (The Class Inheritance and Introspection document describes the preferred methods for determining whether an object is an instance of a class or interface.) Because of the package reorganization in 3.1, the getInstanceOf() method does not always return the same value as in 3.0. For example, if getInstanceOf() returned jsx3.Block in 3.0, it will return jsx3.gui.Block in 3.1. Therefore, any code that checks the return value of getInstanceOf() for equality will likely break in 3.1.

For example,

// this will break in 3.1
if (objBlock.getInstanceOf() == "jsx3.Block")
    objBlock.getServer().alert("Alert", "It's a block!");

Model.findDescendants() Results Order

General Interface 3.0 included a defect in the jsx3.Model.findDescendants() method that caused the results to be returned in reverse order. This was in violation of the method contract that said the results would be returned in either depth-first or breadth-first order. This defect is fixed in 3.1. However, any code that relied on the order of the results from this method may break in 3.1.

The following methods that call find Descendants() are also affected: Model.getDescendantOfName(), Model.getFirstChildOfType(), and Model.getDescendantsOfType(). The isSubclassOf() method would be similarly affected.

List.selectRecord() and Model Events

The contract of the jsx3.gui.List.selectRecord() method has changed. In 3.0, it caused the SELECT model event to fire. In 3.1, it never caused the model event to fire. This change is related to the new 3.1 model event protocol detailed in the Model Events document. For an application running under the 3.0 model event protocol to continue to function properly in 3.1, List.selectRecord() should be replaced with List.doSelect().Otherwise, the application must be upgraded to the 3.1 model event protocol. All other methods affected by the new event protocol are backwards compatible in 3.1.