{title:'Configuration Files', updated:'9.0.0'}

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:

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

##### 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 {@link oaj.config.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 {@link oajr.servlet.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 one of the following: {@link oajr.RestContext.Builder#getConfig()} method. It can also be access by passing in a {@link oaj.config.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 {@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 implements BasicUniversalConfig { | | /** | * 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 implements BasicUniversalConfig { | | /** | * 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(); | } | }

- {@doc juneau-config}