Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8178442

JEP 311: Java Packager API & CLI

    Details

    • Author:
      Victor Drozdov
    • JEP Type:
      Feature
    • Exposure:
      Open
    • Subcomponent:
    • Scope:
      JDK
    • Discussion:
      jdk dash dev at openjdk dot java dot net
    • Effort:
      M
    • Duration:
      M
    • JEP Number:
      311

      Description

      Summary

      Create a new, long-term API and CLI for the Java Packager.

      Motivation

      The Java Packager API is not currently documented or supported. It is used by build tools such as ant-javafx.jar, and by Gradle and Maven plugins. Currently they use an API that is located in the packages:

      com.oracle.tools.packager
      com.sun.javafx.tools.packager
      com.sun.javafx.tools.packager.bundlers
      com.sun.javafx.tools.resource

      The API is far too broad. It should be more consistent with the platform, and no longer export com.sun.* or com.oracle.* packages. These are all deprecated in JDK 10 and will be removed in JDK 11. All package names should share a common prefix. Every option should be available via the CLI.

      The current Java Packager CLI is not intuitive, not consistent with other Java tools, and not all features are accessible. The Java Packager needs to provide a new CLI that exposes all features, and is available via a ToolProvider.

      Description

      ant-javafx.jar will be deprecated, and replaced with ant-java.jar, which uses the new ToolProvider API and and changes all scopes from "fx" to "packager". The Java Packager will be accessible by a ToolProvider in a manner similar to the javac compiler and the jdeps tool. Java Web Start support(JNLP files) will be removed in the new CLI.

      CLI arguments

      For backward compatibility, existing CLI arguments will be left as-is for JDK 10, and refactored into a method that can be removed later.

      The CLI will be reworked to be simpler and expose all Java Packager features. Argument syntax will be more robust, and support one of four options:

      -name=value
      -name value
      --name=value
      --name value

      New CLI arguments

      NOTE: This is just a preliminary list of arguments.

      These are the first order arguments that determine what the operation that the Java Packager will be performing:

      -create-image
      -create-installer

      -create-image

      -verbose
      -name
      --module
      --module-path
      --add-modules
      --limit-modules
      -icon
      -outdir <directory>
      --strip-native-commands <true/false>
      -title
      -vendor
      -description
      -category
      -copyright
      -license
      -secondaryLauncher.name
      -secondaryLauncher.module
      -secondaryLauncher.mainclass
      -srcdir
      -srcfiles
      -version
      -mainclass
      -classpath
      -mainJar/-appclass
      -daemon
      -preloader
      -jvmargs <name,value>(:<name,value>)*
      -jvmuserargs <name,value>(:<name,value>)*
      -daemon/-service
      -BapplicationCategory=
      -BappVersion=
      -Bmac.CFBundleIdentifier=
      -Bmac.category=
      -Bmac.CFBundleVersion=
      -BsignBundle=false
      -mac.file.associations <extension,"description">(:<extension,"description">)*
      -default-arguments <value>(:<value>)*
      -Bicon.png

      -create-installer

      -Bmac.dmg.simple=true
      -file.associations <extension,"description">(:<extension,"description">)*
      -BsignBundle=false
      -Bmac.app-store-entitlements=<filename>
      -installdirChooser
      -Bwin.menuGroup
      -Bwin.64Bit
      -Bwin.64BitJreRuntime
      -Bwin.registryName
      -Bwin.installerName
      -Blinux.bundleName
      -Blinux.deb.fullPackageName
      -Blinux.deb.imageDir
      -Blinux.deb.imageRoot
      -Blinux.deb.configDir
      -Blinux.deb.maintainer
      -Blinux.deb.licenseText
      -Blinux.xdg-prefix

      Configuration-file support

      There will be support similar to java.exe, to pass all arguments via a configuration file. This will be a properties file.

        Attachments

          Issue Links

          1.
          Add ant-java.jar Sub-task Resolved Victor Drozdov (Inactive)  
          2.
          Deprecate ant-javafx.jar Sub-task Resolved Victor Drozdov (Inactive)  
          3.
          Change all scopes from "fx" to "packager" Sub-task Resolved Victor Drozdov (Inactive)  
          4.
          Refactor existing CLI (prepare for future removal) Sub-task Resolved Chris Bensen (Inactive)  
          5.
          Design and implement new CLI Sub-task Resolved Victor Drozdov (Inactive)  
          6.
          Add ToolProvider implementation for java packager Sub-task Resolved Alexander Matveev  
          7.
          ant-java.jar to use ToolProvider Sub-task Resolved Alexander Matveev  
          8.
          Add config file support Sub-task Resolved Victor Drozdov (Inactive)  
          9.
          Check main jar manifest if "main-class" is omitted Sub-task Resolved Victor Drozdov (Inactive)  
          10.
          If only one jar is specified, consider it as main Sub-task Resolved Victor Drozdov (Inactive)  
          11.
          Change javapackager entry point Sub-task Resolved Chris Bensen (Inactive)  
          12.
          Add checks for mutually exclusive arguments Sub-task Resolved Victor Drozdov (Inactive)  
          13.
          Add mechanism for validating dependent arguments Sub-task Resolved Victor Drozdov (Inactive)  
          14.
          Add secondaryLaunchers support for CLI Sub-task Resolved Victor Drozdov (Inactive)  
          15.
          Add missing arguments in new CLI Sub-task Resolved Victor Drozdov (Inactive)  
          16.
          Add new parameter for predefined app image in the new CLI Sub-task Resolved Victor Drozdov (Inactive)  
          17.
          "--main-jar" shouldn't be mandatory parameter for image or installer Sub-task Resolved Victor Drozdov (Inactive)  
          18.
          For ant-java.jar, <bundleArgument arg=...> should accept only new arguments Sub-task Resolved Alexander Matveev  
          19.
          Add new parameter ("--jnlp") for generating images/installers from .jnlp files Sub-task Resolved Victor Drozdov (Inactive)  
          20.
          Add "--help" for new CLI Sub-task Resolved Victor Drozdov (Inactive)  
          21.
          Implement a mechanism for parsing .jnlp and creating a cmd line based on the parsed file. Sub-task Closed Alexander Matveev  
          22.
          Implement a mechanism for creating a bundle for downloaded files (from .jnlp). Sub-task Closed Alexander Matveev  
          23.
          Deprecate classes in legacy.* package Sub-task Resolved Victor Drozdov (Inactive)  

            Activity

              People

              • Assignee:
                vdrozdov Victor Drozdov (Inactive)
                Reporter:
                cbensen Chris Bensen (Inactive)
                Owner:
                Victor Drozdov (Inactive)
                Reviewed By:
                Chris Bensen (Inactive), Kevin Rushforth
                Endorsed By:
                Kevin Rushforth
              • Votes:
                1 Vote for this issue
                Watchers:
                12 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: