Oracle Java SE Embedded: Developer's Guide

13 Launch Embedded Applications

This chapter shows you how to use the java launcher with various options and flags to launch your embedded applications on the target device. It also shows how to exit an application running on an embedded device and where to go for troubleshooting help.

It contains the following sections.

Launch the Application with the java Launcher Tool

Start an application for performance testing on the target device with the java launcher. You can use the -cp or -jar option.

The following example shows the commands for remotely launching the application with ssh and java -cp. In this example, the user name on the target device is pi

$ ssh pi@
pi@'s password: 
$ java -cp Hello.jar helloworldapp.HelloWorldApp 

The final argument is the package.class that contains the application's main() method.

Besides this generic example, you can Launch Your Application with a Specific JVM or Launch Your Application in Debug Mode. See also Unsupported java Launcher Options in the Minimal JVM

Launch Your Application with a Specific JVM

An Oracle Java SE Embedded JRE can contain multiple JVMs. You can specify a particular JVM with these java launcher options:

  • -minimal

  • -client

  • -server

If you use the -client and -server option and that JVM is not present or available, then it will be aliased to the available JVM. Using the -minimal option causes an error if the minimal JVM is not present.

Enable Client Compiler (C1) Profiled Inlining

The client compiler inlining policy uses profile information to improve performance in the minimal and client JVMs. You can enable C1 profiled inlining by using the java launcher flag -XX:+C1ProfileInlining.

Improving JVM Startup Times with Class Data Sharing

Class Data Sharing (CDS) is used with the HotSpot VM to reduce JVM startup times. For general information about CDS, see the Java SE 8 documentation.

Starting with Oracle Java SE Embedded 8u6, you can customize the set of classes included in the classlist and the name of the shared-archive file, and you can specify a custom location for the classlist. These are special features for Oracle Java SE Embedded applications.


The shared-archive file content is considered trusted by default, meaning the contents are not checked, but it contains executable native code that runs outside the Java sandbox. Ensure that the integrity of any shared-archive file you generate cannot be subject to potentially malicious modifications.

There are three java launcher flags that are related to custom CDS classlists:


Creates a custom classlist by writing out the set of all classes loaded by the boot loader to the named file in <classlist_file>. This custom classlist can be used by CDS when creating a shared archive.


Specifies a user-defined classlist to be used when creating a shared archive, such as the one created by the -XX:DumpLoadedClassList flag.


Specifies the name and location of the shared-archive file to be written to during a CDS dump, or read from during JVM execution with CDS enabled.

Here is an example of how you build and implement a custom classlist for your application.

Task 1    Generate the custom list of core library (boot) classes used by your application
java -XX:DumpLoadedClassList=./MyApp.classlist MyApp 
Task 2   Generate a custom shared archive containing those classes
java -Xshare:dump -XX:SharedClassListFile=./MyApp.classlist
Task 3   Run your application using the custom shared archive
java -Xshare:on -XX:SharedArchiveFile=./MyApp.jsa MyApp

Launch Your Application in Debug Mode

If you have a JRE on the target that was built with debugging support, you can start the application in debug mode, then attach a JVMTI-compliant remote debug client from any host on the same network. One client is jdb, described in the Java SE tools documentation for UNIX and Windows. Example 13-1 shows launching with java -jar in debug mode.

Example 13-1 Launching with -jar in Debug Mode

$ java -jar Hello.jar \


Some debugging functionality requires that the java tool be run with the -XX:+UsePerfData flag. By default in Oracle Java SE Embedded, this flag is turned off, whereas it is turned on by default in the Java SE JDK.

Unsupported java Launcher Options in the Minimal JVM

To reduce memory use, the minimal JVM does not support some virtual machine options passed by the java launcher. When an unsupported option is specified, depending on its seriousness, the launcher prints a warning message, ignores the option, and launches the JVM, or prints an error message and terminates without launching the JVM.

Table 13-1 Options not Supported by the Minimal JVM

Option(s) java Launcher Response

-agentpath:jdwp, -Xrunjdwp




-Xagent:hprof, -Xrunhprof, -agentlib:hprof, -agentpath:hprof




-Xincgc, -XX:+UseGarbageCollector




-Xshare:dump, -Xshare:on








The minimal JVM does not support remote debugging, profiling, monitoring, and serviceability tools. These include jcmd, jdb, jinfo, jmap, jstack, and others, including integrated development environments. The minimal JVM ignores requests from these tools.

Exit an Application Running on an Embedded Device

Java applications cannot be terminated from the device's console. However, applications can be terminated using a remote shell:

$ pkill java 


If you have difficulty with an application, you can find diagnostic help in the Java Platform, Standard Edition Troubleshooting Guide.

Also refer to Oracle Java SE Embedded Release Notes for known issues.

Close Window

Table of Contents

Oracle Java SE Embedded: Developer's Guide

Expand | Collapse