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

Annotation Interface JStacheConfig

@Retention(RUNTIME) @Target({PACKAGE,MODULE,TYPE,ANNOTATION_TYPE}) @Documented public @interface JStacheConfig
Set module or package level config for JStache annotated models that do not have the configuration explicitly set (e.g. they have something other than the default of unspecified annotation return type).

Config Resolution

The order of which settings is preferred if set in general is Class > Package > Module.

Specifically the resolution is:

  1. Class annotated with JStache and setting is in JStache annotation NOT set to UNSPECIFIED.
  2. Class annotated with JStache and this annotation NOT set to UNSPECIFIED.
  3. Enclosing classes enclosing the class annotated with JStache with inner to outer order annotated with this annotation NOT set to UNSPECIFIED.
  4. Package annotated with this annotation NOT set to UNSPECIFIED.
  5. Module annotated with this annotation NOT set to UNSPECIFIED.
  6. If everything is unspecified at this point the real default is used (not the default return of the annotation).
While package hierarchy may seem natural for cascading config this library does not do it. Package hierarchy does NOT matter to this library! Resolution will NOT check up parent package directories. If you do not want to copy config to each package it is recommended you use module annotations or use using() to reference other configuration (see next section).

Config Importing

You may import config annotated elsewhere with using(). When config is imported from another class it is essentially a union of NON UNSPECIFIED settings of this annotation instance and the imported class. Thus config resolution follows as though the settings are on this instance.

The referenced config class can be any declared type (interface, enum, etc) but it is best practice to make it something like an empty Enum to avoid confusing it with models.

Unspecified

Annotation methods that return symbols prefixed with "Unspecified" (e.g. JStacheType.UNSPECIFIED) or have values called UNSPECIFIED or return an empty array, empty string, or void.class represent unset and will be resolved through the config resolution. Consequently unlike other annotation implementations the default return of the annotation is not really the concrete default.
Author:
agentgt
API Note
This annotation and thus configuration is available during runtime unlike many of the other annotations in jstachio.

  • Element Details

    • using

      Class<?> using
      Imports configuration from another class annotated by this or other JStache annotations. This allows config sharing even across compile boundaries.

      The configuration on this annotation instance (the one calling using()) will however take precedence if is not UNSPECIFIED.

      using() is not cascading meaning that the referenced configuration classes (the using returned on this instance) that have using() set will be ignored! Furthermore configuration set on enclosing classes, packages, modules on the referenced type are ignored.

      Returns:
      by default void.class which represents UNSPECIFIED.
      Default:
      void.class

    • naming

      JStacheName[] naming
      If JStache.name() is blank the name of the generated class is derived from the models class name and then augmented with JStacheName.prefix() and JStacheName.suffix().
      Returns:
      by default an empty array which represents UNSPECIFIED.
      See Also:
      API Note
      the cardinality of the returned array is currently 0..1. additional elements after the first will be ignored.
      Default:
      {}

    • pathing

      JStachePath[] pathing
      If JStache.path() is not blank the path of the template is resolved by augmenting with JStachePath.prefix() and JStachePath.suffix().
      Returns:
      by default an empty array which represents UNSPECIFIED.
      See Also:
      API Note
      the cardinality of the returned array is currently 0..1. additional elements after the first will be ignored.
      Default:
      {}

    • interfacing

      JStacheInterfaces[] interfacing
      Configures what interfaces/annotations the model implements and or extends.
      Returns:
      by default an empty array which represents UNSPECIFIED.
      See Also:
      API Note
      the cardinality of the returned array is currently 0..1. additional elements after the first will be ignored.
      Default:
      {}

    • contentType

      Class<?> contentType
      Optional content type which determines what escaper to use for all models in the annotated class/package/module.

      The contentType class needs a JStacheContentType annotation on the type. If type() is resolved to JStacheType.JSTACHIO a spec based HTML content type will be used if unspecified.

      Returns:
      by default an UNSPECIFIED content type.
      See Also:
      Default:
      io.jstach.jstache.JStacheContentType.UnspecifiedContentType.class

    • formatter

      Class<?> formatter
      Optional formatter if not UNSPECIFIED for all models in the annotated class/package/module .

      The formatter provider class needs a JStacheFormatter annotation on the type. If type() is resolved to JStacheType.JSTACHIO a default formatter that does not allow null will be used.

      Returns:
      by default an UNSPECIFIED formatter.
      See Also:
      Default:
      io.jstach.jstache.JStacheFormatter.UnspecifiedFormatter.class

    • charset

      String charset
      Encoding of template files.

      charset can be omitted. If not set StandardCharsets.UTF_8 is used by default.

      Returns:
      encoding of given template file
      Default:
      ""

    • type

      JStacheType type
      Determines what style of of code to generate. See JStacheType.
      Returns:
      JStacheType.UNSPECIFIED by default which means the generated code will depend on jstachio runtime if no other config overrides (ie is not set to auto).
      Default:
      UNSPECIFIED