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() { ... }
 }
 

All formatters should be able to handle:

• String
• native types both unboxed or boxed
• URI
• URL

(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:

• JStacheFormatterTypes
• JStacheConfig.formatter()

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"