Class Link

  • All Implemented Interfaces:
    java.lang.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.
    • Constructor Summary

      Constructors 
      Constructor Description
      Link()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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.
      java.io.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​(java.io.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​(java.lang.String patternList)
      Sets attribute containing a list of patterns denoting files to exclude from linked modules when assembling linked image.
      void setExcludeResources​(java.lang.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​(java.lang.String launcherList)
      Sets attribute containing comma-separated list of information needed for additional executables in the linked image.
      void setLocales​(java.lang.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​(java.lang.String moduleList)
      Sets attribute containing list of modules to link.
      void setObservableModules​(java.lang.String moduleList)
      Sets attribute containing modules linker is permitted to know about.
      void setResourceOrder​(java.lang.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 java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Link

        public Link()
    • Method Detail

      • 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()
      • 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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 java.io.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​(java.io.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()
      • 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