Configuration Files

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

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 {@link oaj.config.Config} class.

Config c = Config.create("myconfig.cfg").build(); String path = c.getString("MyProperties/path"); File javaHome = c.getObject("MyProperties/javaHome", File.class); String customMessage = c.getString("MyProperties/customMessage");

Configuration files are associated with REST resources through the following:

- {@link oajr.annotation.Rest#config() Rest(config)}

##### Example:

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

The annotation itself can contain string variables. For example, the Microservice API {@link oajr.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 {...}

Once a config file has been associated with a REST resource, it can be accessed through the {@link oajr.RestContextBuilder#getConfig()} method.

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(RestContextBuilder builder) { Config c = builder.getConfig(); path = c.getString("MyProperties/path"); javaHome = c.getObject(File.class, "MyProperties/javaHome"); }

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=@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 {@link oajr.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! */ @RestMethod(name=GET, path="/") public String sayHello(RestRequest req) { return req.getConfig().getString("HelloWorldResource/message"); } }

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! */ @RestMethod(name=GET, path="/") public String sayHello(RestRequest req) { return req.getConfig().getString("HelloWorldResource/message"); } }

- {@doc juneau-config}