<!--
/***************************************************************************************************************************
 * 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.
 ***************************************************************************************************************************/
 -->

SVL Variables

<p>	
	In the previous examples, there were several cases where embedded variables were contained within
	annotation values:
</p>
<p class='bpcode w800'>
	<ja>@Rest</ja>(
		title=<js>"$L{my.label}"</js>
    )
</p>
<p>
	Variables take the form <l>$X{contents}</l> where <l>X</l> can consist of zero or more ASCII characters and <l>contents</l> can be virtually anything.
	This is called Simple Variable Language, or SVL, and is defined here: {@doc juneau-marshall.SimpleVariableLanguage Simple Variable Language}.
</p>
<h5 class='topic'>Features</h5>
<ul class='spaced-list'>
	<li>
		Variables can be nested arbitrarily deep (e.g. <l>"$X{$Y{foo}}"</l>).
	<li>
		Variables can contain arguments (e.g. <l>"$L{my.label,arg1,arg2}"</l>).
	<li>
		Variables are recursively resolved. 
		<br>i.e., if a variable results to a value with another variable in it, that variable will also be 
		resolved (restricted for security reasons on some variables).
</ul>
<p>
	Variables are configured on resources via the following API:
</p>
<ul class='javatree'>
	<li class='jm'>{@link oajr.RestContextBuilder#vars(Class[])}
</ul>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<jc>// Defined a variable that simply wrapps all strings inside [] brackets.</jc>
	<jc>// e.g. "$BRACKET{foobar}" -> "[foobar]"</jc>
	<jk>public class</jk> BracketVar <jk>extends</jk> SimpleVar {
		
		<jk>public</jk> BracketVar() {
			<jk>super</jk>(<js>"BRACKET"</js>);
		}
			
		<ja>@Override</ja> <jc>/* Var */</jc>
		<jk>public</jk> String resolve(VarResolverSession session, String arg) {
			<jk>return</jk> <js>'['</js> + arg + <js>']'</js>;
		}
	}

	<jc>// Register it with our resource.</jc>
	<ja>@Rest</ja>(...)
	<jk>public class</jk> MyResource {
	
		<jk>public</jk> MyResource(RestContextBuilder builder) {
			builder.vars(BracketVar.<jk>class</jk>);
		}
	}
</p>
<p>
	The methods involved with variables are:
</p>
<ul class='javatree'>
	<li class='jm'>{@link oajr.RestContext#getVarResolver()}
	<li class='jm'>{@link oajr.RestRequest#getVarResolverSession()}
	<li class='jm'>{@link oajr.RestRequest#getClasspathReaderResource(String,boolean)}
</ul>
<p>
	There are two distinct groups of variables:
</p>
<ul class='spaced-list'>
	<li><l>Initialization-time variables</l>
		<br>These are variables that can be used in many of the annotations in {@link oajr.annotation.Rest @Rest}. 
		<br>The {@link oajr.RestContext#getVarResolver()} method returns initialization-time variables only.
	<li><l>Request-time variables</l>
		<br>These are variables that are available during HTTP-requests and can be used on annotation such as {@link oajr.annotation.HtmlDoc @HtmlDoc}. 
		<br>{@link oajr.RestRequest#getVarResolverSession()} method returns initialization and request-time variables.
</ul>
<p>
	The following is the default list of supported variables.
</p>
<h5 class='figure'><a href='#DefaultRestSvlVariables' id='DefaultRestSvlVariables'>Default REST SVL Variables:</a></h5>
<table class='styled w800'>
	<tr>
		<th>Module</th><th>Class</th><th>Pattern</th><th>Initialization<br>time</th><th>Request<br>time</th><th>Examples</th>
	</tr>
	<tr class='dark'>
		<td rowspan='11' style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-svl</td>
		<td>{@link oaj.svl.vars.EnvVariablesVar}</td>
		<td class='code'>$E{key[,default]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$E{PATH}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.SystemPropertiesVar}</td>
		<td class='code'>$S{key[,default]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$S{java.home}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.ArgsVar}</td>
		<td class='code'>$A{key[,default]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$A{foo,null}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.ManifestFileVar}</td>
		<td class='code'>$MF{key[,default]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$MF{Main-Class}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.IfVar}</td>
		<td class='code'>$IF{arg,then[,else]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$IF{$S{my.boolean.property},foo,bar}</td>
	</tr>
	<tr class='dark dd'>
		<td>{@link oaj.svl.vars.SwitchVar}</td>
		<td class='code'>$SW{arg,p1:then1[,p2:then2...]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$SW{$P{os.name},*win*:Windows,*:Something else}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.CoalesceVar}</td>
		<td class='code'>$CO{arg1[,arg2...]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$CO{$S{my.property},$E{my.property},n/a}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.PatternMatchVar}</td>
		<td class='code'>$PM{arg,pattern}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$PM{$P{os.name},*win*}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.NotEmptyVar}</td>
		<td class='code'>$NE{arg}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$NE{$S{foo}}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.UpperCaseVar}</td>
		<td class='code'>$UC{arg}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$UC{$S{foo}}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oaj.svl.vars.LowerCaseVar}</td>
		<td class='code'>$LC{arg}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$LC{$S{foo}}</td>
	</tr>
	<tr class='light dd'>
		<td rowspan='1' style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-config</td>
		<td>{@link oaj.config.vars.ConfigVar}</td>
		<td class='code'>$C{key[,default]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$C{REST/staticFiles}</td>
	</tr>
	<tr class='dark'>
		<td rowspan='14' style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-rest-server</td>
		<td>{@link oajr.vars.FileVar}</td>
		<td class='code'>$F{path[,default]}}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$F{resources/MyAsideMessage.html, Oops not found!}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.ServletInitParamVar}</td>
		<td class='code'>$I{name[,default]}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$I{my.param}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.LocalizationVar}</td>
		<td class='code'>$L{key[,args...]}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$L{MyMessage,foo,bar}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.RequestAttributeVar}</td>
		<td class='code'>$RA{key1[,key2...]}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$RA{attrName}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.RequestFormDataVar}</td>
		<td class='code'>$RF{key1[,key2...]}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$RF{paramName}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.RequestHeaderVar}</td>
		<td class='code'>$RH{key1[,key2...]}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$RH{Header-Name}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.RequestPathVar}</td>
		<td class='code'>$RP{key1[,key2...]}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$RP{pathVAr}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.RequestQueryVar}</td>
		<td class='code'>$RQ{key1[,key2...]}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$RQ{paramName}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.RequestVar}</td>
		<td class='code'>$R{key1[,key2...]}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$R{contextPath}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.RestInfoVar}</td>
		<td class='code'>$RI{key}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$RI{externalDocs}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.SerializedRequestAttrVar}</td>
		<td class='code'>$SA{contentType,key[,default]}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$SA{application/json,$RA{foo}}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.UrlVar}</td>
		<td class='code'>$U{uri}></td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$U{servlet:/foo}</td>
	</tr>
	<tr class='dark'>
		<td>{@link oajr.vars.UrlEncodeVar}</td>
		<td class='code'>$UE{uriPart}</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$U{servlet:/foo?bar=$UE{$RA{bar}}</td>
	</tr>
	<tr class='dark dd'>
		<td>{@link oajr.vars.WidgetVar}</td>
		<td class='code'>$W{name}</td>
		<td style='text-align:center;font-weight:bold'>no</td>
		<td style='text-align:center;font-weight:bold'>yes</td>
		<td class='code'>$W{MenuItemWidget}</td>
	</tr>
</table>