Configuration Files

The Server API provides methods for associating configuration files with REST servlets so that configuration properties can be defined in external files.

It uses the following annotation:

Restconfig

Example

@Rest(
    // Config file is located at ./config_dir/myconfig.cfg
    config="config_dir/myconfig.cfg",
    ...
)
public class MyResource {...}

In recap, the Configuration API provides support for INI-style configuration files with embedded string variables:

Example

#--------------------------
# Examples
#--------------------------
[MyProperties]
path = $E{PATH}
javaHome = $S{java.home}
customMessage = Java home is $C{MyProperties/javaHome} and the
    environment path is $C{MyProperties/path}.

These properties are then accessible through the Config class.

@RestGet("/")
public String sample(Config config) {
    String path = config.get("MyProperties/path").get();
    File javaHome = config.get("MyProperties/javaHome").as(File.class).orElse(null);
    String customMessage = config.get("MyProperties/customMessage").orElse("Hello");
    ...
}

The annotation itself can contain string variables.

For example, the Microservice API BasicRestServlet class defines the location of the config file as a system property juneau.configFile:

@Rest(
    // Config file location is defined as a system property
    config="$S{juneau.configFile}",
    ...
)
public class MyResource {...}

Spring Boot applications typically define an application.properties file. You can reuse it as a config file like so:

@Rest(
    config="application.properties",
    ...
)
public class MyResource {...}

Note that properties files are a subset of functionality of INI files (they're basically just INI files with a single default section). It's therefore possible to use INI-style syntax such as sections in your application.properties file.

Once a config file has been associated with a REST resource, it can be accessed through the RestContext.Builder.config() method. It can also be accessed by passing in a Config bean to any of your REST OP methods.

A common usage is to use this method to initialize fields in your servlet.

@Rest(
    // Config file is located at ./config_dir/myconfig.cfg
    config="config_dir/myconfig.cfg",
    ...
)
public class MyResource {
    private final String path;
    private final File javaHome;

    public MyResource(RestContext.Builder builder) {
        Config config = builder.getConfig();
        path = config.get("MyProperties/path").orElse("mypath");
        javaHome = config.get("MyProperties/javaHome").as(File.class).orElse(null);
    }

Another common usage is to refer to config properties through $C variables in your annotations:

@Rest
// Get stylesheet from myconfig.cfg but default to devops.css if it's not specified
@HtmlDoc(
    stylesheet="$C{MyServlet/stylesheet,servlet:/styles/devops.css}",
)
public class MyResource {...}

It's even possible to reference request-level variables in your config file if you use RestRequest.getConfig() to access the config file:

#-------------------------------------
# Contents of config_dir/myconfig.cfg
#-------------------------------------
[HelloWorldResource]
message = Hello $RQ{person}!

/**
* Sample REST resource that prints out a simple "Hello world!" message.
*/
@Rest(
    config="config_dir/myconfig.cfg",
    ...
)
public class HelloWorldResource extends BasicRestServlet {

    /**
    * GET request handler.
    * Specify the GET parameter "?person=X" for a specialized message!
    */
    @RestGet("/")
    public String sayHello(Config config) {
        return config.get("HelloWorldResource/message").get();
    }
}

You can even add resource bundles into the mix:

#-------------------------------------
# Contents of config_dir/myconfig.cfg
#-------------------------------------
[HelloWorldResource]
message = $L{localizedMessage,$RQ{person}}

#-------------------------------------------
# Contents of HelloWorldResource.properties
#-------------------------------------------
localizedMessage = Hello {0}!

/**
* Sample REST resource that prints out a simple "Hello world!" message.
*/
@Rest(
    messages="HelloWorldResources",
    config="config_dir/myconfig.cfg",
    ...
)
public class HelloWorldResource extends BasicRestServlet {

    /**
    * GET request handler.
    * Specify the GET parameter "?person=X" for a specialized message!
    */
    @RestGet("/")
    public String sayHello(Config config) {
        return config.get("HelloWorldResource/message").get();
    }
}

See Also

juneau-config