Module io.jstach.jstache
Package io.jstach.jstache

Annotation Interface JStacheCatalog

@Retention(SOURCE) @Target(PACKAGE) @Documented public @interface JStacheCatalog
Place on package to generate a TemplateProvider/JStachioTemplateFinder that will have a catalog of all public generated JStache templates in the compile time boundary that are of type JStacheType.JSTACHIO.

The class will be put in the annotated package and implements both io.jstach.jstachio.spi.TemplateProvider and io.jstach.jstachio.spi.JStachioTemplateFinder.

This is useful for:

  1. Modular applications that use module-info.java instead of META-INF/services for service loader registration.
  2. Application wishing to avoid reflection altogether but still wanting to use JStachio runtime particularly the model to template loookup.
  3. Allow access and rendering of package protected models from other parts of the application.

Modular applications

Modular applications that do not want to allow reflective access ( opens ... to io.jstach.jstachio;) to the JStachio runtime can instead register the generated template provider in the module-info.java as a service provider like: 

 provides io.jstach.jstachio.spi.TemplateProvider with annotatedpackage.TemplateCatalog;
or as a JStachioTemplateFinder: 

 // module-info.java
 provides io.jstach.jstachio.spi.JStachioTemplateFinder with annotatedpackage.TemplateCatalog;
In general the TemplateProvider is preferred as it will allow reflective access (either ServiceLoader or direct constructor reflection) to other models that are perhaps not in the same compile time boundary as well as caching. Note that the generated code does not implement caching so if going the JStachioTemplateFinder route caching will be the implementers responsibility.

Tip: Some tools do not like generated classes being referenced in module-info.java therefore a general recommendation is to extend the generated class and reference the class doing the extending in the module-info.java. Below is an example: 


 // extend the generated class
 package annotatedpackage;
 public class MyTemplateCatalog extends TemplateCatalog {}
  

 // register the extended class
 provides io.jstach.jstachio.spi.TemplateProvider with annotatedpackage.MyTemplateCatalog;

Avoiding reflection

For those wanting to avoid reflection a custom JStachio can be created from the generated catalog. 

 JStachio j = JStachioFactory.builder()
     .add(new annotatedpackage.TemplateCatalog())
     .build();

Package protected models

If the package annotated has models that are package protected those models will still be added to the generated template catalog as the generated class will have access. Normally JStachio uses either the Service Loader which requires public access to the generated template or reflection which may or may not require public access depending on modularization.

Multiple packages can be annotated and thus multiple TemplateProvider/Finder can be referenced.

Author:
agentgt

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    JStacheCatalog.CatalogFlag
    Configuration flags for generating template catalogs such META-INF/services files.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    JStacheCatalog.CatalogFlag[]
    flags
    Configuration flags for generating template catalogs.
    String
    name
    Name of the generated class that will be put in the annotated package.

  • Element Details

    • name

      String name
      Name of the generated class that will be put in the annotated package.
      Returns:
      name of the class to be generated. The default is TemplateCatalog.
      Default:
      "TemplateCatalog"

    • flags

      JStacheCatalog.CatalogFlag[] flags
      Configuration flags for generating template catalogs.
      Returns:
      an array of flags.
      See Also:
      Default:
      {}