Module org.update4j
Package org.update4j

Class FileMetadata

Object
FileMetadata
public class FileMetadata extends Object
This class represents a managed file (—in sense of updating and dynamically loading onto a JVM instance upon launch) in this framework. It corresponds with the <file> XML element.

Some metadata is required for updating only, some are required for launch only, and some are for both. The documentation will try to point that out for each field.

An instance of this class cannot be created directly, only Configuration.Builder and Configuration.parse(ConfigMapper) can. For both approaches you use a special interim object: The builder takes a FileMetadata.Reference object in the file() method — created by either readFrom(Path) for single files, or streamDirectory(Path) for a complete directory. The parse() method works with the ConfigMapper class that lists files with FileMappers.

An instance of this class is immutable and thus thread-safe.

Author:
Mordechai Meisels

  • Method Details

    • getUri

      public URI getUri()
      Returns the download URI for this file. This might be directly expressed in the uri attribute as an absolute uri, relative to the base uri, or — if missing — inferred from the path attribute.

      When inferring from the path it will use the complete path structure if — and only if — the path is relative to the base path. Otherwise it will only use the last part (i.e. the "filename").

      If this file is marked for a foreign OS and the URI has a foreign property in the file (a property marked for a different os), it will return null.

      This field is only used for updating.

      Returns:
      The download URI for this file.

    • getPath

      public Path getPath()
      Returns the local path for this file. This might be directly expressed in the path attribute as an absolute path, relative to the base path, or — if missing — inferred from the uri attribute.

      When inferring from the uri it will use the complete path structure if — and only if — the uri is relative to the base uri. Otherwise it will only use the last part (i.e. the "filename").

      If this file is marked for a foreign OS and the path has a foreign property in the file (a property marked for a different os), it will return null.

      This field is used for both updating and launching.

      Returns:
      The local path for this file.

    • getOs

      public OS getOs()
      Returns the operating system expressed in the os attribute, or null if non.

      This field is used for both updating and launching.

      Returns:
      The operating system expressed in the os attribute, or null if non.

    • getChecksum

      public long getChecksum()
      Returns the Adler32 checksum of this file. Used to check if an update is needed and to validate the file post-download.

      This field is only used for updating.

      Returns:
      The Adler32 checksum of this file.

    • getSize

      public long getSize()
      Returns the file size. Used to check if an update is needed, validate the file post-download, and to calculate proper download deltas.

      This field is only used for updating.

      Returns:
      The file size.

    • isClasspath

      public boolean isClasspath()
      Returns if this file is marked to be loaded on the dynamic classpath. Files in the bootstrap and non-jar files should generally be marked false.

      This field is only used for launching.

      Returns:
      If this file is marked to be loaded on the dynamic classpath.

    • isModulepath

      public boolean isModulepath()
      Returns if this file is marked to be loaded on the dynamic modulepath. Files in the bootstrap should generally be marked false. Non-jar files must not mark this true or the JVM will fail.

      This field is only used for launching.

      Returns:
      If this file is marked to be loaded on the dynamic classpath.

    • getComment

      public String getComment()
      Returns a string from the comment attribute, or null if missing.

      This has no effect on the framework and can be used for just anything. For instance: you might mark this file with requiresRestart to notify the update handler to restart the application if this file was part of the update. Or you might put an authentication key which might then be used in the download by overriding UpdateHandler.openDownloadStream(FileMetadata).

      Returns:
      A string from the comment attribute, or null if missing.

    • isIgnoreBootConflict

      public boolean isIgnoreBootConflict()
      Returns whether this file was marked to ignore a boot conflict check.

      The boot conflict check is a safety measure put in place to prevent breaking your remote applications, and then being impossible to fix remotely just by pushing a new release.
      If you push a file that then gets loaded onto the boot modulepath (by placing it in a location that is searched by the modulepath) and that file ends up being a invalid module (as split package, duplicate module name or just not a zip file), the JVM will complain and resist to start up. Since we can't start the application anymore, there is no way to fix this other than reinstalling the application.

      This file check is done for each and every file with the .jar file extension, even if the file was explicitly marked with the modulepath (meaning it is only loaded on the dynamic modulepath).

      In cases where the file is not visible to the boot modulepath (by carefully placing it in the right directory) and you want to circumvent this check you can mark this true.

      This field is only used for updating.

      Returns:
      If this file is marked to ignore a boot conflict check.

    • getSignature

      public String getSignature()
      Returns the Base64 encoded file signature.

      This field is only used for updating.

      Returns:
      The Base64 encoded file signature.

    • getAddExports

      public List<AddPackage> getAddExports()
      Returns an unmodifiable list of packages that should be exported to a module despite not being defined so in the module-info.class file.

      This is ignored if isModulepath() returns false.

      This field is only used for launching.

      Returns:
      A list of packages to be exported to other modules.

    • getAddOpens

      public List<AddPackage> getAddOpens()
      Returns an unmodifiable list of packages that should be opened to a module despite not being defined so in the module-info.class file.

      This is ignored if isModulepath() returns false.

      This field is only used for launching.

      Returns:
      A list of packages to be opened to other modules.

    • getAddReads

      public List<String> getAddReads()
      Returns an unmodifiable list modules this module should read despite not being defined so in the module-info.class file.

      This is ignored if isModulepath() returns false.

      This field is only used for launching.

      Returns:
      A list of modules this module should read.

    • requiresUpdate

      public boolean requiresUpdate() throws IOException
      Checks if this file is out of date and requires an update.
      Returns:
      If this file requires an update.
      Throws:
      IOException - If any exception arises while reading the file content.

    • readFrom

      public static FileMetadata.Reference readFrom​(Path source)
      Construct a FileMetadata.Reference of the file at the provided location and can be used in the Builder API.

      This should point to a real file on the filesystem and cannot contain placeholders.

      Parameters:
      source - The path of the real file to which to refer in the builder.
      Returns:
      A Reference to a file to be used in the Builder API.

    • readFrom

      public static FileMetadata.Reference readFrom​(String source)
      Construct a FileMetadata.Reference of the file at the provided location and can be used in the Builder API.

      This should point to a real file on the filesystem and cannot contain placeholders.

      Parameters:
      source - The path of the real file to which to refer in the builder.
      Returns:
      A Reference to a file to be used in the Builder API.

    • streamDirectory

      public static Stream<FileMetadata.Reference> streamDirectory​(Path dir)
      Construct a stream of file FileMetadata.References from the provided directory. You can then customize individual files by using Stream.peek(Consumer), or filter out files with Stream.filter(Predicate). It will only contain files and symlinks, not directories.

      For convenience, this method also presets the path() to the file's source path relative to to streamed directory. So for the directory structure /home/a/b/c.jar, streaming /home/a would set the path to b/c.jar.
      If you wish to infer the path from the URI (as described in FileMetadata.Reference.path(String)) you must nullify it by calling path((String)null).

      This should point to a real directory on the filesystem and cannot contain placeholders.

      Parameters:
      source - The path of the real directory to stream.
      Returns:
      A Stream<Reference> of files to be used in the Builder API.

    • streamDirectory

      public static Stream<FileMetadata.Reference> streamDirectory​(String dir)
      Construct a stream of file FileMetadata.References from the provided directory. You can then customize individual files by using Stream.peek(Consumer), or filter out files with Stream.filter(Predicate). It will only contain files and symlinks, not directories.

      For convenience, this method also presets the path() to the file's source path relative to to streamed directory. So for the directory structure /home/a/b/c.jar, streaming /home/a would set the path to b/c.jar.
      If you wish to infer the path from the URI (as described in FileMetadata.Reference.path(String)) you must nullify it by calling path((String)null).

      This should point to a real directory on the filesystem and cannot contain placeholders.

      Parameters:
      source - The path of the real directory to stream.
      Returns:
      A Stream<Reference> of files to be used in the Builder API.