Chapter 7 Build, Webapp and Deployment
Prev 7.7 Download to the Client Next

7.7 Download to the Client

All files referenced by resource tags in xma-app.xml are downloaded to the client. When XMA starts, it first checks the server version of the XMA-application to start. This server version is compared to the combined hash value of xma-app.xml and plugins.xml. If it matches, the cached versions of the files are used, otherwise the new versions of the files are downloaded from the server.

Then it checks all files referenced by top level resource tags, resource tags inside of plugin-impl tags and eventually inside of swt-description tags. Each of these files is downloaded if the hash value of the cached version of the file does not match the hash value described for the file in xma-app.xml or plugins.xml.

Then the login procedure of XMA is executed. Afterwards all files referenced by resource tags inside the component tag of the first component are checked the same way and downloaded if needed. After this, invoke() is called on the first component. The files referenced by resource tags inside other component tags are checked and eventually downloaded, when the corresponding component is used the first time using getComponent() or getComponentExtern(). So the components are downloaded as late as possible while the user is already using the application. Components which are not used are not downloaded.

Because all top level resources need to be downloaded before the first component becomes visible, it is very important, that the total size of all these resources is kept small.

7.7.1 Delta Download

Delta Download is a possibility to reduce the download size of bigger files, if an older version of the same file is already cached on the client side. In this case only the differences between the two versions of the file need to be downloaded. Then the old version on the client is patched with this differences to reproduce the new version.

To use delta download on a file, the corresponding resource tag has to point to a versioned jar-file. A versioned jar-file is a jar-file containing a version number in the form name_<major>.<minor>.<bugfix>.jar. The client side XMA BootRuntime searches for the newest version already cached and tries to download the delta file between the found version and the actually needed version.

E.g. to use delta download on xmartclient.jar you have to change its entry in xma-app.xml from

<resource href="clientrt/xmartclient.jar" type="jar" version="" />
to
<resource href="clientrt/xmartclient_1.8.4.jar" type="jar" version="" shared="true" />

Make this change for all files, you want to deliver using delta download. If a delta file is not found a full download is made automatically. All files not containing version numbers in the form described above are downloaded using the normal full download.

It is strongly recommended to use the parameter shared="true" to increase the probability of already finding an older version of the same library in the cache. With shared="true" the library is shared between all XMA applications in the cache. Without shared="true", only an older version of the same library downloaded from the same XMA application is searched.

See also Resources shared between applications and Delta Download

If there are any resourceLink tags pointing to the file where you added the version number to the file name, you either have to update the resourceLinks to the new filename, too, or remove them. Since resourceLinks are currently not used, you can safely remove them. E.g. if you changed xmartclint.jar for delta download, remove all entries like this:

<resourceLink href="clientrt/xmartclient.jar" />

The application has to pack the delta files to previous versions additional to the full version of the resource in its .war-file.

For the libraries xmartclient.jar and epclient.jar, the delta files can be found at the libraries' Maven repository location. The delta files of the current version to all previous released versions are collected in one zip file (called <artifact>-<version>-xdelta.zip). To download these add them to your project's pom.xml.

For getting the xmartclient.jar delta files add:

 <dependency>
   <groupId>org.codehaus.openxma</groupId>
   <artifactId>xmartclient</artifactId>
   <classifier>xdelta</classifier>
   <type>zip</type>   
   <version>2.0.3</version> <!-- choose the xmartclient version used in your project -->
 </dependency>

For getting the epclient.jar delta files add:

 <dependency>
   <groupId>org.codehaus.openxma</groupId>
   <artifactId>epclient</artifactId>
   <classifier>xdelta</classifier>
   <type>zip</type>   
   <version>5.0.4</version> <!-- choose the epclient version used in your project -->
 </dependency>

The xdelta.zip files have to be unzipped and copied into your project's web application to a folder clientrt. This can be done by little changes in your build.xml.

Define the version of the xmartclient.jar corresponding to the pom.xml entry in an Ant property xmartversion (add this to the preconditions target): 

<property name="xmartversion" value="2.0.3"/>

In the target webapp there are this lines:

<!-- include all runtime libaries required by the client -->
<copy file="${dependency_lib}/xmartclient.jar" preservelastmodified="true" todir="${webappDir}/clientrt"/>
<xmachecksum file="${webappDir}/clientrt/xmartclient.jar"/>

Replace the lines above with this entry:

<!-- include all runtime libaries required by the client -->
<copy file="${dependency_lib}/xmartclient.jar" preservelastmodified="true" tofile="${webappDir}/clientrt/xmartclient-${xmartversion}.jar"/>
<xmachecksum file="${webappDir}/clientrt/xmartclient-${xmartversion}.jar"/>
<unzip src="${dependency_lib}/xmartclient-xdelta.zip" dest="${webappDir}/clientrt"/>

If you want to provide such delta files for some of your own jar-files, there exists the custom ant task jardeltas to generate them. To use it you first have to declare it in your build.xml file.

<taskdef name="jardeltas" 
     classname="at.spardat.xma.boot.antext.JarDeltas"
     classpathref="anttask.class.path" /> <!-- created by script/anttask_pom.xml -->
Then you create the delta files with a statement like the following: 
<jardeltas target="${buildDirVers}/xmartclient_1.8.4.jar" minversion="1_7_0"
   versionsdir="${relDir}/${ant.project.name}" testdeltas="true" no99="true"/>
This example creates the delta files for xmartclient.jar.

jardeltas has the following parameters:

  • target: The path to the most current version of the jar file. It must contain the version number in the form name_<major>.<minor>.<bugfix>.jar

  • versionsdir: The path to the directory containing all the previous versions of the jar file to which the deltas should be generated. This directory must contain subdirectories in the form <major>_<minor>_<bugfix> (e.g 1_7_0). These subdirectories each have to contain one previous version of the jar file. These previous versions of the jar file again must be in the form name_<major>.<minor>.<bugfix>.jar.

  • minversion: This optional parameter defines the minimal version of previous versions to use for delta generation. Older versions are ignored.

  • testdeltas: This optional parameter defines if the generated deltas should be automatically tested. The test consists of applying the generated delta to the old version of the jar file and compare the outcome to the new version of the jar file. It must be identical.

  • no99: This optional parameter can turn of delta generation automatically if the version number is 99_99_99.

Do not forget to create the .MD5-file, too, so the user of the jar-file can simply copy the .MD5-file as described in Using Existing Delta Files. You create the .MD5-file by a statement like the following:

<xmachecksum file="${buildDirVers}/xmartclient_1.8.4.jar" />

Prev Up Next
7.6 XMA Debug Home Chapter 8 XMA Frontend Integration