juneau-doc/docs/Topics/07.juneau-rest-server/25.ConfigurationFiles.html

<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

Configuration Files

<p>
	The Server API provides methods for associating configuration files with REST servlets so that 
	configuration properties can be defined in external files.
</p>
<p>
	In recap, the Configuration API provides support for INI-style configuration files with embedded string variables:
</p>

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<cc>#--------------------------</cc>
	<cc># Examples </cc>
	<cc>#--------------------------</cc>
	<cs>[MyProperties]</cs>
	<ck>path</ck> = <cv>$E{PATH}</cv>
	<ck>javaHome</ck> = <cv>$S{java.home}</cv>
	<ck>customMessage</ck> = <cv>Java home is $C{MyProperties/javaHome} and the environment path is $C{MyProperties/path}.</cv>
</p>
<p>
	These properties are then accessible through the {@link oaj.config.Config} class.
</p>
<p class='bpcode w800'>
	Config c = Config.<jsm>create</jsm>(<js>"myconfig.cfg"</js>).build();
	String path = c.getString(<js>"MyProperties/path"</js>);
	File javaHome = c.getObject(<js>"MyProperties/javaHome"</js>, File.<jk>class</jk>);
	String customMessage = c.getString(<js>"MyProperties/customMessage"</js>);
</p>
<p>
	Configuration files are associated with REST resources through the following:
</p>
<ul class='javatree'>
	<li class='ja'>{@link oajr.annotation.RestResource#config() RestResource(config)}
</ul>

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@RestResource</ja>(
		<jc>// Config file is located at ./config_dir/myconfig.cfg</jc>
		config=<js>"config_dir/myconfig.cfg"</js>,
		...
	)
	<jk>public class</jk> MyResource {...}
</p>
<p>
	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 <l>"juneau.configFile"</l>:
</p>
<p class='bpcode w800'>
	<ja>@RestResource</ja>(
		<jc>// Config file location is defined as a system property</jc>
		config=<js>"$S{juneau.configFile}"</js>,
		...
	)
	<jk>public class</jk> MyResource {...}
</p>
<p>
	Once a config file has been associated with a REST resource, it can be accessed through the 
	{@link oajr.RestContextBuilder#getConfig()} method.
</p>
<p>
	A common usage is to use this method to initialize fields in your servlet.
</p>
<p class='bpcode w800'>
	<ja>@RestResource</ja>(
		<jc>// Config file is located at ./config_dir/myconfig.cfg</jc>
		config=<js>"config_dir/myconfig.cfg"</js>,
		...
	)
	<jk>public class</jk> MyResource  {
		<jk>private final</jk> String <jf>path</jf>;
		<jk>private final</jk> File <jf>javaHome</jf>;
	
		<jk>public</jk> MyResource(RestContextBuilder builder) {
			Config c = builder.getConfig();
			<jf>path</jf> = c.getString(<js>"MyProperties/path"</js>);
			<jf>javaHome</jf> = c.getObject(File.<jk>class</jk>, <js>"MyProperties/javaHome"</js>);
		}
</p>
<p>
	Another common usage is to refer to config properties through <ck>$C</ck> variables in your annotations:
</p>
<p class='bpcode w800'>
	<ja>@RestResource</ja>(
		<jc>// Get stylesheet from myconfig.cfg, but default to devops.css if it's not specified</jc>
		htmldoc=<ja>@HtmlDoc</ja>(
			stylesheet=<js>"$C{MyServlet/stylesheet,servlet:/styles/devops.css}"</js>,
		)
		...
	)
	<jk>public class</jk> MyResource {...}
</p>
<p>
	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:
</p>
<p class='bpcode w800'>
	<cc>#-------------------------------------</cc>
	<cc># Contents of config_dir/myconfig.cfg </cc>
	<cc>#-------------------------------------</cc>
	<cs>[HelloWorldResource]</cs>
	<ck>message</ck> = <cv>Hello $RQ{person}!</cv>
</p>
<p class='bpcode w800'>
	<jd>/** 
	 * Sample REST resource that prints out a simple "Hello world!" message.
	 */</jd>
	 <ja>@RestResource</ja>(
	 	config=<js>"config_dir/myconfig.cfg"</js>,
	 	...
	 )
 	<jk>public class</jk> HelloWorldResource <jk>extends</jk> BasicRestServlet {
		
		<jd>/** 
		 * GET request handler.
		 * Specify the GET parameter "?person=X" for a specialized message! 
		 */</jd>
		<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>)
		<jk>public</jk> String sayHello(RestRequest req) {
			<jk>return</jk> req.getConfig().getString(<js>"HelloWorldResource/message"</js>);
		}
	}
</p>
<p>
	You can even add resource bundles into the mix:
</p>
<p class='bpcode w800'>
	<cc>#-------------------------------------</cc>
	<cc># Contents of config_dir/myconfig.cfg </cc>
	<cc>#-------------------------------------</cc>
	<cs>[HelloWorldResource]</cs>
	<ck>message</ck> = <cv>$L{localizedMessage,$RQ{person}}</cv>
</p>
<p class='bpcode w800'>
	<cc>#-------------------------------------------</cc>
	<cc># Contents of HelloWorldResource.properties </cc>
	<cc>#-------------------------------------------</cc>
	<ck>localizedMessage</ck> = <cv>Hello {0}!</cv>
</p>
<p class='bpcode w800'>
	<jd>/** 
	 * Sample REST resource that prints out a simple "Hello world!" message.
	 */</jd>
	 <ja>@RestResource</ja>(
	 	messages=<js>"HelloWorldResources"</js>,
	 	config=<js>"config_dir/myconfig.cfg"</js>,
	 	...
	 )
 	<jk>public class</jk> HelloWorldResource <jk>extends</jk> BasicRestServlet {
		
		<jd>/** 
		 * GET request handler.
		 * Specify the GET parameter "?person=X" for a specialized message! 
		 */</jd>
		<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>)
		<jk>public</jk> String sayHello(RestRequest req) {
			<jk>return</jk> req.getConfig().getString(<js>"HelloWorldResource/message"</js>);
		}
	}
</p>

<ul class='seealso'>
	<li>{@doc juneau-config}
</ul>