Documentation Contents

Customizing the Rich Internet Application Loading Experience

• The RIA Loading Experience
• The RIA Loading Process
• Issues to Consider
• Customization Options
  • Adding a Splash Screen for an Applet
  • Implementing a Customized Loading Progress Indicator
    • The javax.jnlp.DownloadServiceListener Interface
    • Constructors of the Loading Progress Indicator Class
    • Methods of the javax.jnlp.DownloadServiceListener Interface
    • Specifying the Custom Progress Indicator in the JNLP File
    • How the RIA Software Communicates Progress
• Best Practices and Tips
• Resources

The RIA Loading Experience

Java Rich Internet applications (RIAs) are downloaded over the internet and displayed to the end user. The speed of the download may vary depending on various criteria such as the size of the RIA JAR file, any external dependencies, and the speed of the internet connection.

When the RIA is being downloaded, by default, the RIA software (Java Plug-in and Java Web Start software) will display the standard progress indicators, such as the spinning Java logo and progress bars. End users may get impatient when confronted with large downloads. With improvements in RIA software technology in the Java SE 6 update 18 and Java SE 6 update 21 releases, you can keep the end user engaged by providing a creative, captivating, and meaningful RIA loading experience. You can customize the RIA loading experience in several ways as described next.

• By providing a splash screen
• By creating a customized loading progress indicator
• By leveraging one progress indicator to reflect progress of RIA download and the loading of RIA-specific data

You can also use a combination of the above options to accomodate older versions of the Java Runtime Environment (JRE) software on the client machine.

Note: Certain customization options are specific to applets or to Java Web Start applications. Such cases will be identified in this topic.

The RIA Loading Process

This section describes the process by which RIAs are loaded.

RIA software initiates a series of steps to download, validate, and execute a RIA. The RIA loading process can be broadly broken down into the following stages. RIA software provides varying levels of progress-related feedback during these stages.

• Initialization – During this stage, RIA software performs an assessment of the resources required to launch the RIA. The amount of work required to download, validate, and execute the RIA is indeterminate at this time.
• Loading and validation – RIA software downloads the required resources (JAR files) over the Internet, if necessary. If the RIA has been previously cached, RIA software loads the resources from the local cache. RIA software validates the resources. Deterministic feedback is communicated by the RIA software during the resource loading and validation process. Deterministic feedback implies that percent completion rates are calculated and communicated by the RIA software.
• RIA Execution – During this stage, RIA software executes the RIA. The RIA is now fully functional. The RIA can load application-specific data at this time.

Customization Options

Adding a Splash Screen

The simplest way to customize a RIA's loading experience is to provide a splash screen. Specify the image that should be displayed in the splash screen. No changes are required in the RIA itself. RIA software displays the splash screen when the RIA is being loaded and hides it when the RIA's resources have been downloaded and validated. See the following topics for more information:

• Creating a Splash Screen for an Applet topic in the Java Tutorials to view an example
• Java Web Start FAQ and JNLP FIle Syntax for information about adding a splash screen for a Java Web Start application

Implementing a Customized Loading Progress Indicator

You can replace the default loading progress indicator with a custom implementation that provides regular feedback about how the RIA is loading. Don't feel constrained by rectangular boxes or the use of the Swing JProgressBar component. You can develop a customized loading progress indicator that is meaningful to your RIA or web site. The loading progress indicator can use visual or non-visual means to keep the end user interested and engaged while the RIA is loading in the background.

See Customizing the Loading Experience topic in the Java Tutorials for step-by-step instructions and detailed examples. A few screenshots of loading progress indicators are shown next.

Default loading progress indicator for Java Web Start application

Customized loading progress indicator for Java Web Start application

Customized loading progress indicator for the Reversi JavaFX applet (black balls turn white as loading progresses)

The following features enable varied customizations of the loading progress indicator for a RIA that is deployed by using JNLP technology:

• The customized loading progress indicator can provide deterministic or non-deterministic feedback.
• The customized loading progress indicator can provide visual or non-visual cues to communicate progress.
• A single loading progress indicator can be developed to support applets and Java Web Start applications.
• Multiple loading progress indicators can be defined as Java Network Launch Protocol (JNLP) extensions. The loading progress indicator specified in the RIA's main JNLP file takes precedence (if one is specified). You should specify which extension should be displayed to avoid undeterministic behavior.
• The customized loading progress indicator can be leveraged to also display progress when loading application-specific data. For example, if a RIA invokes web services to load initial application data, you can use the progress range of 0 - 75% to indicate status of RIA download, and use the range of 76% - 100% to indicate progress of a web service invocation that fetches application data.
• Loading progress indicators for applets can perform the following operations:
  • They can receive a reference to an instance of the java.applet.AppletStub class. This allows the loading progress indicator code to access the java.applet.AppletContext object to retrieve the applet's parameters.
  • They can invoke JavaScript code in the applet's parent web page. A reference to the window can be retrieved as shown next.

    JSObject window = JSObject.getWindow(null);
    window.call("someJavaScriptFunction", args);    
        

The next few paragraphs describe technical details about implementing a loading progress indicator.

The javax.jnlp.DownloadServiceListener Interface

A loading progress indicator class should implement the javax.jnlp.DownloadServiceListener interface.

Constructors of the Loading Progress Indicator Class

Specify the following constructors in the loading progress indicator class. The RIA software will invoke the appropriate constructor depending on the capabilities of the JRE software on the client machine. In some cases, RIA software may not instantiate the loading progress indicator class if all resources are up-to-date.

• Constructor without any parameters – This constructor should be specified in the loading progress indicator class for a Java Web Start application. This constructor can also be specified in the loading progress indicator class for an applet. If the RIA software invokes this constructor, the loading progress indicator UI will be displayed in a top level window such as a javax.swing.JFrame object.
• Constructor with one parameter – This constructor has one parameter of type java.lang.Object. The Object argument can be typecast to an instance of the java.awt.Container class. This constructor is relevant to loading progress indicators for applets. If the RIA software (in this case, Java Plug-in software) invokes this constructor, the loading progress indicator UI will be displayed in the applet's container.
• Constructor with two parameters – This constructor has two parameters of type java.lang.Object. The first Object argument can be typecast to an instance of the java.awt.Container class. The second Object argument can be typecast to an instance of the java.applet.AppletStub class. If the RIA software (in this case, Java Plug-in software) invokes this constructor, the loading progress indicator UI will be displayed in the applet's container. The loading progress indicator can access the java.applet.AppletContext object to customize the loading progress indicator further. This constructor is relevant to loading progress indicators for applets.

  When specifying the constructor with two parameters, it is better to also specify the single-parameter constructor to accomodate older versions of the client JRE software. The constructor with two parameters is invoked only when the client JRE software version is at least Java SE 6 update 21.

Methods of the javax.jnlp.DownloadServiceListener Interface

The loading progress indicator class should implement the following methods of the interface to receive and convey the latest progress information.

• progress(URL url, String version, long readSoFar, long total, int overallPercent)
• upgradingArchive(java.net.URL url, java.lang.String version, int patchPercent, int overallPercent)
• validating(java.net.URL url, java.lang.String version, long entry, long total, int overallPercent) – When the loading progress indicator class is instantiated, this method is always invoked with an overallPercent value of 100.

Update progress information in the loading progress indicator based on the overallPercent values received in these methods.

Specifying the Custom Progress Indicator in the JNLP File

Include the following information in the RIA's Java Network Launch Protocol (JNLP) file to specify a loading progress indicator:

• download="progress" attribute to indicate which JAR file contains the loading progress indicator class
• progress-class attribute containing fully qualified name of the loading progress indicator class. This attribute can be defined as a part of the <applet-desc>, <application-desc>, or <component-desc> depending on how the RIA and the loading progress indicator are deployed.

A sample JNLP file for an applet is shown next.

<jnlp spec="1.0+" codebase="" href="">
...
  <resources>
    ...
    <jar href="MyApplet.jar" main="true" />    
    <jar href="CustomProgressIndicator.jar" download="progress" />
  </resources>

  <applet-desc
     name="MyFavoriteApplet"
     main-class="myAppletPackage.MyFavoriteApplet"
     progress-class="myCustomProgressPackage.MyCustomProgressIndicator"
     width="600"
     height="200">
  </applet-desc>
...
</jnlp>

How the RIA Software Communicates Progress

RIA software communicates progress information as follows:

• RIA software instantiates loading progress indicator, if necessary. In some cases, when all resources are cached and up-to-date, the loading progress indicator may not be instantiated at all.
• RIA software invokes the progress, upgradingArchive, validating methods several times with increasing values of overallPercent.
• In some cases, when the resources are already cached and validated, RIA software may just invoke the constructor followed by a 100% completion message.
• RIA software will always send a 100% completion message to the loading progress indicator.

Best Practices and Tips

• When deciding on an approach to customize the RIA loading experience, consider the capabilities of older versions of client JRE software. You can provide a range of increasingly sophisticated implementations depending on the capabilities of the client JRE software and other criteria as described next.
  • Specify a splash screen that can be displayed for applets when the client JRE software version is at least Java SE 6 update 10.
  • Specify a customized loading progress indicator that can be displayed when the client JRE software version is at least Java SE 6 update 18.
• Consider the fact that a splash screen or loading screen may not be displayed at all when a RIA is partially or completely cached.
• When developing a customized loading progress indicator, consider the following items:
  • Keep the size of the loading progress indicator JAR file small. RIA resources are downloaded concurrently. If the loading progress indicator JAR file is large, then it may be downloaded at approximately the same time as other resources. In this case, the loading progress indicator may be displayed for a very short time or may not be displayed at all.
  • Limit the amount of resources required by the loading progress indicator. Avoid using ImageIO or service lookups as this may cause other resources to be downloaded.
  • A loading progress indicator can use the same top level window as the Java Web Start application itself. In this case, limit the amount of resources that are used when the application's constructor is invoked. Specify resource lookups in the application's main method instead.
  • A loading progress indicator can be integrated into the applet's UI. In this case, create a top level container, such as a javax.swing.JPanel object, and add it to the surfaceContainer object described previously. After the applet's resources have been completely downloaded, remove the top level container from the surfaceContainer object and add it to the applet itself.
  • A signed loading progress indicator implementation may be best for a signed RIA. In this case, security warnings would be displayed and accepted early on and progress can be updated without further interruptions.

Resources

• Customizing the Loading Experience topic in the Java Tutorials for step-by-step instructions and examples.
• Client JRE Capabilities - Quick Reference

Copyright © 1993, 2010, Oracle and/or its affiliates. All rights reserved. Please send comments using this Feedback page.

Java Technology