log4j-core/src/main/java/org/apache/logging/log4j/core/LogEvent.java - logging-log4j2 - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements. See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You 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 org.apache.logging.log4j.core;

 import java.io.Serializable;

 import org.apache.logging.log4j.Level;
 import org.apache.logging.log4j.Marker;
 import org.apache.logging.log4j.ThreadContext;
 import org.apache.logging.log4j.core.impl.ThrowableProxy;
 import org.apache.logging.log4j.core.time.Instant;
 import org.apache.logging.log4j.message.Message;
 import org.apache.logging.log4j.util.ReadOnlyStringMap;

 /**
  * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
  * may be transmitted over a network connection. Besides containing a
  * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
  * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
  * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
  * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
  * {@link #getContextData()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
  * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
  * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
  * and deserialized properly without causing problems if the exception class is not available on the other end.
  */
 public interface LogEvent extends Serializable {

     /**
      * Returns an immutable version of this log event, which MAY BE a copy of this event.
      *
      * @return an immutable version of this log event
      */
     LogEvent toImmutable();

     /**
      * Returns the {@code ReadOnlyStringMap} object holding context data key-value pairs.
      * <p>
      * Context data (also known as Mapped Diagnostic Context or MDC) is data that is set by the application to be
      * included in all subsequent log events. The default source for context data is the {@link ThreadContext} (and
      * <a href="https://logging.apache.org/log4j/2.x/manual/configuration.html#PropertySubstitution">properties</a>
      * configured on the Logger that logged the event), but users can configure a custom {@link ContextDataInjector}
      * to inject key-value pairs from any arbitrary source.
      *
      * @return the {@code ReadOnlyStringMap} object holding context data key-value pairs
      * @see ContextDataInjector
      * @see ThreadContext
      * @since 2.7
      */
     ReadOnlyStringMap getContextData();

     /**
      * Gets the context stack (also known as Nested Diagnostic Context or NDC).
      *
      * @return The context stack, never {@code null}.
      */
     ThreadContext.ContextStack getContextStack();

     /**
      * Returns the fully qualified class name of the caller of the logging API.
      *
      * @return The fully qualified class name of the caller.
      */
     String getLoggerFqcn();

     /**
      * Gets the level.
      *
      * @return level.
      */
     Level getLevel();

     /**
      * Gets the logger name.
      *
      * @return logger name, may be {@code null}.
      */
     String getLoggerName();

     /**
      * Gets the Marker associated with the event.
      *
      * @return Marker or {@code null} if no Marker was defined on this LogEvent
      */
     Marker getMarker();

     /**
      * Gets the message associated with the event.
      *
      * @return message.
      */
     Message getMessage();

     /**
      * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
      * Use {@link #getInstant()} to get higher precision timestamp information if available on this platform.
      *
      * @return the milliseconds component of this log event's {@linkplain #getInstant() timestamp}
      * @see java.lang.System#currentTimeMillis()
      */
     long getTimeMillis();

     /**
      * Returns the Instant when the message was logged.
      * <p>
      * <b>Caution</b>: if this {@code LogEvent} implementation is mutable and reused for multiple consecutive log messages,
      * then the {@code Instant} object returned by this method is also mutable and reused.
      * Client code should not keep a reference to the returned object but make a copy instead.
      * </p>
      *
      * @return the {@code Instant} holding Instant details for this log event
      * @since 2.11.0
      */
     Instant getInstant();

     /**
      * Gets the source of logging request.
      *
      * @return source of logging request, may be null.
      */
     StackTraceElement getSource();

     /**
      * Gets the thread name.
      *
      * @return thread name, may be null.
      * TODO guess this could go into a thread context object too. (RG) Why?
      */
     String getThreadName();

     /**
      * Gets the thread ID.
      *
      * @return thread ID.
      * @since 2.6
      */
     long getThreadId();

     /**
      * Gets the thread priority.
      *
      * @return thread priority.
      * @since 2.6
      */
     int getThreadPriority();

     /**
      * Gets throwable associated with logging request.
      *
      * <p>Convenience method for {@code ThrowableProxy.getThrowable();}</p>
      *
      * @return throwable, may be null.
      */
     Throwable getThrown();

     /**
      * Gets throwable proxy associated with logging request.
      *
      * @return throwable, may be null.
      */
     ThrowableProxy getThrownProxy();

     /**
      * Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous
      * Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient
      * alternative to the {@code immediateFlush=true} configuration.
      *
      * @return whether this event is the last one in a batch.
      */
     // see also LOG4J2-164
     boolean isEndOfBatch();

     /**
      * Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
      * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
      * another thread.
      *
      * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
      * @see #getSource()
      */
     // see also LOG4J2-153
     boolean isIncludeLocation();

     /**
      * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to
      * buffered downstream components when to flush to disk, as a more efficient alternative to the
      * {@code immediateFlush=true} configuration.
      *
      * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
      */
     void setEndOfBatch(boolean endOfBatch);

     /**
      * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
      * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
      * another thread.
      *
      * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false}
      *                         otherwise.
      * @see #getSource()
      */
     void setIncludeLocation(boolean locationRequired);

     /**
      * Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created,
      * or a dummy value if it is known that this value will not be used downstream.
      * @return The value of the running Java Virtual Machine's high-resolution time source when this event was created.
      * @since Log4J 2.4
      */
     long getNanoTime();
 }
	/*
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You 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 org.apache.logging.log4j.core;

	import java.io.Serializable;

	import org.apache.logging.log4j.Level;
	import org.apache.logging.log4j.Marker;
	import org.apache.logging.log4j.ThreadContext;
	import org.apache.logging.log4j.core.impl.ThrowableProxy;
	import org.apache.logging.log4j.core.time.Instant;
	import org.apache.logging.log4j.message.Message;
	import org.apache.logging.log4j.util.ReadOnlyStringMap;

	/**
	* Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
	* may be transmitted over a network connection. Besides containing a
	* {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
	* {@link org.apache.logging.log4j.Level} that the message was logged at. If a
	* {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
	* {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
	* {@link #getContextData()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
	* call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
	* be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
	* and deserialized properly without causing problems if the exception class is not available on the other end.
	*/
	public interface LogEvent extends Serializable {

	/**
	* Returns an immutable version of this log event, which MAY BE a copy of this event.
	*
	* @return an immutable version of this log event
	*/
	LogEvent toImmutable();

	/**
	* Returns the {@code ReadOnlyStringMap} object holding context data key-value pairs.
	* <p>
	* Context data (also known as Mapped Diagnostic Context or MDC) is data that is set by the application to be
	* included in all subsequent log events. The default source for context data is the {@link ThreadContext} (and
	* <a href="https://logging.apache.org/log4j/2.x/manual/configuration.html#PropertySubstitution">properties</a>
	* configured on the Logger that logged the event), but users can configure a custom {@link ContextDataInjector}
	* to inject key-value pairs from any arbitrary source.
	*
	* @return the {@code ReadOnlyStringMap} object holding context data key-value pairs
	* @see ContextDataInjector
	* @see ThreadContext
	* @since 2.7
	*/
	ReadOnlyStringMap getContextData();

	/**
	* Gets the context stack (also known as Nested Diagnostic Context or NDC).
	*
	* @return The context stack, never {@code null}.
	*/
	ThreadContext.ContextStack getContextStack();

	/**
	* Returns the fully qualified class name of the caller of the logging API.
	*
	* @return The fully qualified class name of the caller.
	*/
	String getLoggerFqcn();

	/**
	* Gets the level.
	*
	* @return level.
	*/
	Level getLevel();

	/**
	* Gets the logger name.
	*
	* @return logger name, may be {@code null}.
	*/
	String getLoggerName();

	/**
	* Gets the Marker associated with the event.
	*
	* @return Marker or {@code null} if no Marker was defined on this LogEvent
	*/
	Marker getMarker();

	/**
	* Gets the message associated with the event.
	*
	* @return message.
	*/
	Message getMessage();

	/**
	* Gets event time in milliseconds since midnight, January 1, 1970 UTC.
	* Use {@link #getInstant()} to get higher precision timestamp information if available on this platform.
	*
	* @return the milliseconds component of this log event's {@linkplain #getInstant() timestamp}
	* @see java.lang.System#currentTimeMillis()
	*/
	long getTimeMillis();

	/**
	* Returns the Instant when the message was logged.
	* <p>
	* <b>Caution</b>: if this {@code LogEvent} implementation is mutable and reused for multiple consecutive log messages,
	* then the {@code Instant} object returned by this method is also mutable and reused.
	* Client code should not keep a reference to the returned object but make a copy instead.
	* </p>
	*
	* @return the {@code Instant} holding Instant details for this log event
	* @since 2.11.0
	*/
	Instant getInstant();

	/**
	* Gets the source of logging request.
	*
	* @return source of logging request, may be null.
	*/
	StackTraceElement getSource();

	/**
	* Gets the thread name.
	*
	* @return thread name, may be null.
	* TODO guess this could go into a thread context object too. (RG) Why?
	*/
	String getThreadName();

	/**
	* Gets the thread ID.
	*
	* @return thread ID.
	* @since 2.6
	*/
	long getThreadId();

	/**
	* Gets the thread priority.
	*
	* @return thread priority.
	* @since 2.6
	*/
	int getThreadPriority();

	/**
	* Gets throwable associated with logging request.
	*
	* <p>Convenience method for {@code ThrowableProxy.getThrowable();}</p>
	*
	* @return throwable, may be null.
	*/
	Throwable getThrown();

	/**
	* Gets throwable proxy associated with logging request.
	*
	* @return throwable, may be null.
	*/
	ThrowableProxy getThrownProxy();

	/**
	* Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous
	* Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient
	* alternative to the {@code immediateFlush=true} configuration.
	*
	* @return whether this event is the last one in a batch.
	*/
	// see also LOG4J2-164
	boolean isEndOfBatch();

	/**
	* Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
	* this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
	* another thread.
	*
	* @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
	* @see #getSource()
	*/
	// see also LOG4J2-153
	boolean isIncludeLocation();

	/**
	* Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to
	* buffered downstream components when to flush to disk, as a more efficient alternative to the
	* {@code immediateFlush=true} configuration.
	*
	* @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
	*/
	void setEndOfBatch(boolean endOfBatch);

	/**
	* Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
	* this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
	* another thread.
	*
	* @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false}
	* otherwise.
	* @see #getSource()
	*/
	void setIncludeLocation(boolean locationRequired);

	/**
	* Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created,
	* or a dummy value if it is known that this value will not be used downstream.
	* @return The value of the running Java Virtual Machine's high-resolution time source when this event was created.
	* @since Log4J 2.4
	*/
	long getNanoTime();
	}