Application Startup (original) (raw)

As of JDK 8u451, JavaFX is no longer included as part of Java SE 8. Please visit https://www.oracle.com/javase/javafx for more information.

This topic provides information about the application startup process, user experience, and customization options.

The user experience is an important factor in making an application successful. The deployment of an application creates a user's first impression, and impacts the user's satisfaction with the application.

In this topic, the default experience for users of Java and JavaFX applications is explained, and the options for customizing the user experience are presented. This topic contains the following sections:

• User Experience Considerations
• Application Startup Process, Experience, and Customization
• Helping Users Start the Application

4.1 User Experience Considerations

Users are easily annoyed if they are unable to start an application, do not understand what are the next steps, perceive the application as slow or hung, and for many other reasons.

Default Java packaging takes care of many problem areas including:

• Ensuring the user has the required JRE installed
• Auto installing missing dependencies or offering to install them as needed
• Providing visual feedback to the user while the application is being loaded
• Showing descriptive error messages

For example, when users do not have Java installed and double-click the JAR file for your application, they see a dialog box explaining that they need to download and install the JRE.

Developers have a wide range of options on how to tune the experience for their users, such as:

• Show your own splash screen
• Use a custom loading progress indicator
• For JavaFX applications, customize the messaging (for example, explain to users why they need to install the JRE in a language other than English)

4.2 Application Startup Process, Experience, and Customization

The following sections describe the transition phases of application startup, how users experience those phases, and how the default visual feedback to the user can be customized.

4.2.1 Startup Process

Between the time an application is started and the time the user sees the main dialog, a sequence of events occurs on screen while operations are carried out in the background. Figure 4-1 shows these activities and describes them in the following paragraphs. This startup sequence partially depends on the execution mode and on the speed with which the background operations complete. Figure 4-1 shows a series of boxes that depict the background operations over time, including screen shots of what the user sees as these operations occur for a JavaFX application.

The application startup process has the following phases:

• Phase 1: Initialization
  Initialization of the JRE and an initial examination of the application identifies components that must be loaded and executed before starting the application. The initialization phase is shown in the first two boxes in the upper row in Figure 4-1.
• Phase 2: Loading and preparation
  The required resources are loaded from either the network or a disk cache, and validation procedures occur. For JavaFX applications, all execution modes show either the default or a custom progress bar. This phase is shown in the third box in the upper row in Figure 4-1.
• Phase 3: Application-specific initialization
  The application is started, but additional resources might need to be loaded or other lengthy preparations performed before the application becomes fully functional. For example, it might be necessary to check if elevated permissions are needed and to display the appropriate request for permission to the user.
• Phase 4: Application execution
  The application is shown and is ready to use after the background operations shown in Figure 4-1 are finished.

4.2.1.2 Visual Feedback After Initialization

To provide visual feedback after the initialization phase of a JavaFX application, JavaFX provides a preloader, which gets notifications about the loading progress and can also get application-specific notifications. By default, a preloader with a progress bar is displayed during this phase, as described in Section 4.2.2, "Default User Experience."

You can customize the default preloader, as described in Section 4.2.3, "Customization Options for JavaFX Applications." You can also create your own preloaders to customize the display and messaging. See Chapter 13, "Preloaders for JavaFX Applications" for information.

For Java applets, a custom progress bar can be provided. See Section 14.3.2, "Implementing a Customized Loading Progress Indicator" for information.

4.2.3 Customization Options for JavaFX Applications

The splash screen for embedded applications is displayed in the web page and can be easily customized by using an onGetSplash callback, as shown in Section 19.2.3, "onGetSplash."

The default JavaFX preloader can be customized by using a CSS style sheet, similar to other JavaFX components. Pass the customized style data using the javafx.default.preloader.stylesheet parameter for your application. The following items are valid for the parameter:

• Absolute or relative URI of the CSS style sheet, either as a text file with a .css extension, or in binary form with a .bss extension. For more information about binary conversion, see Section 5.4, "Style Sheet Conversion."
• Actual CSS code.

To customize the preloader, use the .default-preloader class. In addition to standard CSS keys, the preloader has the following special keys:

• -fx-preloader-status-text
  Status text shown in the preloader
• -fx-preloader-graphic
  Absolute or relative URI of the image used by the preloader

Example 4-1 shows an example of CSS file my.css:

Add the style sheet to the fx:deploy Ant task as shown in Example 4-2:

If only a few customizations are needed, pass CSS code instead of a file name, to avoid the overhead of downloading a file. Example 4-3 shows how to change the background color to yellow.

To add a company logo to the default JavaFX preloader, you could pass the following string as a value of the javafx.default.preloader.stylesheet parameter :

".default-preloader { -fx-preloader-graphic:url ('http://my.company/logo.gif'); }"

If customizing the default JavaFX preloader is not enough and you need a different visualization or behavior, see Chapter 13, "Preloaders for JavaFX Applications" for information about how to implement your own preloader, and see Chapter 5, "Packaging Basics" for information about how to add the custom preloader to your package.

4.3 Helping Users Start the Application

In some cases, a user might have difficulty getting your application to run. For example, the following situations could cause an application to fail:

• The user has an unsupported platform.
• The user's system does not have the JRE installed.
• Java is not configured correctly, for example the proxy information is not set.
• The user declined to grant permissions to an application.
• The application does not meet current security requirements.

It is important to plan for users who experience problems, by either providing guidance to resolve the issue or having the application fail gracefully and explaining to the user why it cannot be resolved.

The following sections describe methods for handling some common issues.

4.3.2 Runtime Errors

An application can fail to launch due to various runtime errors or user mistakes, such as the absence of a network connection needed to load some of the application JAR files.

One of the most common errors is when the user does not grant permissions to the application. In that case, the application fails, and the user has to restart the application and then grant permissions to get it to run. In a case like this, it is helpful to explain to the user why the application failed and what the user must do to restart it successfully. By default, an error message is shown, either in a dialog box or inside the web page in the location where the application is embedded.

If the Deployment Toolkit is used, then the onDeployError handler can be used to display an error message in the application area in the web page. You can also consider including some instructions in the splash screen to alert users about granting permissions. For more information, see Chapter 19, "Deployment in the Browser."

For JavaFX applications, you can also include a custom preloader to get notifications about errors, unless the error occurs while launching the preloader. For more information about JavaFX preloaders and code examples, see Chapter 13, "Preloaders for JavaFX Applications."

4.3.3 Multiple JREs Installed

If you run a Java Web Start application and you have both a 32-bit JRE and 64-bit JRE installed on your computer, then the Java Web Start application uses the most recent version of JRE. If both a 32-bit JRE and 64-bit JRE of the same version are installed, then the 32-bit version is initially used. The application uses Java Web Start from this JRE, and it will also use this JRE's classes and libraries.

You can configure your browser so that it prompts you which version of Java Web Start it should use when you want to launch a Java Web Start application. By default, browsers usually use the latest installed version of Java Web Start that was available at the time of the browser's installation.

You can specify which architecture and JRE version your Java Web Start application should use with the arch attribute of the<resources> element and the version attribute of the <java> element. For example:

See resources Element in Java Web Start Guidefor more information about this element.

However, Java Web Start will only use the JRE version and architecture values specified in the JNLP file if security settings, the Deployment Rule Set, your choice of the version of Java Web Start to use (if your browser prompted you for it), and the deploy code (the code that implements Java Web Start) permit it.

For example, suppose you have have 64-bit JRE 8u261 and 32-bit JRE 8u251 installed in your system. You launch your application with a JNLP file whose <resources> element is specified as in the previous example. Java Web Start will be run in the JVM of the same JRE that it's in. With this configuration, this typically will be 64-bit JRE 8u261 (the latest version). At this point, Java Web Start hasn't run any of your application's code. Java Web Start launches another instance of Java Web Start (using the deploy code of 64-bit JRE 8u261) using the JRE specified in the JNLP file, 32-bit JRE 8u251, which will ultimately run your application.

Again, your application might not use the JRE version and architecture values specified in the JNLP file because of factors mentioned previously.