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 the to 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.withUpdater 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.jdkToolchain. Furthermore, you can select the jpackage tool explicitly from another JDK via jpackageToolchain or jpackageTool.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	OPTIONS_IMAGE	filename of the generated jpackage options to create the application image.
static java.lang.String	OPTIONS_INSTALLER	filename of the generated jpackage options to create the installer.
static java.lang.String	PACKAGE_IMAGE_TEMPLATE	filename of the options template to create the application image.
static java.lang.String	PACKAGE_INSTALLER_TEMPLATE	filename of the options template to create the installer.
static java.lang.String	PACKAGE_UPDATE_TEMPLATE	filename of the template to create the package updater script.

Fields inherited from class org.tentackle.maven.plugin.jlink.AbstractJLinkMojo

DEST_CLASSPATH, DEST_MODULEPATH, DEST_RESOURCES, ZIP_EXTENSION

Fields inherited from class org.tentackle.maven.AbstractTentackleMojo

charset, JDK_TOOLCHAIN, minLogLevel, resourceDirs, verbosity, verbosityLevel

Fields inherited from interface org.apache.maven.plugin.Mojo

ROLE

Constructor Summary

Constructors

Constructor	Description
JPackageMojo()

Method Summary

Modifier and Type	Method	Description
protected void	createImage(JLinkResolver.Result result)	Invokes the jlink tool and copies other artifacts and resources.
void	executeImpl()
protected void	generateFiles(JLinkResolver.Result result)	Generates additional files such as shell scripts or command files.
java.lang.String	getImagePathPrefix()	Gets the prefix to the jars and dirs in the runtime image.
java.io.File	getPackageDirectory()	Gets the directory where to create the installers.
java.lang.String	getPackageImageTemplate()	Gets the name of the package template to create the application image.
java.lang.String	getPackageInstallerTemplate()	Gets the name of the package template to create the installer.
java.lang.String	getPackageUpdateTemplate()	Gets the name of the package updater template.
protected void	installTemplates(boolean overwrite)	Copies the templates to the template directory.
void	prepareExecute()
protected boolean	validate()

Methods inherited from class org.tentackle.maven.plugin.jlink.AbstractJLinkMojo

copyArtifacts, copyExtraDirectories, copyResources, createJLinkImage, createZipFile, getAddModules, getClassifier, getExcludeModules, getExtraClassifier, getExtraClasspathElements, getExtraDirectories, getFinalName, getImageDirectory, getJavaMajorRuntimeVersion, getJavaRuntimeVersion, getJdepsTool, getLocationManager, getMainClass, getMainModule, getProjectHelper, getTemplateDir, getVariables, getVariablesPrecedence, getZipDirectory, installTemplate, isClasspathDependency, isModulePathOnly, isWithUpdater, logToolOutput

Methods inherited from class org.tentackle.maven.AbstractTentackleMojo

createPackageMap, determineEncoding, determineJavaToolVersion, determineVerbosity, execute, findResourceDirs, finishExecute, getCanonicalPath, getHostName, getMajorVersion, getMavenProject, getMavenSession, getMojoExecution, getPathRelativeToBasedir, getResourceDirName, getSettings, getSettingsDecrypter, getToolchain, getToolchain, getToolchain, getToolchainManager, getToolFinder, installJavaLoggingHandler, isExecutionRecursive, isSkippedByDefault, loadResourceFileIntoString

Methods inherited from class org.apache.maven.plugin.AbstractMojo

getLog, getPluginContext, setLog, setPluginContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PACKAGE_IMAGE_TEMPLATE

public static final java.lang.String PACKAGE_IMAGE_TEMPLATE

filename of the options template to create the application image.

See Also:

Constant Field Values

PACKAGE_INSTALLER_TEMPLATE

public static final java.lang.String PACKAGE_INSTALLER_TEMPLATE

filename of the options template to create the installer.

See Also:

Constant Field Values

PACKAGE_UPDATE_TEMPLATE

public static final java.lang.String PACKAGE_UPDATE_TEMPLATE

filename of the template to create the package updater script.

See Also:

Constant Field Values

OPTIONS_IMAGE

public static final java.lang.String OPTIONS_IMAGE

filename of the generated jpackage options to create the application image.

See Also:

Constant Field Values

OPTIONS_INSTALLER

public static final java.lang.String OPTIONS_INSTALLER

filename of the generated jpackage options to create the installer.

See Also:

Constant Field Values

Constructor Detail

JPackageMojo

public JPackageMojo()

Method Detail

getImagePathPrefix

public java.lang.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 java.lang.String getPackageImageTemplate()

Gets the name of the package template to create the application image.

Returns:

the template file name

getPackageInstallerTemplate

public java.lang.String getPackageInstallerTemplate()

Gets the name of the package template to create the installer.

Returns:

the template file name

getPackageUpdateTemplate

public java.lang.String getPackageUpdateTemplate()

Gets the name of the package updater template.

Returns:

the template file name, null if update feature disabled

getPackageDirectory

public java.io.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