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

Class Templates

java.lang.Object
io.jstach.jstachio.spi.Templates
public final class Templates extends Object
Locates generated templates by their model via reflection.

This utility class is useful if you plan on implementing your own JStachio and or other integrations.

Author:
agentgt
API Note
In order to use reflection in a modular setup one must open packages to the io.jstach.jstachio module.

  • Method Details

    • validateEncoding

      public static void validateEncoding(TemplateInfo template, Output.EncodedOutput<?> output)
      A utility method that will check if the templates encoding matches the outputs encoding.
      Parameters:
      template - template charset to check
      output - an encoded output expecting the template charset to be the same.
      Throws:
      UnsupportedCharsetException - if the charsets do not match

    • findTemplate

      public static TemplateInfo findTemplate(Class<?> modelType, JStachioConfig config) throws Exception
      Finds a Template if possible otherwise falling back to a TemplateInfo based on annotation metadata. A call first resolves the type that is actually annotated with JStache and then effectively calls getTemplate(Class) first and if that fails possibly tries getInfoByReflection(Class) based on config.
      Parameters:
      modelType - the models class (the one annotated with JStache and not the Templates class)
      config - config used to determine whether or not to fallback
      Returns:
      the template info which might be a Template if the generated template was found.
      Throws:
      Exception - if any reflection error happes or the template is not found
      API Note
      Callers can do an instanceof Template t to see if a generated template was returned instead of the fallback.

    • findTemplateOrNull

      public static @Nullable TemplateInfo findTemplateOrNull(Class<?> modelType, JStachioConfig config)
      Finds a Template if possible otherwise falling back to a TemplateInfo based on annotation metadata. A call first resolves the type that is actually annotated with JStache and then effectively calls getTemplate(Class) first and if that fails possibly tries getInfoByReflection(Class) based on config. Unlike findTemplate(Class, JStachioConfig) this call will not produce any logging and will not throw an exception if it fails.
      Parameters:
      modelType - the models class (the one annotated with JStache and not the Templates class)
      config - config used to determine whether or not to fallback
      Returns:
      the template info which might be a Template if the generated template was found or null if not found.
      API Note
      Callers can do an instanceof Template t to see if a generated template was returned instead of the fallback.

    • getInfoByReflection

      public static TemplateInfo getInfoByReflection(Class<?> modelType) throws Exception
      Finds template info by accessing JStache annotations through reflective lookup.

      This allows you to lookup template meta data regardless of whether or not the annotation processor has generated code. This method is mainly used for fallback mechanisms and extensions.

      Why might you need the reflective data instead of the static generated meta data? Well often times the annotation processor in a hot reload environment such as JRebel, JBoss modules, or Spring Reload has not generated the code from a JStache model and or it is not desired. This allows reflection based engines like JMustache to keep working even if code is not generated.

      Parameters:
      modelType - the class that is annotated with JStache
      Returns:
      template info meta data
      Throws:
      Exception - if any reflection error happes or the template is not found

    • getTemplate

      public static <T> Template<T> getTemplate(Class<T> clazz) throws Exception
      Finds a template by reflection or an exception is thrown.
      Type Parameters:
      T - the model type
      Parameters:
      clazz - the model type
      Returns:
      the template never null.
      Throws:
      NoSuchElementException - if the template is not found
      Exception - if the template is not found or any reflective access errors

    • getTemplate

      public static <T> Template<T> getTemplate(Class<T> modelType, Iterable<Templates.TemplateLoadStrategy> strategies, Iterable<ClassLoader> classLoaders, System.Logger logger) throws Exception
      Finds a template by reflection or an exception is thrown. Because the return template is parameterized a template matching the exact type is returned and inheritance either via interfaces or super class is not checked!
      Type Parameters:
      T - the model type
      Parameters:
      modelType - the model type
      strategies - load strategies
      classLoaders - class loaders to try loading
      logger - used to log attempted strategies. If you do not want to log use JStachioConfig.noopLogger().
      Returns:
      the template never null.
      Throws:
      NoSuchElementException - if the template is not found
      Exception - if the template is not found or any reflective access errors

    • generatedClassName

      public static String generatedClassName(Class<?> modelClass)
      Gets the canonical class name of the generated template code regardless of whether or not code has actually been generated. Because the class may not have been generated the return is a String.
      Parameters:
      modelClass - the exact model class that contains the JStache annotation.
      Returns:
      the FQN class name of the would be generated template code
      Throws:
      NoSuchElementException - if the model class is not annotated with JStache.

    • findTemplates

      public static Stream<Template<?>> findTemplates(ServiceLoader<TemplateProvider> serviceLoader, TemplateConfig templateConfig, Consumer<ServiceConfigurationError> errorHandler)
      Find templates by the given service loader.
      Parameters:
      serviceLoader - a prepared service loader
      templateConfig - template config to use for instantiating templates
      errorHandler - handle ServiceConfigurationError errors.
      Returns:
      lazy stream of templates

    • resolvePath

      @Deprecated public static @Nullable JStachePath resolvePath(Class<?> model)
      Deprecated.
      use getInfoByReflection(Class) or getPathInfo(Class).
      Resolve path lookup information reflectively from a model class by doing config resolution at runtime.
      Parameters:
      model - a class annotated with JStache
      Returns:
      the resolved path annotation
      API Note
      This method is an implementation detail for reflection rendering engines such as JMustache and JStachio's future reflection based engine. It is recommended you do not rely on it as it is subject to change in the future.

    • getPathInfo

      public static Templates.PathInfo getPathInfo(Class<?> modelClass)
      INTERNAL (use at your own risk): Resolved JStachePath config by replacing JStachePath.UNSPECIFIED with default values. The passed in model class does not need be directly annotated with JStache and can be subclass.
      Parameters:
      modelClass - the model's class
      Returns:
      never null path information.
      API Note
      INTERNAL (use at your own risk): This method largely exists because TemplateInfo does not expose the original prefix and suffix used. The prefix and suffix are needed for reloading the templates for extensions. If you use this method please let the developers know and for what.