Module org.tentackle.maven.plugin.jlink
Package org.tentackle.maven.plugin.jlink

Class JPackageMojo

java.lang.Object
org.apache.maven.plugin.AbstractMojo
org.tentackle.maven.AbstractTentackleMojo
org.tentackle.maven.plugin.jlink.AbstractJLinkMojo
org.tentackle.maven.plugin.jlink.JPackageMojo
All Implemented Interfaces:
org.apache.maven.plugin.ContextEnabled, org.apache.maven.plugin.Mojo
@Mojo(name="jpackage", requiresDependencyResolution=RUNTIME, defaultPhase=PACKAGE) public class JPackageMojo extends AbstractJLinkMojo
Creates a java application installer with the jpackage tool.

The mojo works in 4 phases:

  1. Invokes the jlink tool as described in JLinkMojo. This will generate a directory holding the runtime image. However, no run or update scripts and no zip file will be created.
  2. Invokes the jpackage tool to generate the application image from the previously created runtime image. Application- and platform specific options can be configured via the packageImageTemplate.
  3. If the runtime image contains extra classpath- or modulepath-elements, the generated config files will be patched. This is especially necessary to provide the correct classpath order according to the maven/module dependency tree, which usually differs from the one determined by jpackage, because jpackage has no idea about the maven project structure and does its own guess according to the packages referenced from within the jars. This may become an issue if the classpath order is critical, such as configurations overridden in META-INF.
  4. Finally, the installer will be generated from the application image. The packageInstallerTemplate is used to provide additional options to the jpackage tool.
The minimum plugin configuration is very simple: 
   ...
   <packaging>jpackage</packaging>
   ...
       <plugin>
         <groupId>org.tentackle</groupId>
         <artifactId>tentackle-jlink-maven-plugin</artifactId>
         <version>${tentackle.version}</version>
         <extensions>true</extensions>
         <configuration>
           <mainModule>com.example</mainModule>
           <mainClass>com.example.MyApp</mainClass>
         </configuration>
       </plugin>
The freemarker templates are copied to the project's template folder, if missing. They become part of the project and can be changed easily according to project specific needs (for example by adding runtime arguments). To install and edit the templates before running jpackage (or jlink, see JLinkMojo), use InitMojo first. In addition to the template variables defined by the JLinkMojo, the variable runtimeDir is provided pointing to the runtime image directory (which is platform specific).

If the application is built with Tentackle's update feature, please keep in mind that applications deployed by an installer are maintained by a platform specific package manager. If the installation is system-wide, the installation files cannot be changed by a regular user. Some platforms, however, also provide per-user installations that can be updated. For Windows, the jpackage tool provides the option --win-per-user-install. MacOS allows the user to decide whether to install system-wide or for the current user only. See AbstractJLinkMojo.isWithUpdater() for more details.

If both jlink zip-files and jpackage installers are required, change the packaging type to jar and add executions, like this: 

         <executions>
           <execution>
             <id>both</id>
             <goals>
               <goal>jlink</goal>
               <goal>jpackage</goal>
             </goals>
           </execution>
         </executions>
The jpackage goal will then re-use the previously created jlink image.

The contents of the application image and attachment of the artifacts for installation and deployment can be customized by an application-specific implementation. To do so, provide a plugin dependency that contains a class annotated with @Service(ArtifactCreator).

Important: the jpackage tool is available since Java 14.

Notice that you can create an image for a different java version than the one used by the maven build process via AbstractTentackleMojo.getToolchain(). Furthermore, you can select the jpackage tool explicitly from another JDK via jpackageToolchain or jpackageTool.

  • Field Details

    • PACKAGE_IMAGE_TEMPLATE

      public static final String PACKAGE_IMAGE_TEMPLATE
      filename of the options template to create the application image.
      See Also:

    • PACKAGE_INSTALLER_TEMPLATE

      public static final String PACKAGE_INSTALLER_TEMPLATE
      filename of the options template to create the installer.
      See Also:

    • PACKAGE_UPDATE_TEMPLATE

      public static final String PACKAGE_UPDATE_TEMPLATE
      filename of the template to create the package updater script.
      See Also:

    • OPTIONS_IMAGE

      public static final String OPTIONS_IMAGE
      filename of the generated jpackage options to create the application image.
      See Also:

    • OPTIONS_INSTALLER

      public static final String OPTIONS_INSTALLER
      filename of the generated jpackage options to create the installer.
      See Also:

  • Constructor Details

    • JPackageMojo

      public JPackageMojo()

  • Method Details

    • getImagePathPrefix

      public String getImagePathPrefix()
      Description copied from class: AbstractJLinkMojo
      Gets the prefix to the jars and dirs in the runtime image.
      Overrides:
      getImagePathPrefix in class AbstractJLinkMojo
      Returns:
      the prefix, empty string if none (never null)

    • getPackageImageTemplate

      public String getPackageImageTemplate()
      Gets the name of the package template to create the application image.
      Returns:
      the template file name

    • getPackageInstallerTemplate

      public String getPackageInstallerTemplate()
      Gets the name of the package template to create the installer.
      Returns:
      the template file name

    • getPackageUpdateTemplate

      public String getPackageUpdateTemplate()
      Gets the name of the package updater template.
      Returns:
      the template file name, null if update feature disabled

    • getPackageDirectory

      public File getPackageDirectory()
      Gets the directory where to create the installers.
      Returns:
      the installer target directory

    • prepareExecute

      public void prepareExecute() throws org.apache.maven.plugin.MojoExecutionException, org.apache.maven.plugin.MojoFailureException
      Overrides:
      prepareExecute in class AbstractJLinkMojo
      Throws:
      org.apache.maven.plugin.MojoExecutionException
      org.apache.maven.plugin.MojoFailureException

    • executeImpl

      public void executeImpl() throws org.apache.maven.plugin.MojoExecutionException, org.apache.maven.plugin.MojoFailureException
      Overrides:
      executeImpl in class AbstractJLinkMojo
      Throws:
      org.apache.maven.plugin.MojoExecutionException
      org.apache.maven.plugin.MojoFailureException

    • createImage

      protected void createImage(JLinkResolver.Result result) throws org.apache.maven.plugin.MojoFailureException, org.apache.maven.plugin.MojoExecutionException
      Description copied from class: AbstractJLinkMojo
      Invokes the jlink tool and copies other artifacts and resources.
      Overrides:
      createImage in class AbstractJLinkMojo
      Parameters:
      result - the resolver result
      Throws:
      org.apache.maven.plugin.MojoFailureException
      org.apache.maven.plugin.MojoExecutionException

    • generateFiles

      protected void generateFiles(JLinkResolver.Result result) throws org.apache.maven.plugin.MojoExecutionException
      Description copied from class: AbstractJLinkMojo
      Generates additional files such as shell scripts or command files.
      Specified by:
      generateFiles in class AbstractJLinkMojo
      Parameters:
      result - the resolver result
      Throws:
      org.apache.maven.plugin.MojoExecutionException - if generation failed

    • validate

      protected boolean validate() throws org.apache.maven.plugin.MojoExecutionException
      Overrides:
      validate in class AbstractJLinkMojo
      Throws:
      org.apache.maven.plugin.MojoExecutionException

    • installTemplates

      protected void installTemplates(boolean overwrite) throws org.apache.maven.plugin.MojoExecutionException
      Description copied from class: AbstractJLinkMojo
      Copies the templates to the template directory.
      Specified by:
      installTemplates in class AbstractJLinkMojo
      Parameters:
      overwrite - true if overwrite existing templates, false if install only missing
      Throws:
      org.apache.maven.plugin.MojoExecutionException - if installation failed