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

Interface JStachio

All Superinterfaces:
Renderer<Object>
All Known Subinterfaces:
ContextJStachio
All Known Implementing Classes:
AbstractJStachio, SpringJStachio
public interface JStachio extends Renderer<Object>
Render models by using reflection or static catalog to lookup generated templates as well as apply filtering and fallback mechanisms.

Example Usage


 @JStache(template = "Hello {{name}}!")
 public record HelloWorld(String name) {}

 public static String output(String name) {
   //Normally you would have to use generated class HelloWorldRenderer
   //but this JStachio allows you to render directly
   //from the model.
   return JStachio.render(new HelloWorld(name));
 }
Not only is the above more convenient than using the raw generated code it also allows additional custom runtime behavior like filtering as well as allows easier integration with web frameworks.

Customize

The default JStachio uses the ServiceLoader to load JStachioExtensions. You can customize it by adding jars that have provided JStachioExtensions or by adjusting config.

If you would like to create your own JStachio instead of the default you can either extend AbstractJStachio or use JStachioFactory.builder(). If you want your custom JStachio to be set as the default such that the static render methods on this class call it you can do that with setStatic(Supplier). While this interface is not sealed it is strongly recommended that you do not implement this interface! It has been left unsealed for mocking and testing purposes.

See Also:
API Note
The static render methods are convenience methods that will by default use the ServiceLoader based JStachio which loads all extensions via the ServiceLoader.

  • Method Details

    • execute

      default void execute(Object model, Appendable appendable) throws IOException
      Finds a template by using the models class if possible and then applies filtering and then finally render the model by writing to the appendable.

      Renders the passed in model.

      Specified by:
      execute in interface Renderer<Object>
      Parameters:
      model - a model assumed never to be null.
      appendable - the appendable to write to.
      Throws:
      IOException - if there is an error writing to the appendable

    • execute

      default StringBuilder execute(Object model, StringBuilder sb)
      Finds a template by using the models class if possible and then applies filtering and then finally render the model by writing to the StringBuilder.

      A convenience method that does not throw IOException when using StringBuilder.

      Specified by:
      execute in interface Renderer<Object>
      Parameters:
      model - a model assumed never to be null.
      sb - should never be null.
      Returns:
      the passed in StringBuilder.

    • execute

      default String execute(Object model)
      Finds a template by using the models class if possible and then applies filtering and then finally render the model to a String.

      Convenience method that directly renders the model as a String.

      Specified by:
      execute in interface Renderer<Object>
      Parameters:
      model - never null.
      Returns:
      the rendered model.

    • write

      <A extends Output.EncodedOutput<E>, E extends Exception> A write(Object model, A output) throws E
      Renders the passed in model directly to a binary stream possibly leveraging pre-encoded parts of the template. This may improve performance when rendering UTF-8 to an OutputStream as some of the encoding is done in advance. Because the encoding is done statically you cannot pass the charset in. The chosen charset comes from JStacheConfig.charset().
      Type Parameters:
      A - output type
      E - error type
      Parameters:
      model - a model assumed never to be null.
      output - to write to.
      Returns:
      the passed in output for convenience
      Throws:
      UnsupportedCharsetException - if the encoding of the output does not match the template.
      E - if an error occurs while writing to output

    • findTemplate

      Template<Object> findTemplate(Object model) throws Exception
      Finds a template by model. This is useful if you need metadata before writing such as charset and media type for HTTP output which the template has.

      The returned template is decorated if filtering is on and a filter that is not the template is applied.

      Passing in a TemplateModel should work as well and the returned template will be able to execute the TemplateModel as though it were a regular model.

      Parameters:
      model - the actual model or a TemplateModel containing the model
      Returns:
      a filtered template
      Throws:
      NoSuchElementException - if a template is not found and no other lookup errors happen.
      Exception - if template cannot be found for unexpected reasons such as reflection errors.
      API Note
      implementations should handle TemplateModel passed in.

    • supportsType

      boolean supportsType(Class<?> modelType)
      Determines if this jstachio can render the model type (the class annotated by JStache).
      Parameters:
      modelType - the models class (the one annotated with JStache and not the Templates class)
      Returns:
      true if this jstachio can render instances of modelType

    • render

      static void render(Object model, Appendable a) throws IOException
      Executes the ServiceLoader instance of JStachio execute(Object, Appendable).
      Parameters:
      model - never null
      a - appendable never null
      Throws:
      IOException - if there is an error using the appendable
      See Also:

    • render

      static StringBuilder render(Object model, StringBuilder a)
      Executes the ServiceLoader instance of JStachio execute(Object, StringBuilder).
      Parameters:
      model - never null
      a - appendable never null
      Returns:
      the passed in StringBuilder
      See Also:

    • render

      static String render(Object model)
      Executes the ServiceLoader instance of JStachio execute(Object).
      Parameters:
      model - the root context model. Never null.
      Returns:
      the rendered string.
      See Also:

    • of

      static JStachio of()
      Gets the static singleton jstachio.
      Returns:
      the jstachio from setStatic(Supplier)
      Throws:
      NullPointerException - if jstachio is not found
      See Also:

    • defaults

      static JStachio defaults()
      Gets default singleton ServiceLoader based jstachio.
      Returns:
      service loaded jstachio

    • setStatic

      static void setStatic(Supplier<JStachio> jstachioProvider)
      Set the static singleton of JStachio.

      Useful if you would like to avoid using the default ServiceLoader mechanism.

      Parameters:
      jstachioProvider - if null a NPE will be thrown.
      API Note
      the provider will be called on every call of of() and thus to avoid constant recreation it is recommend the supplier be memoized/cached.