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

Annotation Interface JStacheFormatter

@Retention(RUNTIME) @Target(TYPE) @Documented public @interface JStacheFormatter
Statically registers a formatter.

Formatters are called before escapers to resolve the output of a variable (e.g. {{variable}}). Colloquially you can think of them as glorified Object.toString() on objects.

A class that is annotated statically provides a formatter instead of using the ServiceLoader and can be used as marker for a particular formatter in JStacheConfig.formatter().

There are two supported Formatter types:

  • io.jstach.jstachio.Formatter
  • java.util.function.Function<Object,String>
The Function one is desirable if you would like no reference of jstachio runtime api in your code base and or just an easier interface to implement.

On the otherhand the Formatter interfaces allows potentially greater performance and or if you need to format native types.

It is important to understand that formatters do not have complete control what types are allowed to be formatted. That is a formatter might be able to output a certain class but the annotation processor will fail before that as only certain types are allowed to be formatted. To control what types are allowed to be formatted (and thus will use the formatter at runtime) see JStacheFormatterTypes which also allows the formatter itself to be annotated.

Consequently if a class is annotated with this annotation and JStacheFormatterTypes the types will be added to the whitelist of allowed types if the annotated formatter is picked. Because you often need to whitelist types to allow customer formatters it is a best practice you annotate the formatter with whatever custom types are allowed.

For example let us say we want to add a custom formatter that is aware of LocalDate we would add: 

 
 @JStacheFormatter
 @JStacheFormatterTypes(types={LocalDate.class})
 public class MyFormatter {
   //required factory method
   public static Formatter provider() { ... }
 }
Or for zero dependency: 
 
 @JStacheFormatter
 @JStacheFormatterTypes(types={LocalDate.class})
 public class MyFormatter {
   //required factory method
   public static Function<Object,String> provider() { ... }
 }

All formatters should be able to handle:

(whether they output something however is up to the formatter). Because the allowed types can be widened more than what the formatter is annotated for a formatter also needs to be prepared for that. The default formatters in JStachio will toString() objects that are not recognized but whose types are whitelisted via JStacheFormatterTypes from other config.

Because formatters have to be rather omiscient of all types consider using a lambda JStacheLambda for formatting complex objects.

Author:
agentgt
See Also:
API Note
n.b. the class annotated does not need to implement the formatter interface! It just needs to provide it.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    JStacheFormatter.UnspecifiedFormatter
    A formatter type marker to resolve the formatter based on config elsewhere.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    providesMethod
    A static method that will return an implementation of io.jstach.api.runtime.Formatter or Function<Object,String>

  • Element Details

    • providesMethod

      String providesMethod
      A static method that will return an implementation of io.jstach.api.runtime.Formatter or Function<Object,String>
      Returns:
      default method name is provider just like the ServiceLoader
      Default:
      "provider"