Clock

A clock to return walltime timestamps for log statements. This is implemented as an abstract class (rather than an interface) to reduce to risk of breaking existing implementations if the API changes.

Essential Implementation Restrictions

Any implementation of this API MUST follow the rules listed below to avoid any risk of re-entrant code calling during logger initialization. Failure to do so risks creating complex, hard to debug, issues with Flogger configuration.

1. Implementations MUST NOT attempt any logging in static methods or constructors.
2. Implementations MUST NOT statically depend on any unknown code.
3. Implementations MUST NOT depend on any unknown code in constructors.

Note that logging and calling arbitrary unknown code (which might log) are permitted inside the instance methods of this API, since they are not called during platform initialization. The easiest way to achieve this is to simply avoid having any non-trivial static fields or any instance fields at all in the implementation.

While this sounds onerous it's not difficult to achieve because this API is a singleton, and can delay any actual work until its methods are called. For example if any additional state is required in the implementation, it can be held via a "lazy holder" to defer initialization.

This is a service type

This type is considered a service type and implemenations may be loaded from the classpath via java.util.ServiceLoader provided the proper service metadata is included in the jar file containing the implementation. When creating an implementation of this class, you can provide serivce metadata (and thereby allow users to get your implementation just by including your jar file) by either manually including a META-INF/services/io.spine.logging.flogger.backend.Clock file containing the name of your implementation class or by annotating your implementation class using @AutoService(Clock.class). See the documentation of both java.util.ServiceLoader and DefaultPlatform for more information.

See also