Module io.jstach.jstachio
Package io.jstach.jstachio.context

Interface ContextNode

All Superinterfaces:
Formatter.Formattable, Iterable<@Nullable ContextNode>
All Known Implementing Classes:
ObjectContext
public sealed interface ContextNode extends Formatter.Formattable, Iterable<@Nullable ContextNode>
This interface serves three puproses:
  1. A way to represent the current context stack (see parent())
  2. Allow you to simulate JSON/Javscript object node like trees without being coupled to a particularly JSON lib.
  3. Represent per request context data in a web framework like CSRF tokens.
The interface simply wraps Map and Iterable (and arrays) lazily through composition but generally cannot wrap other context nodes. If an object is wrapped that is not a Map or Iterable it becomes a leaf node similar to JSON.

It is not recommended you use this interface as it avoids much of the type checking safty of this library, decreases performance as well as increase coupling however it does provide a slightly better bridge to legacy Map<String,?> models over using the maps directly.

Context Node while similar to a Map does not follow the same rules of resolution where Map resolves bindings always last. It will resolve first and thus it is easy to accidentally get stuck in the Context Node context. To prevent this it is highly recommended you do not open a context node with a section block and prefer dotted notation to access it.

Example:


 {{message}}
 {{#@context}}
 {{message}} {{! message here will only ever resolve against @context and not the parent }}
 {{/@context}}
Author:
agentgt
See Also:
API Note
The parents do not know anything about their children as it is the child that has reference to the parent. This interface unlike most of JStachio API is very null heavy because JSON and Javascript allow null.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    CONTEXT_BINDING_NAME
    The default binding name in mustache for the context parameter.

  • Method Summary

    Modifier and Type
    Method
    Description
    static ContextNode
    empty()
    An empty context node that is safe to use identify comparison.
    @Nullable ContextNode
    find(String field)
    Will search up the tree for a field starting at this nodes children first.
    @Nullable ContextNode
    get(String field)
    Gets a field from a ContextNode.
    default boolean
    isFalsey()
    Determines if the node is falsey.
    static boolean
    isFalsey(@Nullable ContextNode context)
    Determines if the node is falsey based on mustache spec semantics where: null, empty iterables, empty arrays and boolean false are falsey however empty Map is not falsey but empty() is always falsey.
    static boolean
    isFalsey(@Nullable Object context)
    Determines if an object is falsey based on mustache spec semantics where: null, empty iterables, empty arrays and boolean false are falsey however empty Map is not falsey.
    Iterator<@Nullable ContextNode>
    iterator()
    If the node is a Map or a non iterable/array a singleton iterator will be returned.
    Object
    object()
    The object being wrapped.
    static ContextNode
    of(Function<String,?> function)
    Creates a root context node with the given function to look up children.
    static ContextNode
    ofRoot(@Nullable Object o)
    Creates the root node from an Object.
    default @Nullable ContextNode
    parent()
    The parent node.
    default String
    renderString()
    Convenience method for calling toString on the wrapped object.
    static ContextNode
    resolve(Object o)
    Resolves the context node from an object.
    static ContextNode
    resolve(Object first, Object second)
    Resolves the context node trying first and then second.

    Methods inherited from interface io.jstach.jstachio.Formatter.Formattable

    format

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Field Details

  • Method Details

    • of

      static ContextNode of(Function<String,?> function)
      Creates a root context node with the given function to look up children.
      Parameters:
      function - used to find children with a given name
      Returns:
      root context node powered by a function
      API Note
      Unlike many other methods in this class this is not nullable.

    • empty

      static ContextNode empty()
      An empty context node that is safe to use identify comparison.
      Returns:
      empty singleton context node

    • resolve

      static ContextNode resolve(Object o)
      Resolves the context node from an object.
      Parameters:
      o - object that maybe a context or have a context.
      Returns:
      empty() if not found.

    • resolve

      static ContextNode resolve(Object first, Object second)
      Resolves the context node trying first and then second.
      Parameters:
      first - first object to try
      second - second object to try
      Returns:
      empty() if not found.

    • ofRoot

      static ContextNode ofRoot(@Nullable Object o)
      Creates the root node from an Object.
      Parameters:
      o - the object to be wrapped. Maybe null.
      Returns:
      empty() if the root object is null otherwise a new root node.
      API Note
      this method is legacy and mainly used for testing. Prefer of(Function). Prior to 1.3.0 the method may return null but now it will always return nonnull.

    • get

      @Nullable ContextNode get(String field)
      Gets a field from a ContextNode. This is direct access (end of a dotted path) and does not check the parents. The default implementation will check if the wrapping object is a Map and use it to return a child context node. Just like Map null will be returned if no field is found.
      Parameters:
      field - the name of the field
      Returns:
      a new child node. Maybe null.

    • find

      @Nullable ContextNode find(String field)
      Will search up the tree for a field starting at this nodes children first.
      Parameters:
      field - context name (e.g. section name)
      Returns:
      null if not found otherwise creates a new node from the map or object containing the field.

    • object

      Object object()
      The object being wrapped.
      Returns:
      the Map, Iterable or object that was wrapped. Never null.

    • renderString

      default String renderString()
      Convenience method for calling toString on the wrapped object.
      Returns:
      a toString on the wrapped object.

    • parent

      default @Nullable ContextNode parent()
      The parent node.
      Returns:
      the parent node or null if this is the root.

    • iterator

      Iterator<@Nullable ContextNode> iterator()
      If the node is a Map or a non iterable/array a singleton iterator will be returned. Otherwise if it is an iterable/array new child context nodes will be created lazily.
      Specified by:
      iterator in interface Iterable<@Nullable ContextNode>
      Returns:
      lazy iterator of context nodes.
      API Note
      Notice that return iterator may return null elements as JSON lists may contain null elements.

    • isFalsey

      default boolean isFalsey()
      Determines if the node is falsey. If falsey (return of true) inverted section blocks will be executed. The default checks if iterator() has any next elements and if it does not it is falsey.
      Returns:
      true if falsey.

    • isFalsey

      static boolean isFalsey(@Nullable Object context)
      Determines if an object is falsey based on mustache spec semantics where: null, empty iterables, empty arrays and boolean false are falsey however empty Map is not falsey. Optional is falsey if it is empty.
      Parameters:
      context - a context object. ContextNode are allowed as input as well as null.
      Returns:
      true if the object is falsey.

    • isFalsey

      static boolean isFalsey(@Nullable ContextNode context)
      Determines if the node is falsey based on mustache spec semantics where: null, empty iterables, empty arrays and boolean false are falsey however empty Map is not falsey but empty() is always falsey.
      Parameters:
      context - a context node. null.
      Returns:
      true if the node is falsey.