Package ratpack.core.server

Interface ServerConfigBuilder

    • Method Detail

      • baseDir

        ServerConfigBuilder baseDir​(Path baseDir)
        Sets the root of the filesystem for the application.

        The base dir acts as the portable file system for the application. All paths within the application, resolved by Ratpack API are resolved from this point. For example, Chain.files(Action) allows serving static files within the base dir.

        The base dir is also used to resolve paths to file system locations when using json(String), yaml(String) and props(String). This allows config files to travel with the application within the base dir.

        It is generally desirable to use the BaseDir.find() to dynamically find the base dir at runtime.

        Parameters:
        baseDir - the base dir
        Returns:
        this

      • findBaseDir

        default ServerConfigBuilder findBaseDir​(String markerFilePath)
        Sets the base dir using BaseDir.find(String).
        Parameters:
        markerFilePath - the path to the marker file on the classpath
        Returns:
        this
        Since:
        1.4

      • port

        ServerConfigBuilder port​(int port)
        Sets the port to listen for requests on.

        Defaults to 5050.

        Parameters:
        port - the port to listen for requests on
        Returns:
        this
        See Also:
        ServerConfig.getPort()

      • development

        ServerConfigBuilder development​(boolean development)
        Whether or not the application is "development".

        Default value is false.

        Parameters:
        development - Whether or not the application is "development".
        Returns:
        this
        See Also:
        ServerConfig.isDevelopment()

      • registerShutdownHook

        ServerConfigBuilder registerShutdownHook​(boolean registerShutdownHook)
        Whether or not to register a JVM shutdown hook to gracefully stop the server.

        Default value is true.

        Parameters:
        registerShutdownHook - whether to register or not
        Returns:
        this
        Since:
        1.6
        See Also:
        ServerConfig.isRegisterShutdownHook()

      • maxContentLength

        ServerConfigBuilder maxContentLength​(int maxContentLength)
        The max number of bytes a request body can be. Default value is 1048576 (1 megabyte).
        Parameters:
        maxContentLength - the max content length to accept
        Returns:
        this
        See Also:
        ServerConfig.getMaxContentLength()

      • connectQueueSize

        ServerConfigBuilder connectQueueSize​(int connectQueueSize)
        The maximum amount of connections that may be waiting to be accepted at any time.

        This is effectively the SO_BACKLOG standard socket parameter. If the queue is full (i.e. there are too many pending connections), connection attempts will be rejected. Established connections are not part of this queue so do not contribute towards the limit.

        The default value is platform specific, but usually either 200 or 128. Most application do not need to change this default.

        Parameters:
        connectQueueSize - connection queue size
        Since:
        1.5

      • ssl

        ServerConfigBuilder ssl​(io.netty.handler.ssl.SslContext sslContext)
        The SSL context to use if the application serves content over HTTPS.
        Parameters:
        sslContext - the SSL context
        Returns:
        this
        Since:
        1.5
        See Also:
        SslContextBuilder

      • ssl

        ServerConfigBuilder ssl​(io.netty.handler.ssl.SslContext sslContext,
                        Action<? super io.netty.util.DomainWildcardMappingBuilder<io.netty.handler.ssl.SslContext>> sniConfiguration)
        Configures the SSL contexts to use based on the client requested domain if the application serves content over HTTPS.

        Specifying this configuration will override the SSL context configured via ssl(SslContext).

        Domain mapping supports DNS Wildcard and will match at most one level deep.

        Parameters:
        sslContext - the default SSL context to use if no domain mapping is found.
        sniConfiguration - the SNI based SSL configuration to apply.
        Returns:
        this
        Since:
        2.0

      • ssl

        ServerConfigBuilder ssl​(io.netty.util.Mapping<String,​io.netty.handler.ssl.SslContext> sniConfiguration)
        Configures the SSL contexts to use based on the client requested domain if the application serves content over HTTPS.

        Specifying this configuration will override the SSL context configured via ssl(SslContext).

        Domain mapping supports DNS Wildcard and will match at most one level deep.

        Parameters:
        sniConfiguration - the SNI based SSL configuration to apply.
        Returns:
        this
        Since:
        2.0
        See Also:
        DomainWildcardMappingBuilder

      • env

        ServerConfigBuilder 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.

        Specified by:
        env in interface ConfigDataBuilder
        Returns:
        this

      • env

        ServerConfigBuilder 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.
        Specified by:
        env in interface ConfigDataBuilder
        Parameters:
        prefix - the prefix which should be used to identify relevant environment variables
        Returns:
        this

      • args

        ServerConfigBuilder args​(String[] args)
        Adds the given args as a config source.

        This method is designed to be used with the args var of the static main(String... args) application entry point. This allows configuration parameters to be passed to the application on the command line.

        Each arg should be of the format «key»=«value». For the following example, the application has been started with the argument thing.name=foo. 

        
 import ratpack.test.embed.EmbeddedApp;
 import static org.junit.jupiter.api.Assertions.assertEquals;

 public class Example {
   static class Thing {
     public String name;
   }

   public static void main(String... args) throws Exception {
     EmbeddedApp.of(a -> a
         .serverConfig(s -> s
             .args(args)
             .require("/thing", Thing.class)
         )
         .handlers(c -> c
             .get(ctx -> ctx.render(ctx.get(Thing.class).name))
         )
     ).test(httpClient ->
         assertEquals(httpClient.getText(), "foo")
     );
   }
 }
        Specified by:
        args in interface ConfigDataBuilder
        Parameters:
        args - the argument values
        Returns:
        this
        Since:
        1.1

      • args

        ServerConfigBuilder 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.

        Specified by:
        args in interface ConfigDataBuilder
        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
        See Also:
        args(String[])

      • props

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

      • props

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

        If a base dir is set, the path will be resolved relative to it. Otherwise, it will be resolved relative to the file system root.

        Specified by:
        props in interface ConfigDataBuilder
        Parameters:
        path - the path to the file
        Returns:
        this

      • object

        ServerConfigBuilder 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);
   }
 }
        Specified by:
        object in interface ConfigDataBuilder
        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

      • props

        ServerConfigBuilder 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());
   }
 }
        Specified by:
        props in interface ConfigDataBuilder
        Parameters:
        map - the map
        Returns:
        this

      • sysProps

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

      • env

        ServerConfigBuilder 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.
        Specified by:
        env in interface ConfigDataBuilder
        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

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

      • json

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

      • json

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

        If a base dir is set, the path will be resolved relative to it. Otherwise, it will be resolved relative to the file system root.

        Specified by:
        json in interface ConfigDataBuilder
        Parameters:
        path - the path to the file
        Returns:
        this

      • yaml

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

      • yaml

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

        If a base dir is set, the path will be resolved relative to it. Otherwise, it will be resolved relative to the file system root.

        Specified by:
        yaml in interface ConfigDataBuilder
        Parameters:
        path - the path to the file
        Returns:
        this

      • require

        default ServerConfigBuilder require​(String pointer,
                                    Class<?> type)
        Declares that it is required that the server config provide an object of the given type at the given path.

        The build() method will fail if the config is not able to provide the requested object.

        All objects declared using this method will also automatically be implicitly added to the base registry.

        The pointer argument is of the same format given to the ConfigData.get(String, Class) method. 

        
 import ratpack.test.embed.EmbeddedApp;

 import java.util.Collections;

 import static org.junit.jupiter.api.Assertions.*;

 public class Example {
   static class MyConfig {
     public String value;
   }

   public static void main(String... args) throws Exception {
     EmbeddedApp.of(a -> a
         .serverConfig(s -> s
             .props(Collections.singletonMap("config.value", "foo"))
             .require("/config", MyConfig.class)
         )
         .handlers(c -> c
             .get(ctx -> ctx.render(ctx.get(MyConfig.class).value))
         )
     ).test(httpClient ->
       assertEquals("foo", httpClient.getText())
     );
   }
 }
        Parameters:
        pointer - a JSON Pointer specifying the point in the configuration data to bind from
        type - the class of the type to bind to
        Returns:
        this

      • require

        default ServerConfigBuilder require​(String pointer,
                                    Type type)
        Declares that it is required that the server config provide an object of the given type at the given path.
        Parameters:
        pointer - a JSON Pointer specifying the point in the configuration data to bind from
        type - the type to bind to
        Returns:
        this
        Since:
        1.4

      • require

        ServerConfigBuilder require​(String pointer,
                            com.google.common.reflect.TypeToken<?> type)
        Declares that it is required that the server config provide an object of the given type at the given path.
        Parameters:
        pointer - a JSON Pointer specifying the point in the configuration data to bind from
        type - the type to bind to
        Returns:
        this
        Since:
        1.4

      • decodingErrorLevel

        ServerConfigBuilder decodingErrorLevel​(DecodingErrorLevel log)
        Configures how to emit messages associated with errors when decoding incoming requests.
        Parameters:
        log - the logging setting for failed decodings
        Returns:
        this
        Since:
        2.0
        See Also:
        ()