Module org.update4j
Package org.update4j

Class Configuration.Builder

Object
Builder
Enclosing class:
Configuration

public static class Configuration.Builder
extends Object
This class is used to generate new configurations when a new draft is released. This might be called directly in code or used in various build plugins.

In the builder process you refer to actual files on your machine, it will read the file metadata and create a new configuration. With the exceptions of FileMetadata.readFrom(String) and FileMetadata.streamDirectory(String) all string methods may take placeholder values that may refer to dynamic properties, listed properties, system properties or system environment variables.

To refer to a property my.prop with the value Hello:

 "${my.prop} World!" -> "Hello World"
 

Or, on Windows:

 "${LOCALAPPDATA}/My App" -> "C:/Users/<user-name>/AppData/Local/My App"
 

Placeholder references are resolved when build() is called.

If a string has a value that can be replaced with a property placeholder but was hardcoded, it will be replaced for you. You can control how to replace via matchAndReplace(PlaceholderMatchType) in both the config and in each individual file.

Author:
Mordechai Meisels
  • Method Details

    • baseUri

      public Configuration.Builder baseUri​(String uri)
      Set the base URI that files with a relative uri should resolve against. Files with an absolute URI will ignore this field.

      You may use a placeholder value for this field.

      If this is not set, all files must have an absolute URI.

      Parameters:
      uri - The base URI that files with a relative uri should resolve against.
      Returns:
      The builder for chaining.
    • baseUri

      public Configuration.Builder baseUri​(URI uri)
      Set the base URI that files with a relative uri should resolve against. Files with an absolute URI will ignore this field.

      This is equivalent to:

       baseUri(uri.toString())
       

      If this is not set, all files must have an absolute URI.

      Parameters:
      uri - The base URI that files with a relative uri should resolve against.
      Returns:
      The builder for chaining.
    • getBaseUri

      public String getBaseUri()
      Returns the value passed in baseUri(String).
      Returns:
      The value passed in baseUri(String).
    • basePath

      public Configuration.Builder basePath​(String path)
      Set the base path that files with a relative path should resolve against. Files with an absolute path will ignore this field.

      You may use a placeholder value for this field.

      If this is not set, all files must have an absolute path.

      Parameters:
      path - The base path that files with a relative path should resolve against.
      Returns:
      The builder for chaining.
    • basePath

      public Configuration.Builder basePath​(Path path)
      Set the base path that files with a relative path should resolve against. Files with an absolute path will ignore this field.

      This is equivalent to:

       basePath(path.toString())
       

      If this is not set, all files must have an absolute path.

      Parameters:
      path - The base path that files with a relative path should resolve against.
      Returns:
      The builder for chaining.
    • getBasePath

      public String getBasePath()
      Returns the value passed in basePath(String).
      Returns:
      The value passed in basePath(String).
    • signer

      public Configuration.Builder signer​(PrivateKey key)
      Set the private key to use for configuration and file signing. If not set, they will not be signed.
      Parameters:
      key - the PrivateKey for file signing.
      Returns:
      The builder for chaining.
    • signer

      public Configuration.Builder signer​(Path path, char[] keystorePass, String alias, char[] aliasPass)
      Convenience method to load the private key from a Java Keystore at the given path with the given keypair alias, using the keystore and alias passwords. Once loaded, it will forward the private key to signer(PrivateKey).

      It wraps all checked exceptions in a RuntimeException to keep the chaining clean.

      Parameters:
      path - The location of the keystore.
      keystorePass - The password of the keystore.
      alias - The alias of the keypair.
      aliasPass - The alias password, or null.
      Returns:
      The builder for chaining.
    • signer

      public Configuration.Builder signer​(String path, char[] keystorePass, String alias, char[] aliasPass)
      Convenience method to load the private key from a Java Keystore at the given path string with the given keypair alias, using the keystore and alias passwords. Once loaded, it will forward the private key to signer(PrivateKey).

      This method is equivalent to calling:

       signer(Paths.get(path), keystorePass, alias, aliasPass);
       

      It wraps all checked exceptions in a RuntimeException to keep the chaining clean.

      Parameters:
      path - The location of the keystore.
      keystorePass - The password of the keystore.
      alias - The alias of the keypair.
      aliasPass - The alias password, or null.
      Returns:
      The builder for chaining.
    • signer

      public Configuration.Builder signer​(char[] keystorePass, String alias, char[] aliasPass)
      Convenience method to load the private key from the Java Keystore at the default keystore location (${user.home}/.keystore) with the given keypair alias, using the keystore and alias passwords. Once loaded, it will forward the private key to signer(PrivateKey).

      It wraps all checked exceptions in a RuntimeException to keep the chaining clean.

      Parameters:
      keystorePass - The password of the keystore.
      alias - The alias of the keypair.
      aliasPass - The alias password, or null.
      Returns:
      The builder for chaining.
    • getSigner

      public PrivateKey getSigner()
      Returns the value passed in signer(PrivateKey).
      Returns:
      The value passed in signer(PrivateKey).
    • file

      public Configuration.Builder file​(FileMetadata.Reference reference)
      List a single file in the configuration. Files are listed using FileMetadata.readFrom(Path). You can customize the individual file with the value returned from readFrom().

      This method can be called repeatedly. It will add them all to a list.

      Parameters:
      reference - A file reference to list in the configuration.
      Returns:
      The builder for chaining.
    • files

      public Configuration.Builder files​(Collection<FileMetadata.Reference> refs)
      List a collection of files in the configuration.

      This method can be called repeatedly. It will add them all to a single list.

      Parameters:
      refs - A collection of file references to list in the configuration.
      Returns:
      The builder for chaining.
    • files

      public Configuration.Builder files​(Stream<FileMetadata.Reference> fileStream)
      List a stream of FileMetadata instances in the configuration. Streams can be created using FileMetadata.streamDirectory(Path) and customized using peek() or map().

      This method can be called repeatedly. It will add them all to a single list.

      Parameters:
      fileStream - A stream of file references to list in the configuration.
      Returns:
      The builder for chaining.
    • getFiles

      public List<FileMetadata.Reference> getFiles()
      Returns all files listed via file() or files().
      Returns:
      All files listed via file() or files().
    • property

      public Configuration.Builder property​(String key, String value)
      List a single property with the given key and value. The value may contain a placeholder.

      This method can be called repeatedly. It will add them all to a single list.

      Parameters:
      key - The key of the property.
      value - The value of the property.
      Returns:
      The builder for chaining.
    • property

      public Configuration.Builder property​(String key, String value, OS os)
      List a single property with the given key and value that should only resolve for the given operating system. You may have more than one property with the same key if non of them have the same os.

      The value may contain placeholders.

      This method can be called repeatedly. It will add them all to a single list.

      Parameters:
      key - The key of the property.
      value - The value of the property.
      os - The operating system to limit this property.
      Returns:
      The builder for chaining.
    • property

      public Configuration.Builder property​(Property p)
      Lists a single Property in the configuration.

      This method can be called repeatedly. It will add them all to a single list.

      Parameters:
      p - The property to list.
      Returns:
      The builder for chaining.
    • properties

      public Configuration.Builder properties​(Collection<Property> props)
      List a collection of properties in the configuration.

      This method can be called repeatedly. It will add them all to a single list.

      Parameters:
      props - The collection of properties to list.
      Returns:
      The builder for chaining.
    • getProperties

      public List<Property> getProperties()
      Returns all properties listed via property() or properties(). Changes affects the actual list.
      Returns:
      All properties listed via property() or properties().
    • dynamicProperty

      public Configuration.Builder dynamicProperty​(String key, String value)
      Register a dynamic property to the builder. A dynamic property doesn't get listed in the config, but will replace unmapped placeholders when the config is built. The Configuration.read(Reader, Map) and Configuration.parse(ConfigMapper, Map) can be used on the client side to map those properties.

      A dynamic property has higher precedence than a listed property, thus can be used to override the value of listed properties.

      The value may contain placeholders.

      This method can be called repeatedly, it will add them all to a single map. The key or value must not be null.

      Parameters:
      key - The key of the dynamic property.
      value - The value of the dynamic property.
      Returns:
      The builder for chaining.
    • dynamicProperties

      public Configuration.Builder dynamicProperties​(Map<String,​String> dynamics)
      Register a map of dynamic properties to the builder. A dynamic property doesn't get listed in the config, but will replace unmapped placeholders when the config is built. The Configuration.read(Reader, Map) and Configuration.parse(ConfigMapper, Map) can be used on the client side to map those properties.

      A dynamic property has higher precedence than a listed property, thus can be used to override the value of listed properties.

      The values may contain placeholders.

      This method can be called repeatedly, it will add them all to a single map. The key or value must not be null.

      Parameters:
      dynamics - A map of dynamic properties.
      Returns:
      The builder for chaining.
    • getDynamicProperties

      public Map<String,​String> getDynamicProperties()
      Returns the map that collects the dynamic properties. Changes will affect the actual map.
      Returns:
      The map of collected dynamic properties.
    • resolveSystemProperty

      public Configuration.Builder resolveSystemProperty​(String str)
      Hint the builder to replace the value of the given system property if a proper match is found.

      If the system property is referenced as a placeholder anywhere else in the builder, this is not needed.

      Parameters:
      str - The system property key.
      Returns:
      The builder for chaining.
    • resolveSystemProperties

      public Configuration.Builder resolveSystemProperties​(Collection<String> p)
      Hint the builder to replace the value of the given system properties if a proper match is found.

      If these system properties are referenced as placeholders anywhere else in the builder, this is not needed.

      Parameters:
      p - A collection of system property keys.
      Returns:
      The builder for chaining.
    • getSystemPropertiesToResolve

      public List<String> getSystemPropertiesToResolve()
      Returns the listed system property keys to hint the builder to look for a string that could be matched with the system property's value.

      This starts by containing the keys user.home and user.dir, you could remove them here to prevent from replacing those strings. Changes will affect the actual list.

      Returns:
      The list of system property keys to resolve for matching.
    • updateHandler

      public Configuration.Builder updateHandler​(Class<? extends UpdateHandler> clazz)
      List the given class as the update handler when Configuration.update() is called over this config.

      When explicitly listing a class in the config, it will not load the highest version of the update handler. It also relieves you from having to advertise them as required by the ServiceLoader class. Still, for modules you would want to add the provides directive, since this would add the module in the module graph and make the class visible to this framework.

      Parameters:
      clazz - The update handler class name.
      Returns:
      The builder for chaining.
    • updateHandler

      public Configuration.Builder updateHandler​(String className)
      List the given class as the update handler when Configuration.update() is called over this config.

      When explicitly listing a class in the config, it will not load the highest version of the update handler. It also relieves you from having to advertise them as required by the ServiceLoader class. Still, for modules you would want to add the provides directive, since this would add the module in the module graph and make the class visible to this framework.

      This value may contain placeholders.

      Parameters:
      clazz - The update handler class name.
      Returns:
      The builder for chaining.
    • getUpdateHandler

      public String getUpdateHandler()
      Returns the class name passed in updateHandler(String).
      Returns:
      The class name passed in updateHandler(String).
    • launcher

      public Configuration.Builder launcher​(Class<? extends Launcher> clazz)
      List the given class as the launcher when Configuration.launch() is called over this config.

      When explicitly listing a class in the config, it will not load the highest version of the launcher. It also relieves you from having to advertise them as required by the ServiceLoader class. Still, for modules you would want to add the provides directive, since this would add the module in the module graph and make the class visible to this framework.

      Parameters:
      clazz - The update handler class name.
      Returns:
      The builder for chaining.
    • launcher

      public Configuration.Builder launcher​(String className)
      List the given class as the launcher when Configuration.launch() is called over this config.

      When explicitly listing a class in the config, it will not load the highest version of the launcher. It also relieves you from having to advertise them as required by the ServiceLoader class. Still, for modules you would want to add the provides directive, since this would add the module in the module graph and make the class visible to this framework.

      This value may contain placeholders.

      Parameters:
      clazz - The update handler class name.
      Returns:
      The builder for chaining.
    • getLauncher

      public String getLauncher()
      Returns the class name passed in updateHandler(String).
      Returns:
      The class name passed in updateHandler(String).
    • matchAndReplace

      public Configuration.Builder matchAndReplace​(PlaceholderMatchType matcher)
      Attempt to replace strings with listed or system property placeholders according to the given policy. By default, or if you use null, it will use PlaceholderMatchType.WHOLE_WORD.
      Parameters:
      matcher - The match type to be used when implying placeholders.
      Returns:
      The builder for chaining.
    • getMatchType

      public PlaceholderMatchType getMatchType()
      Returns the policy passed in matchAndReplace(PlaceholderMatchType). It will never return null but instead PlaceholderMatchType.WHOLE_WORD.
      Returns:
      The match policy.
    • build

      public Configuration build()
      Collects all information passed to the builder, replaces matches with placeholder according to the getMatchType() policy and validates all values.
      Returns:
      A built Configuration according to the passed information.