Package org.apache.juneau.commons.svl

Class Var

java.lang.Object
org.apache.juneau.commons.svl.Var
Direct Known Subclasses:
SimpleVar, StreamedVar, XVar
public abstract class Var extends Object
Abstract superclass of all Simple Var Language variables.

Vars are used to convert simple variables of the form "$varName{varKey}" into something else by the VarResolver class.

Subclasses must implement one of the following two methods:

Subclasses MUST implement a no-arg constructor so that class names can be passed to the VarResolver.Builder.vars(Class...) method.
They must also be thread safe!

Two direct abstract subclasses are provided to differentiated between simple and streamed vars:

See Also:

  • Constructor Details

  • Method Details

    • resolve

      public abstract String resolve(VarResolverSession session, String arg) throws Exception
      The interface that needs to be implemented for subclasses of SimpleVar.
      Parameters:
      session - The session object used for a single instance of a var resolution.
      arg - The inside argument of the variable.
      Returns:
      The resolved value.
      Throws:
      Exception - Any exception can be thrown.

    • resolveTo

      public abstract void resolveTo(VarResolverSession session, Writer w, String arg) throws Exception
      The interface that needs to be implemented for subclasses of StreamedVar.
      Parameters:
      session - The session object used for a single instance of a var resolution.
      w - The writer to send the resolved value to.
      arg - The inside argument of the variable.
      Throws:
      Exception - Any exception can be thrown.

    • allowNested

      protected boolean allowNested()
      Returns whether nested variables are supported by this variable.

      For example, in "$X{$Y{xxx}}", $Y is a nested variable that will be resolved if this method returns true.

      The default implementation of this method always returns true. Subclasses can override this method to override the default behavior.

      Returns:
      true if nested variables are supported by this variable.

    • allowRecurse

      protected boolean allowRecurse()
      Returns whether variables in the resolved contents of this variable should also be resolved.

      For example, if "$X{xxx}" resolves to "$Y{xxx}", then the $Y variable will be recursively resolved if this method returns true.

      The default implementation of this method always returns true.
      Subclasses can override this method to override the default behavior.

      As a general rule, variables that resolve user-entered data should not be recursively resolved as this may cause a security hole.
      Returns:
      true if resolved variables should be recursively resolved.

    • canResolve

      protected boolean canResolve(VarResolverSession session)
      Returns true if this variable can be resolved in the specified session.

      For example, some variable cannot resolve unless specific context or session objects are available.

      Parameters:
      session - The current session.
      Returns:
      true if this variable can be resolved in the specified session.

    • isStable

      protected boolean isStable()
      Returns true if this variable's resolved value is stable for the lifetime of the resolver — same body produces the same output regardless of when (or in what session) it is resolved.

      Stable vars opt in to compile-time folding by VarTemplateCompiler: rather than producing a VarRefSegment that dispatches at resolve time, the compiler resolves the var once at compile time and stores a LiteralSegment carrying the resolved value. This eliminates the per-resolve dispatch cost for hot paths like @Value("${HOSTNAME:localhost}") where the underlying var (env / system property / etc.) is treated as a build-time constant by the application.

      Default: false. Vars that read mutable session-scoped state (request beans, args, config files) must leave this false — folding would cache an arbitrary resolution as a literal and break per-session correctness.

      Common opt-ins:

      Folding contract:

      When a Var returns true here, the compiler invokes doResolve(VarResolverSession, String) on a no-bean session at compile time. Implementations must not throw on absent session beans during stable folding; if the stable resolution would itself depend on session state (i.e. it isn't really stable), either return false from this method or throw a VarResolverException from doResolve(VarResolverSession, String) which the compiler treats as "cannot fold; emit a normal VarRefSegment".

      Returns:
      true if this variable's resolution is invariant across sessions.

    • doResolve

      protected String doResolve(VarResolverSession session, String arg) throws Exception
      The method called from VarResolver.

      Can be overridden to intercept the request and do special handling.
      Default implementation simply calls resolve(String).

      Parameters:
      session - The session object used for a single instance of a string resolution.
      arg - The inside argument of the variable.
      Returns:
      The resolved value.
      Throws:
      Exception - Any exception can be thrown.

    • getName

      protected String getName()
      Return the name of this variable.

      For example, the system property variable returns "S" since the format of the variable is "$S{system.property}".

      Returns:
      The name of this variable.