jvmMain.com.giancarlobuenaflor.kflogger.backend.system.Clock Maven / Gradle / Ivy
/*
* Copyright (C) 2017 The Flogger Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.giancarlobuenaflor.kflogger.backend.system;
/**
* 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.
*
*
* - Implementations MUST NOT attempt any logging in static methods or constructors.
*
- Implementations MUST NOT statically depend on any unknown code.
*
- 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 {@link 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 {@code
* META-INF/services/com.giancarlobuenaflor.kflogger.backend.system.Clock} file containing the name of
* your implementation class or by annotating your implementation class using {@code @AutoService(Clock.class)}.
* See the documentation of both {@link java.util.ServiceLoader} and {@link DefaultPlatform} for
* more information.
*/
public abstract class Clock {
/**
* Returns the current time from the epoch (00:00 1st Jan, 1970) with nanosecond granularity,
* though not necessarily nanosecond precision. This clock measures UTC and is not required to
* handle leap seconds.
*/
public abstract long getCurrentTimeNanos();
}