Interface ConfigDataBuilder

  • All Known Subinterfaces:
    ServerConfigBuilder

    public interface ConfigDataBuilder
    Configures how configuration data will be loaded and bound to objects.

    Multiple data sources can be specified. All specified data sources will be merged together to form the final configuration data. If a given value exists in multiple data sources, the value from the last specified source will be used.

    By default, if loading a data source fails, the exception will be thrown. If desired, this behavior can be adjusted using onError(Action). For example:

    
     import java.nio.file.Files;
     import java.nio.file.Path;
     import ratpack.func.Action;
     import ratpack.core.server.RatpackServer;
     import ratpack.core.server.ServerConfig;
     import ratpack.test.ServerBackedApplicationUnderTest;
     import ratpack.test.http.TestHttpClient;
    
     import static org.junit.jupiter.api.Assertions.*;
    
     public class Example {
       public static void main(String[] args) throws Exception {
         Path jsonFile = Files.createTempFile("optionalConfig", ".json");
         Files.delete(jsonFile);
         Path yamlFile = Files.createTempFile("mandatoryConfig", ".yaml");
         try {
           Files.write(yamlFile, "server:\n  threads: 7\n  port: 0".getBytes());
           RatpackServer server = RatpackServer.of(spec -> {
             ServerConfig serverConfig = ServerConfig
               .embedded()
               .onError(Action.noop()).json(jsonFile)
               .onError(Action.throwException()).yaml(yamlFile)
               .build();
             spec
               .serverConfig(serverConfig)
               .handler(registry ->
                 ctx -> ctx.render("threads:" + ctx.get(ServerConfig.class).getThreads())
               );
           });
           server.start();
    
           TestHttpClient httpClient = ServerBackedApplicationUnderTest.of(server).getHttpClient();
           assertEquals("threads:7", httpClient.getText());
    
           server.stop();
         } finally {
           Files.delete(yamlFile);
         }
       }
     }
     
    See Also:
    ConfigData.builder()
    • Method Detail

      • build

        ConfigData build()
        Creates the config data, based on the state of this builder.
        Returns:
        a new config data
      • configureObjectMapper

        ConfigDataBuilder configureObjectMapper​(Action<ObjectMapper> action)
        Configures the object mapper used for binding configuration data to arbitrary objects.
        Parameters:
        action - an action to perform upon the object mapper
        Returns:
        this
      • add

        ConfigDataBuilder add​(ConfigSource configSource)
        Adds a configuration source.
        Parameters:
        configSource - the configuration source to add
        Returns:
        this
      • env

        ConfigDataBuilder env()
        Adds a configuration source for environment variables starting with the prefix "RATPACK_".

        The prefix will be removed before loading the data. The environment variable name is split into per-object segments using double underscore as an object boundary. Segments are transformed into camel-case field names using a single underscore as a word boundary.

        Returns:
        this
      • env

        ConfigDataBuilder env​(String prefix)
        Adds a configuration source for environment variables starting with the specified prefix. The prefix will be removed before loading the data. The environment variable name is split into per-object segments using double underscore as an object boundary. Segments are transformed into camel-case field names using a single underscore as a word boundary.
        Parameters:
        prefix - the prefix which should be used to identify relevant environment variables
        Returns:
        this
      • env

        ConfigDataBuilder env​(String prefix,
                              Function<String,​String> mapFunc)
        Adds a configuration source for environment variables starting with the specified prefix. The prefix will be removed before loading the data. The environment variable name is split into per-object segments using double underscore as an object boundary. Segments are transformed into field names using the specified transformation function rather than the default function.
        Parameters:
        prefix - the prefix which should be used to identify relevant environment variables
        mapFunc - the function to transform segments into field names
        Returns:
        this
      • env

        ConfigDataBuilder env​(EnvironmentParser environmentParser)
        Adds a configuration source for environment variables using custom parsing logic.
        Parameters:
        environmentParser - the parser to use to interpret environment variables
        Returns:
        this
      • args

        default ConfigDataBuilder args​(String prefix,
                                       String separator,
                                       String[] args)
        Adds a configuration source for the given string args.

        Args that do not start with the given prefix are ignored. The remaining are each split using the given separator (as a literal string, not as a regex), then trimmed of the prefix.

        Parameters:
        prefix - the prefix that each arg must have to be considered (use null or "" for no prefix)
        separator - the separator between the key and the value
        args - the argument values
        Returns:
        this
        Since:
        1.1
      • json

        ConfigDataBuilder json​(com.google.common.io.ByteSource byteSource)
        Adds a configuration source for a JSON file.
        Parameters:
        byteSource - the source of the JSON data
        Returns:
        this
      • json

        ConfigDataBuilder json​(Path path)
        Adds a configuration source for a JSON file.
        Parameters:
        path - the source of the JSON data
        Returns:
        this
      • json

        ConfigDataBuilder json​(String path)
        Adds the JSON file at the given path as a configuration source.

        The default implementation of ConfigDataBuilder will resolve the given path relative to the actual file system root.

        Parameters:
        path - the path to the source of the JSON data
        Returns:
        this
      • json

        ConfigDataBuilder json​(URL url)
        Adds a configuration source for a JSON file.
        Parameters:
        url - the source of the JSON data
        Returns:
        this
      • props

        ConfigDataBuilder props​(com.google.common.io.ByteSource byteSource)
        Adds a configuration source for a properties file.
        Parameters:
        byteSource - the source of the properties data
        Returns:
        this
      • props

        ConfigDataBuilder props​(Path path)
        Adds a configuration source for a properties file.
        Parameters:
        path - the source of the properties data
        Returns:
        this
      • props

        ConfigDataBuilder props​(Properties properties)
        Adds a configuration source for a properties object.
        Parameters:
        properties - the properties object
        Returns:
        this
      • props

        ConfigDataBuilder props​(Map<String,​String> map)
        Adds a configuration source for a Map (flat key-value pairs). This signature is particularly useful for providing default values as shown below:
        
         import com.google.common.collect.ImmutableMap;
         import ratpack.config.ConfigData;
         import ratpack.core.server.ServerConfig;
         import static org.junit.jupiter.api.Assertions.*;
        
         public class Example {
           public static void main(String[] args) throws Exception {
             ServerConfig serverConfig = ServerConfig
               .builder()
               .props(ImmutableMap.of("server.port", "5060"))
               .sysProps()
               .build();
             assertEquals(5060, serverConfig.getPort());
           }
         }
         
        Parameters:
        map - the map
        Returns:
        this
      • props

        ConfigDataBuilder props​(String path)
        Adds the properties file at the given path as a configuration source.

        The default implementation of ConfigDataBuilder will resolve the given path relative to the actual file system root.

        Parameters:
        path - the path to the source of the properties data
        Returns:
        this
      • props

        ConfigDataBuilder props​(URL url)
        Adds a configuration source for a properties file.
        Parameters:
        url - the source of the properties data
        Returns:
        this
      • sysProps

        ConfigDataBuilder sysProps()
        Adds a configuration source for system properties starting with the prefix "ratpack.".
        Returns:
        this
      • sysProps

        ConfigDataBuilder sysProps​(String prefix)
        Adds a configuration source for system properties starting with the specified prefix.
        Parameters:
        prefix - the prefix which should be used to identify relevant system properties; the prefix will be removed before loading the data
        Returns:
        this
      • yaml

        ConfigDataBuilder yaml​(com.google.common.io.ByteSource byteSource)
        Adds a configuration source for a YAML file.
        Parameters:
        byteSource - the source of the YAML data
        Returns:
        this
      • yaml

        ConfigDataBuilder yaml​(Path path)
        Adds a configuration source for a YAML file.
        Parameters:
        path - the source of the YAML data
        Returns:
        this
      • yaml

        ConfigDataBuilder yaml​(String path)
        Adds the YAML file at the given path as a configuration source.

        The default implementation of ConfigDataBuilder will resolve the given path relative to the actual file system root.

        Parameters:
        path - the path to the source of the YAML data
        Returns:
        this
      • yaml

        ConfigDataBuilder yaml​(URL url)
        Adds a configuration source for a YAML file.
        Parameters:
        url - the source of the YAML data
        Returns:
        this
      • object

        ConfigDataBuilder object​(String path,
                                 Object object)
        Adds the object's fields at the given path as a configuration source.

        The path is a period separated key string. The given object is subject to value merging and overrides as per other config sources.

        
         import ratpack.config.ConfigData;
         import java.util.Collections;
         import static org.junit.jupiter.api.Assertions.assertEquals;
        
         public class Example {
        
           static class Thing {
             public String f1;
             public String f2;
             public String f3;
           }
        
           public static void main(String... args) throws Exception {
             Thing input = new Thing();
             input.f1 = "1";
             input.f2 = "2";
        
             ConfigData configData = ConfigData.of(c -> c
               .object("thing", input)
               .props(Collections.singletonMap("thing.f1", "changed"))
               .object("thing.f3", "changed")
             );
             Thing thing = configData.get("/thing", Thing.class);
        
             assertEquals("changed", thing.f1);
             assertEquals("2", thing.f2);
             assertEquals("changed", thing.f3);
           }
         }
         
        Parameters:
        path - the configuration path the object's fields should be mapped on to
        object - the object from which to derive the configuration fields
        Returns:
        this
        Since:
        1.4
      • onError

        ConfigDataBuilder onError​(Action<? super Throwable> errorHandler)
        Sets the error all that will be used for added configuration sources. The error all only applies to configuration sources added after this method is called; it is not applied retroactively.
        Parameters:
        errorHandler - the error all
        Returns:
        this
        See Also:
        Action.noop(), Action.throwException()
      • getObjectMapper

        ObjectMapper getObjectMapper()
        Returns the object mapper used for configuration binding.
        Returns:
        the object mapper
      • getConfigSources

        com.google.common.collect.ImmutableList<ConfigSource> getConfigSources()
        Returns the config sources used for configuration binding.

        Add sources via add(ConfigSource).

        Returns:
        the config sources