1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache license, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the license for the specific language governing permissions and
15 * limitations under the license.
16 */
17 package org.apache.logging.log4j.core.time;
18
19 import org.apache.logging.log4j.core.util.Clock;
20 import org.apache.logging.log4j.util.StringBuilderFormattable;
21
22 /**
23 * Models a point in time, suitable for event timestamps.
24 * <p>
25 * Provides methods for obtaining high precision time information similar to the
26 * <a href="https://docs.oracle.com/javase/9/docs/api/java/time/Instant.html">Instant</a> class introduced in Java 8,
27 * while also supporting the legacy millisecond precision API.
28 * </p><p>
29 * Depending on the platform, time sources ({@link Clock} implementations) may produce high precision or millisecond
30 * precision time values. At the same time, some time value consumers (for example timestamp formatters) may only be
31 * able to consume time values of millisecond precision, while some others may require a high precision time value.
32 * </p><p>
33 * This class bridges these two time APIs.
34 * </p>
35 * @since 2.11
36 */
37 public interface Instant extends StringBuilderFormattable {
38 /**
39 * Gets the number of seconds from the Java epoch of 1970-01-01T00:00:00Z.
40 * <p>
41 * The epoch second count is a simple incrementing count of seconds where second 0 is 1970-01-01T00:00:00Z.
42 * The nanosecond part of the day is returned by {@link #getNanoOfSecond()}.
43 * </p>
44 * @return the seconds from the epoch of 1970-01-01T00:00:00Z
45 */
46 long getEpochSecond();
47
48 /**
49 * Gets the number of nanoseconds, later along the time-line, from the start of the second.
50 * <p>
51 * The nanosecond-of-second value measures the total number of nanoseconds from the second returned by {@link #getEpochSecond()}.
52 * </p>
53 * @return the nanoseconds within the second, always positive, never exceeds {@code 999,999,999}
54 */
55 int getNanoOfSecond();
56
57 /**
58 * Gets the number of milliseconds from the Java epoch of 1970-01-01T00:00:00Z.
59 * <p>
60 * The epoch millisecond count is a simple incrementing count of milliseconds where millisecond 0 is 1970-01-01T00:00:00Z.
61 * The nanosecond part of the day is returned by {@link #getNanoOfMillisecond()}.
62 * </p>
63 * @return the milliseconds from the epoch of 1970-01-01T00:00:00Z
64 */
65 long getEpochMillisecond();
66
67 /**
68 * Gets the number of nanoseconds, later along the time-line, from the start of the millisecond.
69 * <p>
70 * The nanosecond-of-millisecond value measures the total number of nanoseconds from the millisecond returned by {@link #getEpochMillisecond()}.
71 * </p>
72 * @return the nanoseconds within the millisecond, always positive, never exceeds {@code 999,999}
73 */
74 int getNanoOfMillisecond();
75 }