Skip to main content

REST Server SVL Variables

For the Var API itself, see SVL Variables.

When to use it​

In the previous examples, there were several cases where embedded variables were contained within annotation values:

@Rest(
    title="${L:my.label}"
)

Variables take the form ${X:contents} where X can consist of zero or more ASCII characters and contents can be virtually anything. This is called Simple Variable Language, or SVL, and is defined here: Simple Variable Language.

Features​

  • Variables can be nested arbitrarily deep (e.g.

${X:${Y:foo}}).

  • Variables can contain arguments (e.g.

${L:my.label:arg1:arg2}).

  • Variables are recursively resolved. 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 variables that involve user input).

There are two distinct groups of variables:

  • Initialization-time variables: These are variables that can be used in many of the annotations in @Rest. The RestContext.getVarResolver() method returns initialization-time variables only.
  • Request-time variables: These are variables that are available during HTTP-requests and can be used on annotation such as @HtmlDoc. RestRequest.getVarResolverSession() method returns initialization and request-time variables.

The following is the default list of supported variables:

Default REST SVL Variables​

ModuleClassPatternInitialization timeRequest timeExamples
juneau-svlEnvVariablesVar${E:key[:default]}yesyes${E:PATH}
SystemPropertiesVar${S:key[:default]}yesyes${S:java.home}
EnvFileVar${EF:key[:default]}yesyes${EF:MY_KEY:default}
DotenvVar${DE:key[:default]}yesyes${DE:MY_KEY:default}
ArgsVar${A:key[:default]}yesyes${A:foo:null}
ManifestFileVar${MF:key[:default]}yesyes${MF:Main-Class}
juneau-configConfigVar${C:key[:default]}yesyes${C:REST/staticFiles}
juneau-rest-serverFileVar${F:path[:default]}yesyes${F:resources/MyAsideMessage.html: Oops not found!}
ServletInitParamVar${I:name[:default]}yesyes${I:my.param}
LocalizationVar${L:key[:args...]}noyes${L:MyMessage:foo:bar}
RequestAttributeVar${RA:key1[:key2...]}noyes${RA:attrName}
RequestFormDataVar${RF:key1[:key2...]}noyes${RF:paramName}
RequestHeaderVar${RH:key1[:key2...]}noyes${RH:Header-Name}
RequestPathVar${RP:key1[:key2...]}noyes${RP:pathVar}
RequestQueryVar${RQ:key1[:key2...]}noyes${RQ:paramName}
RequestSwaggerVar${RS:key}noyes${RS:title}
RequestVar${R:key1[:key2...]}noyes${R:contextPath}
SerializedRequestAttrVar${SA:contentType,key[,default]}noyes${SA:application/json,${RA:foo}}
UrlVar${U:uri}noyes${U:servlet:/foo}
UrlEncodeVar${UE:uriPart}yesyes${U:servlet:/foo?bar=${UE:${RA:bar}}}
Widget${W:name}noyes${W:MenuItemWidget}

Transformation/conditional logic that used to be a dedicated Var class ($UC{}, $IF{}, $SW{}, $PM{}, $PR{}, $PE{}, $NE{}, $CO{}, $LN{}, $ST{}, $LC{}) is now expressed via the #{name('args')} function-call syntax introduced in 10.0.0. See Simple Variable Language — #{...} function-call syntax and the 10.0.0 release notes for the migration table.

Custom variables can be defined by supplying a named varResolver bean via @Bean.

Example
import org.apache.juneau.commons.inject.Bean;

// Defined a variable that simply wraps all strings inside [] brackets.
// e.g. "$BRACKET{foobar}" -> "[foobar]"
public class BracketVar extends SimpleVar {

    public BracketVar() {
        super("BRACKET");
    }

    @Override /* Var */
    public String resolve(VarResolverSession session, String arg) {
        return '[' + arg + ']';
    }
}

// Register it with our resource.
@Rest(...)
public class MyResource extends BasicRestResource {

    @Bean(name="varResolver")
    public static VarResolver varResolver(VarResolver.Builder b) {
        return b.vars(BracketVar.class).build();
    }
}

For framework-managed types the resource has a single per-context instance; the bean name is an alias for it, and the bean is not inherited by @Rest(children).

The methods involved with variables are:

RestContextgetVarResolver()RestRequestgetVarResolverSession()

See also​