Using Cross-Domain GI

The cross-domain loading feature allows you to load the General Interface runtime and your application from different security domains, increasing deployment flexibility and allowing you to do the following:

• Host the GI runtime on a content delivery network (CDN)  for improved load times. 
• Use a single runtime installation for several General Interface applications, including applications that are hosted on different domains. This can improve load time since the GI runtime may already be in the browser cache.
• Include General Interface applications in blogs and other management systems where hosting files is not permitted.
• Allow a system administrator to install a single instance of the General Interface runtime to be shared across an organization to simplify application deployment for users.

In a build of GI that supports cross-domain loading all XML and XSL data file have been converted into a JSONP-like format, which supports loading across domains.

For example, the file JSX/locale/messages.xml,

<data jsxnamespace="propsbundle" locales="">
<locale>
<!-- jsx3.lang.ClassLoader -->
<record jsxid="boot.env_reset" jsxtext="Error redefining JSX environment parameter {0} from ''{1}'' to ''{2}''."/>
<record jsxid="boot.class_err" jsxtext="Could not load class {0}."/>
<record jsxid="boot.class_ex" jsxtext="Error loading class {0}: {1}"/>
<record jsxid="boot.class_undef" jsxtext="Loaded JavaScript file {0} but class {1} was not defined."/>
...

becomes JSX/locale/messages.xml.js,

jsx3.net.Request.xdr(
"jsx:/locale/messages.xml",
"<data jsxnamespace=\"propsbundle\" locales=\"\">\n\n <locale>\n <record jsxid=\"boot.env_reset\" jsxtext=\"Error redefining JSX environment parameter {0} from ''{1}'' to ''{2}''.\"/>\n <record jsxid=\"boot.class_err\" jsxtext=\"Could not load class {0}.\"/>\n <record jsxid=\"boot.class_ex\" jsxtext=\"Error loading class {0}: {1}\"/>\n <record jsxid=\"boot.class_undef\" jsxtext=\"Loaded JavaScript file {0} but class {1} was not defined.\"/>\n ... ");

This conversion is completely automated by the build process, which uses the new JsEncodeTask task to compile the XML/XSL resources. The task is turned off by default to avoid some code and data bloat. To enable it you must set the build.gi.xd build property to true, either in build/user.properties or on the command line:

$> ant -Dbuild.gi.xd=true

A pre-built cross-domain ready distribution of GI is available for download as well.

If you want to host your application on a separate domain as well, you must process the XML and XSL resources in your application in a similar manner. You can do so using the same Ant task that General Interface uses. There is also a command line interface for the encoder that comes with the General Interface source distribution:

$> cd WORKSPACE/JSXAPPS/myApp
$> find . -name "*.xml" -or -name "*.xsl" \| xargs \
sh GISRC/build/tools/bin/jsencode.sh -user ../ 

Deployment

When deploying an application cross-domain you must modify the GI launch page to indicate the domains from which resources should be loaded in the cross-domain manner. Consider the following example:

• The GI launch page is http://www.example.com/myApp.html
• The GI application is http://apps.example.com/JSXAPPS/myApp
• The GI runtime is http://cdn.host.com/gi/3.9.0

Then the launch page should include the following:

<script type="text/javascript"
    src="http://cdn.host.com/gi/3.9.0/JSX/js/JSX30.js"
    jsxapppath="http://apps.example.com/JSXAPPS/myApp/"
    jsxxd="http://cdn.host.com/ http://apps.example.com/">

The two URLs in the jsxxd attribute indicate the cross-domain sites. Any resource whose path begins with one of these prefixes will be assumed to exist in the JSONP-like syntax and will be loaded in the cross-domain manner.

Synchronous Loading

Since the introduction of the Asynchronous Modular Platform in Release 3.7, General Interface relies less and less on synchronous loading. Some public APIs still trigger synchronous loading, however. These APIs are still available to use in applications, but they will not work if you deploy the GI runtime or your application cross-domain as described above. This is because the JSONP technique for cross-domain data access works only asynchronously.

The following are examples of synchronous APIs. You must not use any of these in a cross-domain deployment.

• jsx3.require()
•  jsx3.net.Request.send() (when open() is called with bAsync=false)
• jsx3.app.Model.load()
• jsx3.xml.Document.load()
• jsx3.app.Cache.getOrOpenDocument()
• jsx3.lang.ClassLoader.loadJSFileSync()
• XML URL (of jsx3.xml.Cacheable) when XML Async is false
• Persistence = Referenced (not Referenced Async)

In addition, dynamic class loading relies on synchronous loading. Dynamic class loading occurs when an application loads a component file and one or more of the classes used in the component file is not already loaded. There are several possible workarounds to dynamic class loading:

• Use a custom build of GI that pre-loads all GI classes that the application uses.
• Use the AMP architecture and plug-in pre-requisites to declare the class requirements of each plug-in.
• Use the new 3.9 method jsx3.requireAsync() before calling Model.loadXML().