Package io.spine.logging.flogger.backend

Class MetadataHandler<C>

java.lang.Object

io.spine.logging.flogger.backend.MetadataHandler<C>

Type Parameters:

C - the arbitrary context type.

public abstract class MetadataHandler<C>
extends Object

Callback API for logger backend implementations to handle metadata keys/values. The API methods will be called once for each distinct key, in encounter order. Different methods are called depending on whether the key is repeatable or not.

It is expected that the most convenient way to construct a metadata handler is via the Builder class, which lets keys be individually mapped to callbacks, however the class can also just be extended to implement alternate/custom behavior.

See Also:

Original Java code of Google Flogger

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MetadataHandler.Builder<C>	Builder for a map-based MetadataHandler which allows handlers to be associated with individual callbacks.
static interface	MetadataHandler.RepeatedValueHandler<T,C>	API for handling repeated metadata key/values in a single callback.
static interface	MetadataHandler.ValueHandler<T,C>	API for handling metadata key/value pairs individually.

Constructor Summary

Constructors

Constructor	Description
MetadataHandler()

Method Summary

Modifier and Type	Method	Description
static <C> MetadataHandler.Builder<C>	builder(MetadataHandler.ValueHandler<Object,C> defaultHandler)	Returns a builder for a handler with the specified default callback.
protected abstract <T> void	handle(FloggerMetadataKey<T> key, T value, C context)	Handles a single metadata key/value mapping.
protected <T> void	handleRepeated(FloggerMetadataKey<T> key, Iterator<T> values, C context)	Handles values for a repeatable metadata key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetadataHandler

public MetadataHandler()

Method Detail

handle

protected abstract <T> void handle(FloggerMetadataKey<T> key,
                                   T value,
                                   C context)

Handles a single metadata key/value mapping. This method is called directly for singleton non repeatable) keys, but may also be called for repeated keys by the default implementation of handleRepeated(io.spine.logging.flogger.FloggerMetadataKey<T>, java.util.Iterator<T>, C). It is up to the implementation to override that method if this behaviour is unwanted.

Type Parameters:

T - the key/value type.

Parameters:

key - the metadata key (not necessarily a "singleton" key).

value - associated metadata value.

context - an arbitrary context object supplied to the process method.

handleRepeated

protected <T> void handleRepeated(FloggerMetadataKey<T> key,
                                  Iterator<T> values,
                                  C context)

Handles values for a repeatable metadata key. The method is called for all repeatable keys (even those with only one value). The default implementation makes repeated callbacks to the handle(io.spine.logging.flogger.FloggerMetadataKey<T>, T, C) method, in order, for each value.

Type Parameters:

T - the key/value type.

Parameters:

key - the repeatable metadata key.

values - a lightweight iterator over all values associated with the key. Note that this instance is read-only and must not be held beyond the scope of this callback.

context - an arbitrary context object supplied to the process method.

builder

public static <C> MetadataHandler.Builder<C> builder(MetadataHandler.ValueHandler<Object,C> defaultHandler)

Returns a builder for a handler with the specified default callback. The default handler will receive all key/value pairs from the metadata individually, which can result in repeated keys being seen more than once.

A default handler is required because no handler can know the complete set of keys which might be available and it is very undesirable to drop unknown keys. If default repeated values should be handled together, MetadataHandler.Builder.setDefaultRepeatedHandler(RepeatedValueHandler) should be called as well.

Unknown keys/values can only be handled in a generic fashion unless a given key is matched to a known constant. However the entire point of this map-based handler is to avoid any need to do explicit matching, so the default handler should not need to know the value type.

Type Parameters:

C - the context type.

Parameters:

defaultHandler - the default handler for unknown keys/values.