Module io.jstach.jstachio

Package io.jstach.jstachio

Interface Formatter

All Superinterfaces:

Function<@Nullable Object,String>

All Known Subinterfaces:

DefaultFormatter, SpecFormatter

public interface Formatter
extends Function<@Nullable Object,String>

Formats and then sends the results to the downstream appender. Implementations should be singleton like and should not contain state. By default native types are passed straight through to the downstream appender. If this is not desired one can override those methods.

Important: the formatter does not decide what types are allowed at compile time to be formatted. To control what types are allowed to be formatted see JStacheFormatterTypes.

Implementing

An alternative to implementing this complicated interface is to simply make a Function<@Nullable Object, String> and call of(Function) to create a formatter.

To implement a custom formatter:

1. Implement this interface or use of(Function).
2. Register the custom formatter with JStacheFormatter.
3. Add additional allowed types with JStacheFormatterTypes on to the class that is annotated with JStacheFormatter
4. Set JStacheConfig.formatter() to the class that has the JStacheFormatter.

It is the formatters responsibility to handle null for nullable format calls as the downstream appender do not allow null.

Author:

agentgt

See Also:

• JStacheFormatterTypes
• JStacheFormatter

API Note

Although the formatter has access to the raw Output the formatter should never use it directly and simply pass it on to the downstream appender.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Formatter.Formattable	Implement to allow formatting of custom objects you want to output.

Method Summary

Modifier and Type	Method	Description
default String	apply(@Nullable Object t)	Formats an object by using StringBuilder and calling format(Appender, Output, String, Class, Object).
default <A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, boolean b)	Formats the object and then sends the results to the downstream appender.
default <A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, char c)	Formats the object and then sends the results to the downstream appender.
default <A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, double d)	Formats the object and then sends the results to the downstream appender.
default <A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, int i)	Formats the object and then sends the results to the downstream appender.
default <A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, long l)	Formats the object and then sends the results to the downstream appender.
default <A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, short s)	Formats the object and then sends the results to the downstream appender.
default <A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, @Nullable Formatter.Formattable f)	Formats the formattable object and then sends the results to the downstream appender.
default <A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, @Nullable String s)	Formats the object and then sends the results to the downstream appender.
<A extends Output<E>, E extends Exception> void	format(Appender downstream, A a, String path, Class<?> c, @Nullable Object o)	Formats the object and then sends the results to the downstream appender.
static Formatter	of(Function<@Nullable Object,String> formatterFunction)	Adapts a function to a formatter.

Methods inherited from interface java.util.function.Function

andThen, compose

Method Details

apply

default String apply(@Nullable Object t)

Formats an object by using StringBuilder and calling format(Appender, Output, String, Class, Object).

Specified by:

apply in interface Function<@Nullable Object,String>

Parameters:

t - the object to be formatted. Maybe null.

Returns:

the formatted results as a String.

format

<A extends Output<E>,
E extends Exception> void format(Appender downstream,
 A a,
 String path,
 Class<?> c,
 @Nullable Object o)
                                               throws E

Formats the object and then sends the results to the downstream appender.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

c - the object class but is not guaranteed to be accurate. If it is not known Object.class will be used.

o - the object which maybe null

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender.

format

default <A extends Output<E>,
E extends Exception>
void format(Appender downstream,
 A a,
 String path,
 char c)
     throws E

Formats the object and then sends the results to the downstream appender. The default implementation passes natives through to the downstream appender.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

c - character

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender.

format

default <A extends Output<E>,
E extends Exception>
void format(Appender downstream,
 A a,
 String path,
 short s)
     throws E

Formats the object and then sends the results to the downstream appender. The default implementation passes natives through to the downstream appender.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

s - short

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender.

format

default <A extends Output<E>,
E extends Exception>
void format(Appender downstream,
 A a,
 String path,
 int i)
     throws E

Formats the object and then sends the results to the downstream appender. The default implementation passes natives through to the downstream appender.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

i - integer

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender.

format

default <A extends Output<E>,
E extends Exception>
void format(Appender downstream,
 A a,
 String path,
 long l)
     throws E

Formats the object and then sends the results to the downstream appender. The default implementation passes natives through to the downstream appender.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

l - long

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender.

format

default <A extends Output<E>,
E extends Exception>
void format(Appender downstream,
 A a,
 String path,
 double d)
     throws E

Formats the object and then sends the results to the downstream appender. The default implementation passes natives through to the downstream appender.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

d - double

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender.

format

default <A extends Output<E>,
E extends Exception>
void format(Appender downstream,
 A a,
 String path,
 boolean b)
     throws E

Formats the object and then sends the results to the downstream appender. The default implementation passes natives through to the downstream appender.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

b - boolean

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender.

format

default <A extends Output<E>,
E extends Exception>
void format(Appender downstream,
 A a,
 String path,
 @Nullable String s)
     throws E

Formats the object and then sends the results to the downstream appender. The default implementation calls format(Appender, Output, String, Class, Object) and it is generally recommend you override for performance.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

s - String value which maybe null.

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender. Also take note that the string value maybe null!

format

default <A extends Output<E>,
E extends Exception>
void format(Appender downstream,
 A a,
 String path,
 @Nullable Formatter.Formattable f)
     throws E

Formats the formattable object and then sends the results to the downstream appender. The default implementation will call the supplied Formatter.Formattable if it is not null otherwise it will call format(Appender, Output, String, Class, Object) to handle the null case.

Type Parameters:

A - the appendable type

E - the appender exception type

Parameters:

downstream - the downstream appender to be used instead of the appendable directly

a - the appendable to be passed to the appender

path - the dotted mustache like path

f - Formattable which maybe null.

Throws:

E - if the appender or appendable throws an exception

API Note

Although the formatter has access to the raw Appendable the formatter should never use it directly and simply pass it on to the downstream appender. Also take note that the string value maybe null!

of

static Formatter of(Function<@Nullable Object,String> formatterFunction)

Adapts a function to a formatter. If the function is already a formatter then it is simply returned (noop). Thus it is safe to repeatedly call this on formatters. If the function is adapted the returned adapted formatter does not pass native types to the inputted function.

Parameters:

formatterFunction - if it is already an escaper

Returns:

adapted formattter