Link (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.taskdefs.modules, class: Link

Package org.apache.tools.ant.taskdefs.modules

# Class Link

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
org.apache.tools.ant.taskdefs.modules.Link

All Implemented Interfaces:
  `Cloneable`

public class Link extends Task
Assembles jmod files into an executable image. Equivalent to the JDK `jlink` command.

Supported attributes:

`destDir`
  Root directory of created image. (required)
`modulePath`
  Path of modules. Should be a list of .jmod files. Required, unless nested module path or modulepathref is present.
`modulePathRef`
  Reference to path of modules. Referenced path should be a list of .jmod files.
`modules`
  Comma-separated list of modules to assemble. Required, unless one or more nested `<module>` elements are present.
`observableModules`
  Comma-separated list of explicit modules that comprise "universe" visible to tool while linking.
`launchers`
  Comma-separated list of commands, each of the form name`=`module or name`=`module`/`mainclass
`excludeFiles`
  Comma-separated list of patterns specifying files to exclude from linked image. Each is either a standard PathMatcher pattern or `@`filename.
`excludeResources`
  Comma-separated list of patterns specifying resources to exclude from jmods. Each is either a standard PathMatcher pattern or `@`filename.
`locales`
  Comma-separated list of extra locales to include, requires `jdk.localedata` module
`resourceOrder`
Comma-separated list of patterns specifying resource search order. Each is either a standard PathMatcher pattern or `@`filename.
`bindServices`
  boolean, whether to link service providers; default is false
`ignoreSigning`
  boolean, whether to allow signed jar files; default is false
`includeHeaders`
  boolean, whether to include header files; default is true
`includeManPages`
  boolean, whether to include man pages; default is true
`includeNativeCommands`
  boolean, whether to include native executables normally generated for image; default is true
`debug`
  boolean, whether to include debug information; default is true
`verboseLevel`
  If set, jlink will produce verbose output, which will be logged at the specified Ant log level (`DEBUG`, `VERBOSE`, `INFO`}, `WARN`, or `ERR`).
`compress`
  compression level, one of:
  `0`
  `none`
    no compression (default)
  `1`
  `strings`
    constant string sharing
  `2`
  `zip`
    zip compression
`endianness`
  Must be `little` or `big`, default is native endianness
`checkDuplicateLegal`
  Boolean. When merging legal notices from different modules because they have the same name, verify that their contents are identical. Default is false, which means any license files with the same name are assumed to have the same content, and no checking is done.
`vmType`
  Hotspot VM in image, one of:
  - `client`
  - `server`
  - `minimal`
  - `all` (default)

Supported nested elements

`<modulepath>`
  path element
`<module>`
  May be specified multiple times. Only attribute is required `name` attribute.
`<observableModule>`
  May be specified multiple times. Only attribute is required `name` attribute.
`<launcher>`
  May be specified multiple times. Attributes:
  - `name` (required)
  - `module` (required)
  - `mainClass` (optional)
`<locale>`
  May be specified multiple times. Only attribute is required `name` attribute.
`<resourceOrder>`
  Explicit resource search order in image. May be specified multiple times. Exactly one of these attributes must be specified:
  `pattern`
    A standard PathMatcher pattern
  `listFile`
    Text file containing list of resource names (not patterns), one per line
  If the `resourceOrder` attribute is also present on the task, its patterns are treated as if they occur before patterns in nested `<resourceOrder>` elements.
`<excludeFiles>`
  Excludes files from linked image tree. May be specified multiple times. Exactly one of these attributes is required:
  `pattern`
    A standard PathMatcher pattern
  `listFile`
    Text file containing list of file names (not patterns), one per line
`<excludeResources>`
  Excludes resources from jmods. May be specified multiple times. Exactly one of these attributes is required:
  `pattern`
    A standard PathMatcher pattern
  `listFile`
    Text file containing list of resource names (not patterns), one per line
`<compress>`
  Must have `level` attribute, whose permitted values are the same as the `compress` task attribute described above. May also have a `files` attribute, which is a comma-separated list of patterns, and/or nested `<files>` elements, each with either a `pattern` attribute or `listFile` attribute.
`<releaseInfo>`
  Replaces, augments, or trims the image's release info properties. This may specify any of the following:
  - A `file` attribute, pointing to a Java properties file containing new release info properties that will entirely replace the current ones.
  - A `delete` attribute, containing comma-separated property keys to remove from application's release info, and/or any number of nested `<delete>` elements, each with a required `key` attribute.
  - One or more nested `<add>` elements, containing either `key` and `value` attributes, or a `file` attribute and an optional `charset` attribute.

Since:
  1.10.6
See Also:
  - `jlink` tool reference

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `class`
  `Link.Compression`
  Child element fully describing compression of a linked image.
  `static class`
  `Link.CompressionLevel`
  Possible attribute values for compression level of a linked image: `0` `none` no compression (default) `1` `strings` constant string sharing `2` `zip` zip compression
  `static class`
  `Link.Endianness`
  Possible values for linked image endianness: `little` and `big`.
  `class`
  `Link.Launcher`
  Child element representing a custom launcher command in a linked image.
  `class`
  `Link.LocaleSpec`
  Child element that contains a pattern matching Java locales.
  `class`
  `Link.ModuleSpec`
  Child element that explicitly names a Java module.
  `class`
  `Link.PatternListEntry`
  Child element type which specifies a jlink files pattern.
  `class`
  `Link.ReleaseInfo`
  Child element describing changes to the default release properties of a linked image.
  `class`
  `Link.ReleaseInfoEntry`
  Grandchild element describing additional release info properties for a linked image.
  `class`
  `Link.ReleaseInfoKey`
  Grandchild element representing deletable key in a linked image's release properties.
  `static class`
  `Link.VMType`
  Possible values for JVM type in linked image: `client`, `server`, `minimal`, or `all`.

- ## Field Summary

  ### Fields inherited from class org.apache.tools.ant.Task

  `target, taskName, taskType, wrapper`

  ### Fields inherited from class org.apache.tools.ant.ProjectComponent

  `description, location, project`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Link()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Link.Compression`
  `createCompress()`
  Creates child `<compress>` element that specifies the level of compression the linker will apply, and optionally, which files in the image will be compressed.
  `Link.PatternListEntry`
  `createExcludeFiles()`
  Creates child `<excludeFiles>` element that specifies files to exclude from linked modules when assembling linked image.
  `Link.PatternListEntry`
  `createExcludeResources()`
  Creates child `<excludeResources>` element that specifies resources in linked modules that will be excluded from linked image.
  `Link.Launcher`
  `createLauncher()`
  Creates child `<launcher>` element that can contain information on additional executable in the linked image.
  `Link.LocaleSpec`
  `createLocale()`
  Creates child `<locale>` element that specifies a Java locale, or set of locales, to include from the `jdk.localedata` module in the linked image.
  `Link.ModuleSpec`
  `createModule()`
  Adds child `<module>` element, specifying a module to link.
  `Path`
  `createModulePath()`
  Adds child `<modulePath>` element.
  `Link.ModuleSpec`
  `createObservableModule()`
  Creates child `<observableModule>` element that represents one of the modules the linker is permitted to know about.
  `Link.ReleaseInfo`
  `createReleaseInfo()`
  Creates child `<releaseInfo>` element that modifies the default release properties of the linked image.
  `Link.PatternListEntry`
  `createResourceOrder()`
  Creates child `<resourceOrder` element that specifies explicit ordering of resources in linked image.
  `void`
  `execute()`
  Invokes the jlink tool to create a new linked image, unless the output directory exists and all of its files are files are newer than all files in the module path.
  `boolean`
  `getBindServices()`
  Attribute indicating whether linked image should pull in providers in the module path of services used by explicitly linked modules.
  `boolean`
  `getCheckDuplicateLegal()`
  Attribute indicating whether linker should check legal notices with duplicate names, and refuse to merge them (usually using symbolic links) if their respective content is not identical.
  `Link.CompressionLevel`
  `getCompress()`
  Attribute indicating level of compression linker will apply to image.
  `boolean`
  `getDebug()`
  Attribute indicating whether linker should keep or strip debug information in classes.
  `File`
  `getDestDir()`
  Required attribute containing directory where linked image will be created.
  `Link.Endianness`
  `getEndianness()`
  Attribute which indicates whether certain files in the linked image will be big-endian or little-endian.
  `boolean`
  `getIgnoreSigning()`
  Attribute indicating whether linker should allow modules made from signed jars.
  `boolean`
  `getIncludeHeaders()`
  Attribute indicating whether to include header files from linked modules in image.
  `boolean`
  `getIncludeManPages()`
  Attribute indicating whether to include man pages from linked modules in image.
  `boolean`
  `getIncludeNativeCommands()`
  Attribute indicating whether to include generated native commands, and native commands from linked modules, in image.
  `Path`
  `getModulePath()`
  Attribute containing path of directories containing linkable modules.
  `LogLevel`
  `getVerboseLevel()`
  Attribute indicating whether linker should produce verbose output, and at what logging level that output should be shown.
  `Link.VMType`
  `getVmType()`
  Attribute indicating what type of JVM the linked image should have.
  `void`
  `setBindServices(boolean bind)`
  Sets attribute indicating whether linked image should pull in providers in the module path of services used by explicitly linked modules.
  `void`
  `setCheckDuplicateLegal(boolean check)`
  Sets attribute indicating whether linker should check legal notices with duplicate names, and refuse to merge them (usually using symbolic links) if their respective content is not identical.
  `void`
  `setCompress(Link.CompressionLevel level)`
  Sets attribute indicating level of compression linker will apply to image.
  `void`
  `setDebug(boolean debug)`
  Sets attribute indicating whether linker should keep or strip debug information in classes.
  `void`
  `setDestDir(File dir)`
  Sets attribute indicating directory where linked image will be created.
  `void`
  `setEndianness(Link.Endianness endianness)`
  Sets attribute which indicates whether certain files in the linked image will be big-endian or little-endian.
  `void`
  `setExcludeFiles(String patternList)`
  Sets attribute containing a list of patterns denoting files to exclude from linked modules when assembling linked image.
  `void`
  `setExcludeResources(String patternList)`
  Sets attribute containing a list of patterns denoting resources to exclude from linked modules in linked image.
  `void`
  `setIgnoreSigning(boolean ignore)`
  Sets attribute indicating whether linker should allow modules made from signed jars.
  `void`
  `setIncludeHeaders(boolean include)`
  Sets attribute indicating whether to include header files from linked modules in image.
  `void`
  `setIncludeManPages(boolean include)`
  Sets attribute indicating whether to include man pages from linked modules in image.
  `void`
  `setIncludeNativeCommands(boolean include)`
  Sets attribute indicating whether to include generated native commands, and native commands from linked modules, in image.
  `void`
  `setLaunchers(String launcherList)`
  Sets attribute containing comma-separated list of information needed for additional executables in the linked image.
  `void`
  `setLocales(String localeList)`
  Sets attribute containing a list of locale patterns, to specify Java locales to include from `jdk.localedata` module in linked image.
  `void`
  `setModulePath(Path path)`
  Sets attribute containing path of directories containing linkable modules.
  `void`
  `setModulePathRef(Reference ref)`
  Sets module path as a reference.
  `void`
  `setModules(String moduleList)`
  Sets attribute containing list of modules to link.
  `void`
  `setObservableModules(String moduleList)`
  Sets attribute containing modules linker is permitted to know about.
  `void`
  `setResourceOrder(String patternList)`
  Sets attribute containing a list of patterns that explicitly order resources in the linked image.
  `void`
  `setVerboseLevel(LogLevel level)`
  Sets attribute indicating whether linker should produce verbose output, and at what logging level that output should be shown.
  `void`
  `setVmType(Link.VMType type)`
  Set attribute indicating what type of JVM the linked image should have.

  ### Methods inherited from class org.apache.tools.ant.Task

  `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

  ### Methods inherited from class org.apache.tools.ant.ProjectComponent

  `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### Link

    public Link()

- ## Method Details

  - ### createModulePath

    public Path createModulePath()
    Adds child `<modulePath>` element.
    Returns:
      new, empty child element
    See Also:
      - `setModulePath(Path)`

  - ### getModulePath

    public Path getModulePath()
    Attribute containing path of directories containing linkable modules.
    Returns:
      current module path, possibly `null`
    See Also:
      - `setModulePath(Path)`
      - `createModulePath()`

  - ### setModulePath

    public void setModulePath(Path path)
    Sets attribute containing path of directories containing linkable modules.
    Parameters:
      `path` - new module path
    See Also:
      - `getModulePath()`
      - `setModulePathRef(Reference)`
      - `createModulePath()`

  - ### setModulePathRef

    public void setModulePathRef(Reference ref)
    Sets module path as a reference.
    Parameters:
      `ref` - path reference
    See Also:
      - `setModulePath(Path)`
      - `createModulePath()`

  - ### createModule

    public Link.ModuleSpec createModule()
    Adds child `<module>` element, specifying a module to link.
    Returns:
      new, unconfigured child element
    See Also:
      - `setModules(String)`

  - ### setModules

    public void setModules(String moduleList)
    Sets attribute containing list of modules to link.
    Parameters:
      `moduleList` - comma-separated list of module names

  - ### createObservableModule

    public Link.ModuleSpec createObservableModule()
    Creates child `<observableModule>` element that represents one of the modules the linker is permitted to know about.
    Returns:
      new, unconfigured child element

  - ### setObservableModules

    public void setObservableModules(String moduleList)
    Sets attribute containing modules linker is permitted to know about.
    Parameters:
      `moduleList` - comma-separated list of module names

  - ### createLauncher

    public Link.Launcher createLauncher()
    Creates child `<launcher>` element that can contain information on additional executable in the linked image.
    Returns:
      new, unconfigured child element
    See Also:
      - `setLaunchers(String)`

  - ### setLaunchers

    public void setLaunchers(String launcherList)
    Sets attribute containing comma-separated list of information needed for additional executables in the linked image. Each item must be of the form * name`=`module or name`=`module`/`mainclass.
    Parameters:
      `launcherList` - comma-separated list of launcher data

  - ### createLocale

    public Link.LocaleSpec createLocale()
    Creates child `<locale>` element that specifies a Java locale, or set of locales, to include from the `jdk.localedata` module in the linked image.
    Returns:
      new, unconfigured child element

  - ### setLocales

    public void setLocales(String localeList)
    Sets attribute containing a list of locale patterns, to specify Java locales to include from `jdk.localedata` module in linked image. Asterisks (`*`) are permitted for wildcard matches.
    Parameters:
      `localeList` - comma-separated list of locale patterns

  - ### createExcludeFiles

    public Link.PatternListEntry createExcludeFiles()
    Creates child `<excludeFiles>` element that specifies files to exclude from linked modules when assembling linked image.
    Returns:
      new, unconfigured child element
    See Also:
      - `setExcludeFiles(String)`

  - ### setExcludeFiles

    public void setExcludeFiles(String patternList)
    Sets attribute containing a list of patterns denoting files to exclude from linked modules when assembling linked image.
    Parameters:
      `patternList` - comman-separated list of patterns
    See Also:
      - `Link.PatternListEntry`

  - ### createExcludeResources

    public Link.PatternListEntry createExcludeResources()
    Creates child `<excludeResources>` element that specifies resources in linked modules that will be excluded from linked image.
    Returns:
      new, unconfigured child element
    See Also:
      - `setExcludeResources(String)`

  - ### setExcludeResources

    public void setExcludeResources(String patternList)
    Sets attribute containing a list of patterns denoting resources to exclude from linked modules in linked image.
    Parameters:
      `patternList` - comma-separated list of patterns
    See Also:
      - `createExcludeResources()`
      - `Link.PatternListEntry`

  - ### createResourceOrder

    public Link.PatternListEntry createResourceOrder()
    Creates child `<resourceOrder` element that specifies explicit ordering of resources in linked image.
    Returns:
      new, unconfigured child element
    See Also:
      - `setResourceOrder(String)`

  - ### setResourceOrder

    public void setResourceOrder(String patternList)
    Sets attribute containing a list of patterns that explicitly order resources in the linked image. Any patterns specified here will be placed before any patterns specified as child elements.
    Parameters:
      `patternList` - comma-separated list of patterns
    See Also:
      - `createResourceOrder()`
      - `Link.PatternListEntry`

  - ### getBindServices

    public boolean getBindServices()
    Attribute indicating whether linked image should pull in providers in the module path of services used by explicitly linked modules.
    Returns:
      true if linked will pull in service provides, false if not
    See Also:
      - `setBindServices(boolean)`

  - ### setBindServices

    public void setBindServices(boolean bind)
    Sets attribute indicating whether linked image should pull in providers in the module path of services used by explicitly linked modules.
    Parameters:
      `bind` - whether to include service providers
    See Also:
      - `getBindServices()`

  - ### getIgnoreSigning

    public boolean getIgnoreSigning()
    Attribute indicating whether linker should allow modules made from signed jars.
    Returns:
      true if signed jars are allowed, false if modules based on signed jars cause an error
    See Also:
      - `setIgnoreSigning(boolean)`

  - ### setIgnoreSigning

    public void setIgnoreSigning(boolean ignore)
    Sets attribute indicating whether linker should allow modules made from signed jars.

    Note: As of Java 11, this attribute is internally forced to true. See the source.

    Parameters:
      `ignore` - true to have linker allow signed jars, false to have linker emit an error for signed jars
    See Also:
      - `getIgnoreSigning()`

  - ### getIncludeHeaders

    public boolean getIncludeHeaders()
    Attribute indicating whether to include header files from linked modules in image.
    Returns:
      true if header files should be included, false to exclude them
    See Also:
      - `setIncludeHeaders(boolean)`

  - ### setIncludeHeaders

    public void setIncludeHeaders(boolean include)
    Sets attribute indicating whether to include header files from linked modules in image.
    Parameters:
      `include` - true if header files should be included, false to exclude them
    See Also:
      - `getIncludeHeaders()`

  - ### getIncludeManPages

    public boolean getIncludeManPages()
    Attribute indicating whether to include man pages from linked modules in image.
    Returns:
      true if man pages should be included, false to exclude them
    See Also:
      - `setIncludeManPages(boolean)`

  - ### setIncludeManPages

    public void setIncludeManPages(boolean include)
    Sets attribute indicating whether to include man pages from linked modules in image.
    Parameters:
      `include` - true if man pages should be included, false to exclude them
    See Also:
      - `getIncludeManPages()`

  - ### getIncludeNativeCommands

    public boolean getIncludeNativeCommands()
    Attribute indicating whether to include generated native commands, and native commands from linked modules, in image.
    Returns:
      true if native commands should be included, false to exclude them
    See Also:
      - `setIncludeNativeCommands(boolean)`

  - ### setIncludeNativeCommands

    public void setIncludeNativeCommands(boolean include)
    Sets attribute indicating whether to include generated native commands, and native commands from linked modules, in image.
    Parameters:
      `include` - true if native commands should be included, false to exclude them
    See Also:
      - `getIncludeNativeCommands()`

  - ### getDebug

    public boolean getDebug()
    Attribute indicating whether linker should keep or strip debug information in classes.
    Returns:
      true if debug information will be retained, false if it will be stripped
    See Also:
      - `setDebug(boolean)`

  - ### setDebug

    public void setDebug(boolean debug)
    Sets attribute indicating whether linker should keep or strip debug information in classes.
    Parameters:
      `debug` - true if debug information should be retained, false if it should be stripped
    See Also:
      - `getDebug()`

  - ### getVerboseLevel

    public LogLevel getVerboseLevel()
    Attribute indicating whether linker should produce verbose output, and at what logging level that output should be shown.
    Returns:
      logging level at which to show linker's verbose output, or `null` to disable verbose output
    See Also:
      - `setVerboseLevel(LogLevel)`

  - ### setVerboseLevel

    public void setVerboseLevel(LogLevel level)
    Sets attribute indicating whether linker should produce verbose output, and at what logging level that output should be shown.
    Parameters:
      `level` - level logging level at which to show linker's verbose output, or `null` to disable verbose output
    See Also:
      - `getVerboseLevel()`

  - ### getDestDir

    public File getDestDir()
    Required attribute containing directory where linked image will be created.
    Returns:
      directory where linked image will reside
    See Also:
      - `setDestDir(File)`

  - ### setDestDir

    public void setDestDir(File dir)
    Sets attribute indicating directory where linked image will be created.
    Parameters:
      `dir` - directory in which image will be created by linker
    See Also:
      - `getDestDir()`

  - ### getCompress

    public Link.CompressionLevel getCompress()
    Attribute indicating level of compression linker will apply to image. This is exclusive with regard to `createCompress()`: only one of the two may be specified.
    Returns:
      compression level to apply, or `null` for none
    See Also:
      - `setCompress(Link.CompressionLevel)`
      - `createCompress()`

  - ### setCompress

    public void setCompress(Link.CompressionLevel level)
    Sets attribute indicating level of compression linker will apply to image. This is exclusive with regard to `createCompress()`: only one of the two may be specified.
    Parameters:
      `level` - compression level to apply, or `null` for none
    See Also:
      - `getCompress()`
      - `createCompress()`

  - ### createCompress

    public Link.Compression createCompress()
    Creates child `<compress>` element that specifies the level of compression the linker will apply, and optionally, which files in the image will be compressed. This is exclusive with regard to the `compress` attribute: only one of the two may be specified.
    Returns:
      new, unconfigured child element
    See Also:
      - `setCompress(Link.CompressionLevel)`

  - ### getEndianness

    public Link.Endianness getEndianness()
    Attribute which indicates whether certain files in the linked image will be big-endian or little-endian. If `null`, the underlying platform's endianness is used.
    Returns:
      endianness to apply, or `null` to platform default
    See Also:
      - `setEndianness(Link.Endianness)`

  - ### setEndianness

    public void setEndianness(Link.Endianness endianness)
    Sets attribute which indicates whether certain files in the linked image will be big-endian or little-endian. If `null`, the underlying platform's endianness is used.
    Parameters:
      `endianness` - endianness to apply, or `null` to use platform default
    See Also:
      - `getEndianness()`

  - ### getCheckDuplicateLegal

    public boolean getCheckDuplicateLegal()
    Attribute indicating whether linker should check legal notices with duplicate names, and refuse to merge them (usually using symbolic links) if their respective content is not identical.
    Returns:
      true if legal notice files with same name should be checked for identical content, false to suppress check
    See Also:
      - `setCheckDuplicateLegal(boolean)`

  - ### setCheckDuplicateLegal

    public void setCheckDuplicateLegal(boolean check)
    Sets attribute indicating whether linker should check legal notices with duplicate names, and refuse to merge them (usually using symbolic links) if their respective content is not identical.
    Parameters:
      `check` - true if legal notice files with same name should be checked for identical content, false to suppress check
    See Also:
      - `getCheckDuplicateLegal()`

  - ### getVmType

    public Link.VMType getVmType()
    Attribute indicating what type of JVM the linked image should have. If `null`, all JVM types are included.
    Returns:
      type of JVM linked image will have
    See Also:
      - `setVmType(Link.VMType)`

  - ### setVmType

    public void setVmType(Link.VMType type)
    Set attribute indicating what type of JVM the linked image should have. If `null`, all JVM types are included.
    Parameters:
      `type` - type of JVM linked image will have
    See Also:
      - `getVmType()`

  - ### createReleaseInfo

    public Link.ReleaseInfo createReleaseInfo()
    Creates child `<releaseInfo>` element that modifies the default release properties of the linked image.
    Returns:
      new, unconfigured child element

  - ### execute

    public void execute() throws BuildException
    Invokes the jlink tool to create a new linked image, unless the output directory exists and all of its files are files are newer than all files in the module path.
    Overrides:
      `execute` in class `Task`
    Throws:
      `BuildException` - if destDir is not set
      `BuildException` - if module path is unset or empty
      `BuildException` - if module list is empty
      `BuildException` - if compressionLevel attribute and compression child element are both specified