| <!-- |
| /*************************************************************************************************************************** |
| * 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>@RestResource</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-svl juneau-svl}. |
| </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>@RestResource</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.RestResource @RestResource}. |
| <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> |
