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.

Figure 4-1 Background Operations and Screen Events During Application Startup

Description of "Figure 4-1 Background Operations and Screen Events During Application Startup"

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.2 Default User Experience

A properly packaged application provides default visual feedback to the user for the first two phases for all execution modes. The actual behavior depends on the execution mode and type of application.

When launched in standalone mode, most applications start quickly, and no visual feedback is required.

Table 4-1 summarizes the default behavior according to execution mode when the application is launched for the first time and is loaded from the network.

Table 4-1 Default Behavior During First-Time Launch

Startup Phase	Java Web Start Launch	Embedded in a Web Page
Phase 1 Initialization	Splash screen: Description of the illustration java8_splash.gif	Splash screen, JavaFX applications: Description of the illustration html_splash_75.gif Splash screen, Java applications: Description of the illustration html_splash_se8.gif
Phase 2 Loading Code	Progress window, JavaFX applications: Description of the illustration ws_load.png	Progress window, JavaFX applications: Description of the illustration progress_dialog2_40.gif
Phase 3 Transition to Application	Hide progress window	Fade-out progress window, JavaFX applications

Table 4-2 summarizes the default behavior for subsequent launches, in which the JAR files are loaded from the cache. In this case, the process has fewer visual transitions because nothing needs to be loaded from the network during the Loading Code phase, so launch time is substantially shorter.

Table 4-2 Default Startup Behavior During Subsequent Launches

	Java Web Start Launch or Launch from Shortcut	Embedded into Web Page
Phase 1 Initialization	Splash screen: Description of the illustration java8_splash.gif	Splash screen, JavaFX applications: Description of the illustration html_splash_75.gif Splash screen, Java applications: Description of the illustration html_splash_se8.gif
Phase 2 Loading Code	Splash screen: Description of the illustration java8_splash.gif	Splash screen, JavaFX applications: Description of the illustration html_splash_75.gif Splash screen, Java applications: Description of the illustration html_splash_se8.gif
Phase 3 Transition to Application	Hide splash screen	Hide splash screen

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:

.default-preloader { 
    -fx-background-color: yellow; 
    -fx-text-fill: red; 
    -fx-preloader-graphic: url("http://host.domain/duke.gif"); 
    -fx-preloader-text: "Loading, loading, LOADING!"; 
} 

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

<fx:deploy ...>
    <fx:application ...>
        <fx:htmlParam  name="javafx.default.preloader.stylesheet" 
                value="my.css"/>
    <fx:application>
</fx:deploy>

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.

<fx:deploy ...>
    <fx:application ...>
    <!-- Using fx:param here, so it will be applicable to all web
            execution environemnts -->
        <fx:param  name="javafx.default.preloader.stylesheet"
                value=".default-preloader { -fx-background-color: yellow; }"/>
    <fx:application>
</fx:deploy> 

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.2.4 Customization Options for Java Applets

Custom splash screens can be used with Java applets by passing in additional parameters when you deploy the applet. See Section 14.3.1, "Adding a Splash Screen" for information.

To add a custom progress bar to your applet, create a class that implements the DownloadServiceListener interface. See Displaying a Customized Loading Progress Indicator for instructions.

4.3.1 No JRE

If the user does not have the JRE installed, then the application cannot start. The application package includes several hooks to improve the user experience in this case.

You can customize the default behavior described in the following sections. See Chapter 19, "Deployment in the Browser" for information about how to customize prompts to install the JRE, and error handling for web applications.

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."