diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/BridgeAware.java b/log4j-api/src/main/java/org/apache/logging/log4j/BridgeAware.java index 4ee476c5248..38a11fe800d 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/BridgeAware.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/BridgeAware.java @@ -20,6 +20,7 @@ * Extended interface to allow bridges between logging systems to convey the * correct location information. * + * @since 2.19.0 */ public interface BridgeAware { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/CloseableThreadContext.java b/log4j-api/src/main/java/org/apache/logging/log4j/CloseableThreadContext.java index c585edf5460..f66c8144baa 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/CloseableThreadContext.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/CloseableThreadContext.java @@ -99,6 +99,9 @@ public static CloseableThreadContext.Instance putAll(final Map v return new CloseableThreadContext.Instance().putAll(values); } + /** + * @since 2.6 + */ public static class Instance implements AutoCloseable { private int pushCount = 0; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/EventLogger.java b/log4j-api/src/main/java/org/apache/logging/log4j/EventLogger.java index 9b08fa2d850..f88dccce895 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/EventLogger.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/EventLogger.java @@ -22,7 +22,8 @@ /** * Convenience to log {@link StructuredDataMessage}s. * - * @deprecated {@link Logger} accepts {@link StructuredDataMessage}s, users should use to that instead. + * @deprecated Deprecated since 2.24.0. + * {@link Logger} accepts {@link StructuredDataMessage}s, users should use to that instead. */ @Deprecated public final class EventLogger { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/LogBuilder.java b/log4j-api/src/main/java/org/apache/logging/log4j/LogBuilder.java index 992d2875138..2d5c18023b3 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/LogBuilder.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/LogBuilder.java @@ -22,6 +22,8 @@ /** * Interface for constructing log events before logging them. Instances of LogBuilders should only be created * by calling one of the Logger methods that return a LogBuilder. + * + * @since 2.13.0 */ public interface LogBuilder { /** NOOP Logbuilder */ @@ -110,7 +112,7 @@ default void log(final Supplier messageSupplier) {} * * @param messageSupplier The supplier of the message to log. * @return the message logger or {@code null} if no logging occurred. - * @since 2.20 + * @since 2.20.0 */ default Message logAndGet(final Supplier messageSupplier) { return null; @@ -128,6 +130,7 @@ default void log(final Object message) {} * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log(final String message, final Object p0) {} @@ -139,6 +142,7 @@ default void log(final String message, final Object p0) {} * @param p0 parameter to the message. * @param p1 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log(final String message, final Object p0, final Object p1) {} @@ -151,6 +155,7 @@ default void log(final String message, final Object p0, final Object p1) {} * @param p1 parameter to the message. * @param p2 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log(final String message, final Object p0, final Object p1, final Object p2) {} @@ -164,6 +169,7 @@ default void log(final String message, final Object p0, final Object p1, final O * @param p2 parameter to the message. * @param p3 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log(final String message, final Object p0, final Object p1, final Object p2, final Object p3) {} @@ -178,6 +184,7 @@ default void log(final String message, final Object p0, final Object p1, final O * @param p3 parameter to the message. * @param p4 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log( @@ -199,6 +206,7 @@ default void log( * @param p4 parameter to the message. * @param p5 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log( @@ -222,6 +230,7 @@ default void log( * @param p5 parameter to the message. * @param p6 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log( @@ -247,6 +256,7 @@ default void log( * @param p6 parameter to the message. * @param p7 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log( @@ -274,6 +284,7 @@ default void log( * @param p7 parameter to the message. * @param p8 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log( @@ -303,6 +314,7 @@ default void log( * @param p8 parameter to the message. * @param p9 parameter to the message. * + * @since 2.13.1 * @see org.apache.logging.log4j.util.Unbox */ default void log( @@ -320,6 +332,8 @@ default void log( /** * Causes all the data collected to be logged. Default implementatoin does nothing. + * + * @since 2.14.1 */ default void log() {} } diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/LogManager.java b/log4j-api/src/main/java/org/apache/logging/log4j/LogManager.java index cdb91c57658..1cf86d26983 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/LogManager.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/LogManager.java @@ -43,6 +43,7 @@ public class LogManager { /** * Log4j's property to set to the fully qualified class name of a custom implementation of * {@link LoggerContextFactory}. + * @since 2.0.1 * @deprecated Replaced since 2.24.0 with {@value org.apache.logging.log4j.spi.Provider#PROVIDER_PROPERTY_NAME}. */ @Deprecated @@ -297,6 +298,7 @@ protected static LoggerContext getContext( * @param configLocation The URI for the configuration to use. * @param name The LoggerContext name. * @return a LoggerContext. + * @since 2.9.1 */ protected static LoggerContext getContext( final String fqcn, diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java b/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java index ef461ddfe31..f958d08127c 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java @@ -142,6 +142,7 @@ public interface Logger { * * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. + * @since 2.6 */ void debug(Marker marker, CharSequence message); @@ -152,6 +153,7 @@ public interface Logger { * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void debug(Marker marker, CharSequence message, Throwable throwable); @@ -274,6 +276,7 @@ public interface Logger { * Logs a message CharSequence with the {@link Level#DEBUG DEBUG} level. * * @param message the message object to log. + * @since 2.6 */ void debug(CharSequence message); @@ -283,6 +286,7 @@ public interface Logger { * * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void debug(CharSequence message, Throwable throwable); @@ -363,6 +367,7 @@ public interface Logger { * @param marker the marker data specific to this log statement * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void debug(Marker marker, String message, Object p0); @@ -373,6 +378,7 @@ public interface Logger { * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void debug(Marker marker, String message, Object p0, Object p1); @@ -384,6 +390,7 @@ public interface Logger { * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void debug(Marker marker, String message, Object p0, Object p1, Object p2); @@ -396,6 +403,7 @@ public interface Logger { * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void debug(Marker marker, String message, Object p0, Object p1, Object p2, Object p3); @@ -409,6 +417,7 @@ public interface Logger { * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void debug(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -423,6 +432,7 @@ public interface Logger { * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void debug(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -438,6 +448,7 @@ public interface Logger { * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void debug( Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -455,6 +466,7 @@ void debug( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void debug( Marker marker, @@ -482,6 +494,7 @@ void debug( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void debug( Marker marker, @@ -511,6 +524,7 @@ void debug( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void debug( Marker marker, @@ -531,6 +545,7 @@ void debug( * * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void debug(String message, Object p0); @@ -540,6 +555,7 @@ void debug( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void debug(String message, Object p0, Object p1); @@ -550,6 +566,7 @@ void debug( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void debug(String message, Object p0, Object p1, Object p2); @@ -561,6 +578,7 @@ void debug( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void debug(String message, Object p0, Object p1, Object p2, Object p3); @@ -573,6 +591,7 @@ void debug( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void debug(String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -586,6 +605,7 @@ void debug( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void debug(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -600,6 +620,7 @@ void debug( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void debug(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -615,6 +636,7 @@ void debug( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void debug(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7); @@ -631,6 +653,7 @@ void debug( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void debug( String message, @@ -658,6 +681,7 @@ void debug( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void debug( String message, @@ -675,7 +699,7 @@ void debug( /** * Logs entry to a method. Used when the method in question has no parameters or when the parameters should not be * logged. - * @deprecated Use {@link #traceEntry()} instead which performs the same function. + * @deprecated Since 2.6, use {@link #traceEntry()} instead which performs the same function. */ @Deprecated void entry(); @@ -697,7 +721,7 @@ void debug( *

* * @param params The parameters to the method. - * @deprecated Use {@link #traceEntry(String, Object...)} instead which performs the same function. + * @deprecated since 2.11.2, use {@link #traceEntry(String, Object...)} instead which performs the same function. */ @Deprecated void entry(Object... params); @@ -747,6 +771,7 @@ void debug( * * @param marker the marker data specific to this log statement. * @param message the message CharSequence to log. + * @since 2.6 */ void error(Marker marker, CharSequence message); @@ -757,6 +782,7 @@ void debug( * @param marker the marker data specific to this log statement. * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void error(Marker marker, CharSequence message, Throwable throwable); @@ -879,6 +905,7 @@ void debug( * Logs a message CharSequence with the {@link Level#ERROR ERROR} level. * * @param message the message CharSequence to log. + * @since 2.6 */ void error(CharSequence message); @@ -888,6 +915,7 @@ void debug( * * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void error(CharSequence message, Throwable throwable); @@ -968,6 +996,7 @@ void debug( * @param marker the marker data specific to this log statement * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void error(Marker marker, String message, Object p0); @@ -978,6 +1007,7 @@ void debug( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void error(Marker marker, String message, Object p0, Object p1); @@ -989,6 +1019,7 @@ void debug( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void error(Marker marker, String message, Object p0, Object p1, Object p2); @@ -1001,6 +1032,7 @@ void debug( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void error(Marker marker, String message, Object p0, Object p1, Object p2, Object p3); @@ -1014,6 +1046,7 @@ void debug( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void error(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -1028,6 +1061,7 @@ void debug( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void error(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -1043,6 +1077,7 @@ void debug( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void error( Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -1060,6 +1095,7 @@ void error( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void error( Marker marker, @@ -1087,6 +1123,7 @@ void error( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void error( Marker marker, @@ -1116,6 +1153,7 @@ void error( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void error( Marker marker, @@ -1136,6 +1174,7 @@ void error( * * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void error(String message, Object p0); @@ -1145,6 +1184,7 @@ void error( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void error(String message, Object p0, Object p1); @@ -1155,6 +1195,7 @@ void error( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void error(String message, Object p0, Object p1, Object p2); @@ -1166,6 +1207,7 @@ void error( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void error(String message, Object p0, Object p1, Object p2, Object p3); @@ -1178,6 +1220,7 @@ void error( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void error(String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -1191,6 +1234,7 @@ void error( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void error(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -1205,6 +1249,7 @@ void error( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void error(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -1220,6 +1265,7 @@ void error( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void error(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7); @@ -1236,6 +1282,7 @@ void error( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void error( String message, @@ -1263,6 +1310,7 @@ void error( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void error( String message, @@ -1279,7 +1327,7 @@ void error( /** * Logs exit from a method. Used for methods that do not return anything. - * @deprecated Use {@link #traceExit()} instead which performs the same function. + * @deprecated Since 2.6, use {@link #traceExit()} instead which performs the same function. */ @Deprecated void exit(); @@ -1294,7 +1342,7 @@ void error( * @param The type of the parameter and object being returned. * @param result The result being returned from the method call. * @return the result. - * @deprecated Use {@link #traceExit(Object)} instead which performs the same function. + * @deprecated Since 2.6, use {@link #traceExit(Object)} instead which performs the same function. */ @Deprecated R exit(R result); @@ -1344,6 +1392,7 @@ void error( * * @param marker The marker data specific to this log statement. * @param message the message CharSequence to log. + * @since 2.6 */ void fatal(Marker marker, CharSequence message); @@ -1354,6 +1403,7 @@ void error( * @param marker The marker data specific to this log statement. * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void fatal(Marker marker, CharSequence message, Throwable throwable); @@ -1476,6 +1526,7 @@ void error( * Logs a message CharSequence with the {@link Level#FATAL FATAL} level. * * @param message the message CharSequence to log. + * @since 2.6 */ void fatal(CharSequence message); @@ -1485,6 +1536,7 @@ void error( * * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void fatal(CharSequence message, Throwable throwable); @@ -1565,6 +1617,7 @@ void error( * @param marker the marker data specific to this log statement * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void fatal(Marker marker, String message, Object p0); @@ -1575,6 +1628,7 @@ void error( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void fatal(Marker marker, String message, Object p0, Object p1); @@ -1586,6 +1640,7 @@ void error( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void fatal(Marker marker, String message, Object p0, Object p1, Object p2); @@ -1598,6 +1653,7 @@ void error( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void fatal(Marker marker, String message, Object p0, Object p1, Object p2, Object p3); @@ -1611,6 +1667,7 @@ void error( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void fatal(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -1625,6 +1682,7 @@ void error( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void fatal(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -1640,6 +1698,7 @@ void error( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void fatal( Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -1657,6 +1716,7 @@ void fatal( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void fatal( Marker marker, @@ -1684,6 +1744,7 @@ void fatal( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void fatal( Marker marker, @@ -1713,6 +1774,7 @@ void fatal( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void fatal( Marker marker, @@ -1733,6 +1795,7 @@ void fatal( * * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void fatal(String message, Object p0); @@ -1742,6 +1805,7 @@ void fatal( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void fatal(String message, Object p0, Object p1); @@ -1752,6 +1816,7 @@ void fatal( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void fatal(String message, Object p0, Object p1, Object p2); @@ -1763,6 +1828,7 @@ void fatal( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void fatal(String message, Object p0, Object p1, Object p2, Object p3); @@ -1775,6 +1841,7 @@ void fatal( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void fatal(String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -1788,6 +1855,7 @@ void fatal( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void fatal(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -1802,6 +1870,7 @@ void fatal( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void fatal(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -1817,6 +1886,7 @@ void fatal( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void fatal(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7); @@ -1833,6 +1903,7 @@ void fatal( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void fatal( String message, @@ -1860,6 +1931,7 @@ void fatal( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void fatal( String message, @@ -1899,7 +1971,7 @@ void fatal( * Gets the flow message factory used to convert messages into flow messages. * * @return the flow message factory, as an instance of {@link FlowMessageFactory}. - * @since 2.20 + * @since 2.20.0 */ FlowMessageFactory getFlowMessageFactory(); @@ -1955,6 +2027,7 @@ void fatal( * * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. + * @since 2.6 */ void info(Marker marker, CharSequence message); @@ -1965,6 +2038,7 @@ void fatal( * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void info(Marker marker, CharSequence message, Throwable throwable); @@ -2176,6 +2250,7 @@ void fatal( * @param marker the marker data specific to this log statement * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void info(Marker marker, String message, Object p0); @@ -2186,6 +2261,7 @@ void fatal( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void info(Marker marker, String message, Object p0, Object p1); @@ -2197,6 +2273,7 @@ void fatal( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void info(Marker marker, String message, Object p0, Object p1, Object p2); @@ -2209,6 +2286,7 @@ void fatal( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void info(Marker marker, String message, Object p0, Object p1, Object p2, Object p3); @@ -2222,6 +2300,7 @@ void fatal( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void info(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -2236,6 +2315,7 @@ void fatal( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void info(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -2251,6 +2331,7 @@ void fatal( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void info( Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -2268,6 +2349,7 @@ void info( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void info( Marker marker, @@ -2295,6 +2377,7 @@ void info( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void info( Marker marker, @@ -2324,6 +2407,7 @@ void info( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void info( Marker marker, @@ -2344,6 +2428,7 @@ void info( * * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void info(String message, Object p0); @@ -2353,6 +2438,7 @@ void info( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void info(String message, Object p0, Object p1); @@ -2363,6 +2449,7 @@ void info( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void info(String message, Object p0, Object p1, Object p2); @@ -2374,6 +2461,7 @@ void info( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void info(String message, Object p0, Object p1, Object p2, Object p3); @@ -2386,6 +2474,7 @@ void info( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void info(String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -2399,6 +2488,7 @@ void info( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void info(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -2413,6 +2503,7 @@ void info( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void info(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -2428,6 +2519,7 @@ void info( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void info(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7); @@ -2444,6 +2536,7 @@ void info( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void info( String message, @@ -2471,6 +2564,7 @@ void info( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void info( String message, @@ -2651,6 +2745,7 @@ void info( * @param level the logging level * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. + * @since 2.6 */ void log(Level level, Marker marker, CharSequence message); @@ -2662,6 +2757,7 @@ void info( * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void log(Level level, Marker marker, CharSequence message, Throwable throwable); @@ -2795,6 +2891,7 @@ void info( * * @param level the logging level * @param message the message CharSequence to log. + * @since 2.6 */ void log(Level level, CharSequence message); @@ -2805,6 +2902,7 @@ void info( * @param level the logging level * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void log(Level level, CharSequence message, Throwable throwable); @@ -2893,6 +2991,7 @@ void info( * @param marker the marker data specific to this log statement * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void log(Level level, Marker marker, String message, Object p0); @@ -2904,6 +3003,7 @@ void info( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void log(Level level, Marker marker, String message, Object p0, Object p1); @@ -2916,6 +3016,7 @@ void info( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void log(Level level, Marker marker, String message, Object p0, Object p1, Object p2); @@ -2929,6 +3030,7 @@ void info( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void log(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3); @@ -2943,6 +3045,7 @@ void info( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void log(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -2958,6 +3061,7 @@ void info( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void log( Level level, @@ -2983,6 +3087,7 @@ void log( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void log( Level level, @@ -3010,6 +3115,7 @@ void log( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void log( Level level, @@ -3039,6 +3145,7 @@ void log( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void log( Level level, @@ -3070,6 +3177,7 @@ void log( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void log( Level level, @@ -3092,6 +3200,7 @@ void log( * @param level the logging level * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void log(Level level, String message, Object p0); @@ -3102,6 +3211,7 @@ void log( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void log(Level level, String message, Object p0, Object p1); @@ -3113,6 +3223,7 @@ void log( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void log(Level level, String message, Object p0, Object p1, Object p2); @@ -3125,6 +3236,7 @@ void log( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void log(Level level, String message, Object p0, Object p1, Object p2, Object p3); @@ -3138,6 +3250,7 @@ void log( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void log(Level level, String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -3152,6 +3265,7 @@ void log( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void log(Level level, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -3167,6 +3281,7 @@ void log( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void log(Level level, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -3183,6 +3298,7 @@ void log( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void log( Level level, @@ -3210,6 +3326,7 @@ void log( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void log( Level level, @@ -3239,6 +3356,7 @@ void log( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void log( Level level, @@ -3346,6 +3464,7 @@ void log( * * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. + * @since 2.6 */ void trace(Marker marker, CharSequence message); @@ -3357,6 +3476,7 @@ void log( * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. * @see #debug(String) + * @since 2.6 */ void trace(Marker marker, CharSequence message, Throwable throwable); @@ -3573,6 +3693,7 @@ void log( * @param marker the marker data specific to this log statement * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void trace(Marker marker, String message, Object p0); @@ -3583,6 +3704,7 @@ void log( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void trace(Marker marker, String message, Object p0, Object p1); @@ -3594,6 +3716,7 @@ void log( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void trace(Marker marker, String message, Object p0, Object p1, Object p2); @@ -3606,6 +3729,7 @@ void log( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void trace(Marker marker, String message, Object p0, Object p1, Object p2, Object p3); @@ -3619,6 +3743,7 @@ void log( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void trace(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -3633,6 +3758,7 @@ void log( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void trace(Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -3648,6 +3774,7 @@ void log( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void trace( Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -3665,6 +3792,7 @@ void trace( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void trace( Marker marker, @@ -3692,6 +3820,7 @@ void trace( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void trace( Marker marker, @@ -3721,6 +3850,7 @@ void trace( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void trace( Marker marker, @@ -3741,6 +3871,7 @@ void trace( * * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. + * @since 2.6 */ void trace(String message, Object p0); @@ -3750,6 +3881,7 @@ void trace( * @param message the message to log; the format depends on the message factory. * @param p0 parameter to the message. * @param p1 parameter to the message. + * @since 2.6 */ void trace(String message, Object p0, Object p1); @@ -3760,6 +3892,7 @@ void trace( * @param p0 parameter to the message. * @param p1 parameter to the message. * @param p2 parameter to the message. + * @since 2.6 */ void trace(String message, Object p0, Object p1, Object p2); @@ -3771,6 +3904,7 @@ void trace( * @param p1 parameter to the message. * @param p2 parameter to the message. * @param p3 parameter to the message. + * @since 2.6 */ void trace(String message, Object p0, Object p1, Object p2, Object p3); @@ -3783,6 +3917,7 @@ void trace( * @param p2 parameter to the message. * @param p3 parameter to the message. * @param p4 parameter to the message. + * @since 2.6 */ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -3796,6 +3931,7 @@ void trace( * @param p3 parameter to the message. * @param p4 parameter to the message. * @param p5 parameter to the message. + * @since 2.6 */ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5); @@ -3810,6 +3946,7 @@ void trace( * @param p4 parameter to the message. * @param p5 parameter to the message. * @param p6 parameter to the message. + * @since 2.6 */ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6); @@ -3825,6 +3962,7 @@ void trace( * @param p5 parameter to the message. * @param p6 parameter to the message. * @param p7 parameter to the message. + * @since 2.6 */ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7); @@ -3841,6 +3979,7 @@ void trace( * @param p6 parameter to the message. * @param p7 parameter to the message. * @param p8 parameter to the message. + * @since 2.6 */ void trace( String message, @@ -3868,6 +4007,7 @@ void trace( * @param p7 parameter to the message. * @param p8 parameter to the message. * @param p9 parameter to the message. + * @since 2.6 */ void trace( String message, @@ -4110,6 +4250,7 @@ void trace( * * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. + * @since 2.6 */ void warn(Marker marker, CharSequence message); @@ -4120,6 +4261,7 @@ void trace( * @param marker the marker data specific to this log statement * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void warn(Marker marker, CharSequence message, Throwable throwable); @@ -4242,6 +4384,7 @@ void trace( * Logs a message CharSequence with the {@link Level#WARN WARN} level. * * @param message the message CharSequence to log. + * @since 2.6 */ void warn(CharSequence message); @@ -4251,6 +4394,7 @@ void trace( * * @param message the message CharSequence to log. * @param throwable the {@code Throwable} to log, including its stack trace. + * @since 2.6 */ void warn(CharSequence message, Throwable throwable); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java b/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java index d919b3130a1..46dba0dd7d8 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java @@ -214,6 +214,8 @@ private ThreadContext() { /** * Consider private, used for testing. + * + * @since 2.20.0 */ public static void init() { final PropertiesUtil properties = PropertiesUtil.getProperties(); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/DefaultFlowMessageFactory.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/DefaultFlowMessageFactory.java index 57dbd29b8ab..7b93274578e 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/DefaultFlowMessageFactory.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/DefaultFlowMessageFactory.java @@ -32,6 +32,9 @@ public class DefaultFlowMessageFactory implements FlowMessageFactory, Serializab private static final String ENTRY_DEFAULT_PREFIX = "Enter"; private static final long serialVersionUID = 8578655591131397576L; + /** + * @since 2.24.0 + */ public static final FlowMessageFactory INSTANCE = new DefaultFlowMessageFactory(); private final String entryText; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/FlowMessageFactory.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/FlowMessageFactory.java index e2c7f26053e..d53dc872d46 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/FlowMessageFactory.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/FlowMessageFactory.java @@ -28,7 +28,7 @@ public interface FlowMessageFactory { * @param message format string * @param params parameters * @return the new entry message - * @since 2.20 + * @since 2.20.0 */ EntryMessage newEntryMessage(String message, Object... params); @@ -46,7 +46,7 @@ public interface FlowMessageFactory { * @param format a format string * @param result the return value * @return the new exit message - * @since 2.20 + * @since 2.20.0 */ ExitMessage newExitMessage(String format, Object result); @@ -55,7 +55,7 @@ public interface FlowMessageFactory { * * @param message the original entry message * @return the new exit message - * @since 2.20 + * @since 2.20.0 */ ExitMessage newExitMessage(Message message); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java index 7ce23b3d5ae..f1144cee624 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java @@ -79,6 +79,7 @@ public enum MapFormat { * * @param format a MapFormat name * @return a MapFormat + * @since 2.8 */ public static MapFormat lookupIgnoreCase(final String format) { return XML.name().equalsIgnoreCase(format) @@ -96,6 +97,7 @@ public static MapFormat lookupIgnoreCase(final String format) { * All {@code MapFormat} names. * * @return All {@code MapFormat} names. + * @since 2.8 */ public static String[] names() { return new String[] {XML.name(), JSON.name(), JAVA.name(), JAVA_UNQUOTED.name()}; @@ -115,6 +117,7 @@ public MapMessage() { * Constructs a new instance. * * @param initialCapacity the initial capacity. + * @since 2.9.0 */ public MapMessage(final int initialCapacity) { this.data = new SortedArrayStringMap(initialCapacity); @@ -189,7 +192,7 @@ public void clear() { * * @param key the key whose presence to check. May be {@code null}. * @return {@code true} if this data structure contains the specified key, {@code false} otherwise - * @since 2.9 + * @since 2.9.0 */ public boolean containsKey(final String key) { return data.containsKey(key); @@ -277,10 +280,9 @@ public String asString(final String format) { * @param action The action to be performed for each key-value pair in this collection * @param type of the consumer value * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications - * to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or - * {@link #forEach(TriConsumer, Object)}. + * to this data structure while iterating over the contents. * @see ReadOnlyStringMap#forEach(BiConsumer) - * @since 2.9 + * @since 2.9.0 */ public void forEach(final BiConsumer action) { data.forEach(action); @@ -306,10 +308,9 @@ public void forEach(final BiConsumer action) { * @param type of the consumer value * @param type of the third parameter * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications - * to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or - * {@link #forEach(TriConsumer, Object)}. + * to this data structure while iterating over the contents. * @see ReadOnlyStringMap#forEach(TriConsumer, Object) - * @since 2.9 + * @since 2.9.0 */ public void forEach(final TriConsumer action, final S state) { data.forEach(action, state); @@ -419,6 +420,9 @@ protected void asJson(final StringBuilder sb) { MapMessageJsonFormatter.format(sb, data); } + /** + * @since 2.11.2 + */ protected void asJavaUnquoted(final StringBuilder sb) { asJava(sb, false); } @@ -502,7 +506,7 @@ public Throwable getThrowable() { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final boolean value) { // do nothing @@ -511,7 +515,7 @@ protected void validate(final String key, final boolean value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final byte value) { // do nothing @@ -520,7 +524,7 @@ protected void validate(final String key, final byte value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final char value) { // do nothing @@ -529,7 +533,7 @@ protected void validate(final String key, final char value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final double value) { // do nothing @@ -538,7 +542,7 @@ protected void validate(final String key, final double value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final float value) { // do nothing @@ -547,7 +551,7 @@ protected void validate(final String key, final float value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final int value) { // do nothing @@ -556,7 +560,7 @@ protected void validate(final String key, final int value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final long value) { // do nothing @@ -565,7 +569,7 @@ protected void validate(final String key, final long value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final Object value) { // do nothing @@ -574,7 +578,7 @@ protected void validate(final String key, final Object value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final short value) { // do nothing @@ -583,7 +587,7 @@ protected void validate(final String key, final short value) { /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final String value) { // do nothing @@ -594,7 +598,7 @@ protected void validate(final String key, final String value) { * * @param candidateKey The candidate key. * @return The candidate key. - * @since 2.12 + * @since 2.12.0 */ protected String toKey(final String candidateKey) { return candidateKey; @@ -605,7 +609,7 @@ protected String toKey(final String candidateKey) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final boolean value) { @@ -620,7 +624,7 @@ public M with(final String candidateKey, final boolean value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final byte value) { @@ -635,7 +639,7 @@ public M with(final String candidateKey, final byte value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final char value) { @@ -650,7 +654,7 @@ public M with(final String candidateKey, final char value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final double value) { @@ -665,7 +669,7 @@ public M with(final String candidateKey, final double value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final float value) { @@ -680,7 +684,7 @@ public M with(final String candidateKey, final float value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final int value) { @@ -695,7 +699,7 @@ public M with(final String candidateKey, final int value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final long value) { @@ -710,7 +714,7 @@ public M with(final String candidateKey, final long value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final Object value) { @@ -725,7 +729,7 @@ public M with(final String candidateKey, final Object value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return this object - * @since 2.9 + * @since 2.9.0 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final short value) { @@ -740,6 +744,7 @@ public M with(final String candidateKey, final short value) { * @param candidateKey The name of the data item. * @param value The value of the data item. * @return {@code this} + * @since 2.5 */ @SuppressWarnings("unchecked") public M with(final String candidateKey, final String value) { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/MessageCollectionMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/MessageCollectionMessage.java index 1ebd438f3fa..0b683a3c98d 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/MessageCollectionMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/MessageCollectionMessage.java @@ -19,5 +19,6 @@ /** * A Message that is a collection of Messages. * @param The Message type. + * @since 2.9.0 */ public interface MessageCollectionMessage extends Message, Iterable {} diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterConsumer.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterConsumer.java index 199d0b4f6a3..7bbd8120d3e 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterConsumer.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterConsumer.java @@ -26,7 +26,7 @@ * * @param state data * @see ReusableMessage - * @since 2.11 + * @since 2.11.0 */ public interface ParameterConsumer { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterVisitable.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterVisitable.java index f0ce3e820f1..b9dfb918efe 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterVisitable.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterVisitable.java @@ -22,7 +22,7 @@ * Allows message parameters to be iterated over without any allocation * or memory copies. * - * @since 2.11 + * @since 2.11.0 */ @PerformanceSensitive("allocation") public interface ParameterVisitable { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedMessage.java index 4da3642cca1..a93b495e42e 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedMessage.java @@ -112,7 +112,7 @@ private static final class FormatBufferHolder { * @param pattern a formatting pattern * @param args arguments to be formatted * @param throwable a {@link Throwable} - * @deprecated Use {@link #ParameterizedMessage(String, Object[], Throwable)} instead + * @deprecated Since 2.6, use {@link #ParameterizedMessage(String, Object[], Throwable)} instead */ @InlineMe( replacement = "this(pattern, Arrays.stream(args).toArray(Object[]::new), throwable)", diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedNoReferenceMessageFactory.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedNoReferenceMessageFactory.java index d27f7d47659..88442d18551 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedNoReferenceMessageFactory.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedNoReferenceMessageFactory.java @@ -38,6 +38,7 @@ * This class does not implement any {@link MessageFactory2} methods and lets the superclass funnel those calls * through {@link #newMessage(String, Object...)}. *

+ * @since 2.5 */ public final class ParameterizedNoReferenceMessageFactory extends AbstractMessageFactory { private static final long serialVersionUID = 5027639245636870500L; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableMessageFactory.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableMessageFactory.java index 92712ac8cfc..1e504755587 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableMessageFactory.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableMessageFactory.java @@ -37,7 +37,7 @@ public final class ReusableMessageFactory implements MessageFactory2, Serializable { /** - * Instance of ReusableMessageFactory.. + * Instance of ReusableMessageFactory. */ public static final ReusableMessageFactory INSTANCE = new ReusableMessageFactory(); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableObjectMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableObjectMessage.java index 08c86259358..aed52d13c59 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableObjectMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableObjectMessage.java @@ -131,6 +131,9 @@ public Message memento() { return new ObjectMessage(obj); } + /** + * @since 2.11.1 + */ @Override public void clear() { obj = null; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableParameterizedMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableParameterizedMessage.java index 053a5bf8f1c..d3734eeedd1 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableParameterizedMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableParameterizedMessage.java @@ -135,18 +135,27 @@ private static Throwable determineThrowable(final Object[] args, final int argCo return null; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set(final String messagePattern, final Object... arguments) { init(messagePattern, arguments == null ? 0 : arguments.length, arguments); varargs = arguments; return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set(final String messagePattern, final Object p0) { params[0] = p0; init(messagePattern, 1, params); return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set(final String messagePattern, final Object p0, final Object p1) { params[0] = p0; params[1] = p1; @@ -154,6 +163,9 @@ public ReusableParameterizedMessage set(final String messagePattern, final Objec return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set( final String messagePattern, final Object p0, final Object p1, final Object p2) { params[0] = p0; @@ -163,6 +175,9 @@ public ReusableParameterizedMessage set( return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set( final String messagePattern, final Object p0, final Object p1, final Object p2, final Object p3) { params[0] = p0; @@ -173,6 +188,9 @@ public ReusableParameterizedMessage set( return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set( final String messagePattern, final Object p0, @@ -189,6 +207,9 @@ public ReusableParameterizedMessage set( return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set( final String messagePattern, final Object p0, @@ -207,6 +228,9 @@ public ReusableParameterizedMessage set( return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set( final String messagePattern, final Object p0, @@ -227,6 +251,9 @@ public ReusableParameterizedMessage set( return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set( final String messagePattern, final Object p0, @@ -249,6 +276,9 @@ public ReusableParameterizedMessage set( return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set( final String messagePattern, final Object p0, @@ -273,6 +303,9 @@ public ReusableParameterizedMessage set( return this; } + /** + * @since 2.24.0 + */ public ReusableParameterizedMessage set( final String messagePattern, final Object p0, @@ -369,6 +402,9 @@ public String toString() { + ", throwableProvided=" + (getThrowable() != null) + ']'; } + /** + * @since 2.11.1 + */ @Override public void clear() { // LOG4J2-1583 // This method does not clear parameter values, those are expected to be swapped to a diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableSimpleMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableSimpleMessage.java index a2722709c93..824e9d3a98a 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableSimpleMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ReusableSimpleMessage.java @@ -105,6 +105,9 @@ public CharSequence subSequence(final int start, final int end) { return charSequence.subSequence(start, end); } + /** + * @since 2.11.1 + */ @Override public void clear() { charSequence = null; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/StringMapMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/StringMapMessage.java index d2d642a0c4b..545e3533dd3 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/StringMapMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/StringMapMessage.java @@ -22,7 +22,7 @@ /** * A {@link StringMapMessage} typed to {@link String}-only values. This is like the MapMessage class before 2.9. * - * @since 2.9 + * @since 2.9.0 */ @PerformanceSensitive("allocation") @AsynchronouslyFormattable diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataCollectionMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataCollectionMessage.java index fbe760bfa6d..22a295ad1cb 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataCollectionMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataCollectionMessage.java @@ -23,6 +23,7 @@ /** * A collection of StructuredDataMessages. + * @since 2.9.0 */ public class StructuredDataCollectionMessage implements StringBuilderFormattable, MessageCollectionMessage { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataId.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataId.java index 306e18f1277..f8b65d9a81c 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataId.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataId.java @@ -46,6 +46,7 @@ public class StructuredDataId implements Serializable, StringBuilderFormattable /** * Reserved enterprise number. + * @since 2.18.0 */ public static final String RESERVED = "-1"; @@ -61,7 +62,7 @@ public class StructuredDataId implements Serializable, StringBuilderFormattable /** * Creates a StructuredDataId based on the name. * @param name The Structured Data Element name (maximum length is 32) - * @since 2.9 + * @since 2.9.0 */ public StructuredDataId(final String name) { this(name, null, null, MAX_LENGTH); @@ -71,7 +72,7 @@ public StructuredDataId(final String name) { * Creates a StructuredDataId based on the name. * @param name The Structured Data Element name. * @param maxLength The maximum length of the name. - * @since 2.9 + * @since 2.9.0 */ public StructuredDataId(final String name, final int maxLength) { this(name, null, null, maxLength); @@ -94,7 +95,7 @@ public StructuredDataId(final String name, final String[] required, final String * @param required The list of keys that are required for this id. * @param optional The list of keys that are optional for this id. * @param maxLength The maximum length of the id's name. - * @since 2.9 + * @since 2.9.0 */ public StructuredDataId(final String name, final String[] required, final String[] optional, int maxLength) { int index = -1; @@ -127,6 +128,7 @@ public StructuredDataId(final String name, final String[] required, final String * @param enterpriseNumber The enterprise number. * @param required The list of keys that are required for this id. * @param optional The list of keys that are optional for this id. + * @since 2.18.0 */ public StructuredDataId( final String name, final String enterpriseNumber, final String[] required, final String[] optional) { @@ -140,7 +142,7 @@ public StructuredDataId( * @param enterpriseNumber The enterprise number. * @param required The list of keys that are required for this id. * @param optional The list of keys that are optional for this id. - * @deprecated Use {@link #StructuredDataId(String, String, String[], String[])} instead. + * @deprecated Since 2.18.0, use {@link #StructuredDataId(String, String, String[], String[])} instead. */ @Deprecated @InlineMe(replacement = "this(name, String.valueOf(enterpriseNumber), required, optional)") @@ -157,7 +159,7 @@ public StructuredDataId( * @param required The list of keys that are required for this id. * @param optional The list of keys that are optional for this id. * @param maxLength The maximum length of the StructuredData Id key. - * @since 2.9 + * @since 2.18.0 */ public StructuredDataId( final String name, @@ -192,8 +194,8 @@ public StructuredDataId( * @param required The list of keys that are required for this id. * @param optional The list of keys that are optional for this id. * @param maxLength The maximum length of the StructuredData Id key. - * @since 2.9 - * @deprecated Use {@link #StructuredDataId(String, String, String[], String[], int)} instead. + * @since 2.9.0 + * @deprecated Since 2.18.0, use {@link #StructuredDataId(String, String, String[], String[], int)} instead. */ @InlineMe(replacement = "this(name, String.valueOf(enterpriseNumber), required, optional, maxLength)") @Deprecated @@ -225,6 +227,7 @@ public StructuredDataId makeId(final StructuredDataId id) { * @param defaultId The default id to use if this StructuredDataId doesn't have a name. * @param anEnterpriseNumber The enterprise number. * @return a StructuredDataId. + * @since 2.18.0 */ public StructuredDataId makeId(final String defaultId, final String anEnterpriseNumber) { String id; @@ -252,7 +255,7 @@ public StructuredDataId makeId(final String defaultId, final String anEnterprise * @param defaultId The default id to use if this StructuredDataId doesn't have a name. * @param anEnterpriseNumber The enterprise number. * @return a StructuredDataId. - * @deprecated Use {@link StructuredDataId#makeId(String, String)} instead + * @deprecated Since 2.18.0, use {@link StructuredDataId#makeId(String, String)} instead */ @Deprecated // This method should have been `final` from the start, we don't expect anyone to override it. @@ -292,6 +295,7 @@ public String getName() { * Returns the enterprise number. * * @return the enterprise number. + * @since 2.18.0 */ public String getEnterpriseNumber() { return enterpriseNumber; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataMessage.java index 75ca3ef3010..46b757d54f2 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataMessage.java @@ -73,7 +73,7 @@ public StructuredDataMessage(final String id, final String msg, final String typ * @param msg The message. * @param type The message type. * @param maxLength The maximum length of keys; - * @since 2.9 + * @since 2.9.0 */ public StructuredDataMessage(final String id, final String msg, final String type, final int maxLength) { this.id = new StructuredDataId(id, null, null, maxLength); @@ -102,7 +102,7 @@ public StructuredDataMessage(final String id, final String msg, final String typ * @param type The message type. * @param data The StructuredData map. * @param maxLength The maximum length of keys; - * @since 2.9 + * @since 2.9.0 */ public StructuredDataMessage( final String id, final String msg, final String type, final Map data, final int maxLength) { @@ -129,7 +129,7 @@ public StructuredDataMessage(final StructuredDataId id, final String msg, final * @param msg The message. * @param type The message type. * @param maxLength The maximum length of keys; - * @since 2.9 + * @since 2.9.0 */ public StructuredDataMessage(final StructuredDataId id, final String msg, final String type, final int maxLength) { this.id = id; @@ -159,7 +159,7 @@ public StructuredDataMessage( * @param type The message type. * @param data The StructuredData map. * @param maxLength The maximum length of keys; - * @since 2.9 + * @since 2.9.0 */ public StructuredDataMessage( final StructuredDataId id, @@ -318,6 +318,7 @@ public final String asString(final Format format, final StructuredDataId structu * @param structuredDataId The SD-ID as described in RFC 5424. If null the value in the StructuredData * will be used. * @param sb The StringBuilder to append the formatted message to. + * @since 2.8 */ public final void asString(final Format format, final StructuredDataId structuredDataId, final StringBuilder sb) { final boolean full = Format.FULL.equals(format); @@ -520,6 +521,9 @@ protected void validate(final String key, final String value) { validateKey(key); } + /** + * @since 2.9.0 + */ protected void validateKey(final String key) { if (maxLength > 0 && key.length() > maxLength) { throw new IllegalArgumentException( diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ThreadDumpMessage.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ThreadDumpMessage.java index 4ddbdc5c5f4..88ac55fca8c 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ThreadDumpMessage.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ThreadDumpMessage.java @@ -162,8 +162,10 @@ protected Object readResolve() { *

* Implementations of this class are loaded via the standard java Service Provider interface. *

+ * + * @since 2.9.0 */ - public static interface ThreadInfoFactory { + public interface ThreadInfoFactory { Map createThreadInfo(); } diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/message/ThreadInformation.java b/log4j-api/src/main/java/org/apache/logging/log4j/message/ThreadInformation.java index 68e9e79ff51..c9b1d04aa9e 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/message/ThreadInformation.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/message/ThreadInformation.java @@ -18,6 +18,8 @@ /** * Interface used to print basic or extended thread information. + * + * @since 2.9.0 */ public interface ThreadInformation { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/simple/SimpleLoggerContextFactory.java b/log4j-api/src/main/java/org/apache/logging/log4j/simple/SimpleLoggerContextFactory.java index 962c7a7651f..163259f2511 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/simple/SimpleLoggerContextFactory.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/simple/SimpleLoggerContextFactory.java @@ -27,6 +27,8 @@ public class SimpleLoggerContextFactory implements LoggerContextFactory { /** * Singleton instance. + * + * @since 2.17.2 */ public static final SimpleLoggerContextFactory INSTANCE = new SimpleLoggerContextFactory(); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java index 06d99f3f15a..ebe5e5c6680 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java @@ -89,6 +89,7 @@ public abstract class AbstractLogger implements ExtendedLogger, LocationAwareLog /** * The default FlowMessageFactory class. + * @since 2.6 */ public static final Class DEFAULT_FLOW_MESSAGE_FACTORY_CLASS = DefaultFlowMessageFactory.class; @@ -137,6 +138,7 @@ public AbstractLogger(final String name, final MessageFactory messageFactory) { * @param name the logger name (if null, will be derived from this class) * @param messageFactory the {@link Message} factory (if null, {@link ParameterizedMessageFactory} will be used) * @param flowMessageFactory the {@link org.apache.logging.log4j.message.FlowMessage} factory (if null, {@link DefaultFlowMessageFactory} will be used) + * @since 2.24.0 */ protected AbstractLogger( final String name, final MessageFactory messageFactory, final FlowMessageFactory flowMessageFactory) { @@ -584,6 +586,7 @@ public void debug( * @param fqcn The fully qualified class name of the caller. * @param format Format String for the parameters. * @param paramSuppliers The Suppliers of the parameters. + * @since 2.6 */ @SuppressWarnings("deprecation") protected EntryMessage enter(final String fqcn, final String format, final Supplier... paramSuppliers) { @@ -605,6 +608,7 @@ protected EntryMessage enter(final String fqcn, final String format, final Suppl * @param fqcn The fully qualified class name of the caller. * @param format The format String for the parameters. * @param paramSuppliers The parameters to the method. + * @since 2.6 */ @Deprecated protected EntryMessage enter(final String fqcn, final String format, final MessageSupplier... paramSuppliers) { @@ -621,6 +625,7 @@ protected EntryMessage enter(final String fqcn, final String format, final Messa * @param fqcn The fully qualified class name of the caller. * @param format The format String for the parameters. * @param params The parameters to the method. + * @since 2.6 */ protected EntryMessage enter(final String fqcn, final String format, final Object... params) { EntryMessage entryMsg = null; @@ -640,6 +645,7 @@ protected EntryMessage enter(final String fqcn, final String format, final Objec * * @param fqcn The fully qualified class name of the caller. * @param messageSupplier The Supplier of the Message. + * @since 2.6 */ @Deprecated protected EntryMessage enter(final String fqcn, final MessageSupplier messageSupplier) { @@ -702,10 +708,16 @@ protected void entry(final String fqcn, final Object... params) { } } + /** + * @since 2.6 + */ protected EntryMessage entryMsg(final String format, final Object... params) { return flowMessageFactory.newEntryMessage(format, params); } + /** + * @since 2.6 + */ protected EntryMessage entryMsg(final String format, final MessageSupplier... paramSuppliers) { final int count = paramSuppliers == null ? 0 : paramSuppliers.length; final Object[] params = new Object[count]; @@ -715,7 +727,9 @@ protected EntryMessage entryMsg(final String format, final MessageSupplier... pa return entryMsg(format, params); } - @SuppressWarnings("deprecation") + /** + * @since 2.6 + */ protected EntryMessage entryMsg(final String format, final Supplier... paramSuppliers) { return entryMsg(format, LambdaUtil.getAll(paramSuppliers)); } @@ -1109,6 +1123,7 @@ protected R exit(final String fqcn, final R result) { * @param The type of the parameter and object being returned. * @param result The result being returned from the method call. * @return the return value passed to this method. + * @since 2.6 */ protected R exit(final String fqcn, final String format, final R result) { if (isEnabled(Level.TRACE, EXIT_MARKER, (CharSequence) null, null)) { @@ -1117,6 +1132,9 @@ protected R exit(final String fqcn, final String format, final R result) { return result; } + /** + * @since 2.6 + */ protected Message exitMsg(final String format, final Object result) { return flowMessageFactory.newExitMessage(format, result); } @@ -2570,6 +2588,9 @@ public void logIfEnabled( } } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2588,6 +2609,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, messageFactory.newMessage(message), throwable); } + /** + * @since 2.4 + */ protected void logMessage( final String fqcn, final Level level, @@ -2600,7 +2624,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, message, effectiveThrowable); } - @SuppressWarnings("deprecation") + /** + * @since 2.4 + */ protected void logMessage( final String fqcn, final Level level, @@ -2633,12 +2659,18 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, final Marker marker, final String message, final Object p0) { final Message msg = messageFactory.newMessage(message, p0); logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2650,6 +2682,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2662,6 +2697,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2675,6 +2713,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2689,6 +2730,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2704,6 +2748,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2720,6 +2767,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2737,6 +2787,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2755,6 +2808,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } + /** + * @since 2.6 + */ protected void logMessage( final String fqcn, final Level level, @@ -2774,7 +2830,9 @@ protected void logMessage( logMessageSafely(fqcn, level, marker, msg, msg.getThrowable()); } - @SuppressWarnings("deprecation") + /** + * @since 2.4 + */ protected void logMessage( final String fqcn, final Level level, @@ -2804,6 +2862,9 @@ public void logMessage( } } + /** + * @since 2.12.1 + */ protected void log( final Level level, final Marker marker, @@ -2889,6 +2950,7 @@ private static void decrementRecursionDepth() { * one if a single logging call without nested logging calls has been made, or more depending on the level of * nesting. * @return the depth of the nested logging calls in the current Thread + * @since 2.10.0 */ public static int getRecursionDepth() { return getRecursionDepthHolder()[0]; @@ -3746,6 +3808,9 @@ public void warn( logIfEnabled(FQCN, Level.WARN, null, message, p0, p1, p2, p3, p4, p5, p6, p7, p8, p9); } + /** + * @since 2.12.1 + */ protected boolean requiresLocation() { return false; } diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/AbstractLoggerAdapter.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/AbstractLoggerAdapter.java index 4fb5cdb49ee..bd38b48420b 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/AbstractLoggerAdapter.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/AbstractLoggerAdapter.java @@ -94,6 +94,8 @@ public ConcurrentMap getLoggersInContext(final LoggerContext context) /** * For unit testing. Consider to be private. + * + * @since 2.12.1 */ public Set getLoggerContexts() { return new HashSet<>(registry.keySet()); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/DefaultThreadContextMap.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/DefaultThreadContextMap.java index 471dba72fda..f8ea436284e 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/DefaultThreadContextMap.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/DefaultThreadContextMap.java @@ -97,6 +97,9 @@ public void remove(final String key) { } } + /** + * @since 2.8 + */ public void removeAll(final Iterable keys) { final Object[] state = localState.get(); if (state != null) { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/ExtendedLogger.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/ExtendedLogger.java index 29b02cf53df..e344458afe6 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/ExtendedLogger.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/ExtendedLogger.java @@ -48,6 +48,7 @@ public interface ExtendedLogger extends Logger { * @param message The message. * @param t A Throwable. * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled(Level level, Marker marker, CharSequence message, Throwable t); @@ -102,6 +103,7 @@ public interface ExtendedLogger extends Logger { * @param message The message. * @param p0 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled(Level level, Marker marker, String message, Object p0); @@ -114,6 +116,7 @@ public interface ExtendedLogger extends Logger { * @param p0 the message parameters * @param p1 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1); @@ -127,6 +130,7 @@ public interface ExtendedLogger extends Logger { * @param p1 the message parameters * @param p2 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2); @@ -141,6 +145,7 @@ public interface ExtendedLogger extends Logger { * @param p2 the message parameters * @param p3 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3); @@ -156,6 +161,7 @@ public interface ExtendedLogger extends Logger { * @param p3 the message parameters * @param p4 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled( Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4); @@ -173,6 +179,7 @@ boolean isEnabled( * @param p4 the message parameters * @param p5 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled( Level level, @@ -199,6 +206,7 @@ boolean isEnabled( * @param p5 the message parameters * @param p6 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled( Level level, @@ -227,6 +235,7 @@ boolean isEnabled( * @param p6 the message parameters * @param p7 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled( Level level, @@ -257,6 +266,7 @@ boolean isEnabled( * @param p7 the message parameters * @param p8 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled( Level level, @@ -289,6 +299,7 @@ boolean isEnabled( * @param p8 the message parameters * @param p9 the message parameters * @return True if logging is enabled, false otherwise. + * @since 2.6 */ boolean isEnabled( Level level, @@ -326,6 +337,7 @@ boolean isEnabled( * @param marker A Marker or null. * @param message The CharSequence message. * @param t the exception to log, including its stack trace. + * @since 2.6 */ void logIfEnabled(String fqcn, Level level, Marker marker, CharSequence message, Throwable t); @@ -385,6 +397,7 @@ boolean isEnabled( * @param marker A Marker or null. * @param message The message format. * @param p0 the message parameters + * @since 2.6 */ void logIfEnabled(String fqcn, Level level, Marker marker, String message, Object p0); @@ -398,6 +411,7 @@ boolean isEnabled( * @param message The message format. * @param p0 the message parameters * @param p1 the message parameters + * @since 2.6 */ void logIfEnabled(String fqcn, Level level, Marker marker, String message, Object p0, Object p1); @@ -412,6 +426,7 @@ boolean isEnabled( * @param p0 the message parameters * @param p1 the message parameters * @param p2 the message parameters + * @since 2.6 */ void logIfEnabled(String fqcn, Level level, Marker marker, String message, Object p0, Object p1, Object p2); @@ -427,6 +442,7 @@ boolean isEnabled( * @param p1 the message parameters * @param p2 the message parameters * @param p3 the message parameters + * @since 2.6 */ void logIfEnabled( String fqcn, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3); @@ -444,6 +460,7 @@ void logIfEnabled( * @param p2 the message parameters * @param p3 the message parameters * @param p4 the message parameters + * @since 2.6 */ void logIfEnabled( String fqcn, @@ -470,6 +487,7 @@ void logIfEnabled( * @param p3 the message parameters * @param p4 the message parameters * @param p5 the message parameters + * @since 2.6 */ void logIfEnabled( String fqcn, @@ -498,6 +516,7 @@ void logIfEnabled( * @param p4 the message parameters * @param p5 the message parameters * @param p6 the message parameters + * @since 2.6 */ void logIfEnabled( String fqcn, @@ -528,6 +547,7 @@ void logIfEnabled( * @param p5 the message parameters * @param p6 the message parameters * @param p7 the message parameters + * @since 2.6 */ void logIfEnabled( String fqcn, @@ -560,6 +580,7 @@ void logIfEnabled( * @param p6 the message parameters * @param p7 the message parameters * @param p8 the message parameters + * @since 2.6 */ void logIfEnabled( String fqcn, @@ -594,6 +615,7 @@ void logIfEnabled( * @param p7 the message parameters * @param p8 the message parameters * @param p9 the message parameters + * @since 2.6 */ void logIfEnabled( String fqcn, @@ -633,6 +655,7 @@ void logIfEnabled( * @param marker A Marker or null. * @param msgSupplier A function, which when called, produces the desired log message. * @param t the exception to log, including its stack trace. + * @since 2.4 */ void logIfEnabled(String fqcn, Level level, Marker marker, MessageSupplier msgSupplier, Throwable t); @@ -645,6 +668,7 @@ void logIfEnabled( * @param marker A Marker or null. * @param message The message format. * @param paramSuppliers An array of functions, which when called, produce the desired log message parameters. + * @since 2.4 */ @SuppressWarnings("deprecation") void logIfEnabled(String fqcn, Level level, Marker marker, String message, Supplier... paramSuppliers); @@ -658,6 +682,7 @@ void logIfEnabled( * @param marker A Marker or null. * @param msgSupplier A function, which when called, produces the desired log message. * @param t the exception to log, including its stack trace. + * @since 2.4 */ @SuppressWarnings("deprecation") void logIfEnabled(String fqcn, Level level, Marker marker, Supplier msgSupplier, Throwable t); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LocationAwareLogger.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LocationAwareLogger.java index dd6950eed19..c23a5610be9 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LocationAwareLogger.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LocationAwareLogger.java @@ -22,6 +22,8 @@ /** * Logger that accepts the location of the caller. + * + * @since 2.12.1 */ public interface LocationAwareLogger { void logMessage( diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContext.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContext.java index 27874bded06..d5a9119a1e3 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContext.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContext.java @@ -27,6 +27,7 @@ public interface LoggerContext { /** * Empty array. + * @since 2.17.2 */ LoggerContext[] EMPTY_ARRAY = {}; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContextShutdownAware.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContextShutdownAware.java index 5ea88122dbe..426629dc945 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContextShutdownAware.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContextShutdownAware.java @@ -19,6 +19,8 @@ /** * Interface allowing interested classes to know when a LoggerContext has shutdown - if the LoggerContext * implementation provides a way to register listeners. + * + * @since 2.12.1 */ public interface LoggerContextShutdownAware { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContextShutdownEnabled.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContextShutdownEnabled.java index 0add801259c..9c9fdc12d7f 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContextShutdownEnabled.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerContextShutdownEnabled.java @@ -20,6 +20,8 @@ /** * LoggerContexts implementing this are able register LoggerContextShutdownAware classes. + * + * @since 2.12.1 */ public interface LoggerContextShutdownEnabled { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerRegistry.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerRegistry.java index bd27af9ffd0..4274337b145 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerRegistry.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/LoggerRegistry.java @@ -36,6 +36,7 @@ /** * Convenience class to be used as an {@link ExtendedLogger} registry by {@code LoggerContext} implementations. + * @since 2.6 */ @NullMarked public class LoggerRegistry { @@ -52,6 +53,7 @@ public class LoggerRegistry { * Data structure contract for the internal storage of admitted loggers. * * @param subtype of {@code ExtendedLogger} + * @since 2.6 * @deprecated As of version {@code 2.25.0}, planned to be removed! */ @Deprecated @@ -68,6 +70,7 @@ public interface MapFactory { * {@link MapFactory} implementation using {@link ConcurrentHashMap}. * * @param subtype of {@code ExtendedLogger} + * @since 2.6 * @deprecated As of version {@code 2.25.0}, planned to be removed! */ @Deprecated @@ -93,6 +96,7 @@ public void putIfAbsent(final Map innerMap, final String name, final * {@link MapFactory} implementation using {@link WeakHashMap}. * * @param subtype of {@code ExtendedLogger} + * @since 2.6 * @deprecated As of version {@code 2.25.0}, planned to be removed! */ @Deprecated diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/Provider.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/Provider.java index 4f15843e284..4b9ab3f8d51 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/Provider.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/Provider.java @@ -43,11 +43,13 @@ public class Provider { /** * Constant inlined by the compiler + * @since 2.24.0 */ protected static final String CURRENT_VERSION = "2.6.0"; /** * Property name to set for a Log4j 2 provider to specify the priority of this implementation. + * @since 2.0.1 * @deprecated since 2.24.0 */ @Deprecated @@ -55,6 +57,7 @@ public class Provider { /** * Property name to set to the implementation of {@link ThreadContextMap}. + * @since 2.0.1 * @deprecated since 2.24.0 */ @Deprecated @@ -62,6 +65,7 @@ public class Provider { /** * Property name to set to the implementation of {@link LoggerContextFactory}. + * @since 2.0.1 * @deprecated since 2.24.0 */ @Deprecated @@ -100,6 +104,7 @@ public class Provider { /** * Constructor used by the deprecated {@code META-INF/log4j-provider.properties} format. + * @since 2.0.1 * @deprecated since 2.24.0 */ @Deprecated @@ -129,6 +134,7 @@ public Provider(final @Nullable Integer priority, final String versions) { * @param versions Minimal API version required, should be set to {@link #CURRENT_VERSION}, * @param loggerContextFactoryClass A public exported implementation of {@link LoggerContextFactory} or {@code * null} if {@link #getLoggerContextFactory()} is also implemented. + * @since 2.9.0 */ public Provider( final @Nullable Integer priority, @@ -144,6 +150,7 @@ public Provider( * null} if {@link #getLoggerContextFactory()} is also implemented, * @param threadContextMapClass A public exported implementation of {@link ThreadContextMap} or {@code null} if * {@link #getThreadContextMapInstance()} is implemented. + * @since 2.9.0 */ public Provider( final @Nullable Integer priority, @@ -164,6 +171,8 @@ public Provider( /** * Returns the Log4j API versions supported by the implementation. * @return A String containing the Log4j versions supported. + * + * @since 2.9.0 */ public String getVersions() { return versions != null ? versions : ""; @@ -194,6 +203,7 @@ public Integer getPriority() { * Loads the {@link LoggerContextFactory} class specified by this Provider. * * @return the LoggerContextFactory implementation class or {@code null} if unspecified or a loader error occurred. + * @since 2.0.1 */ public @Nullable Class loadLoggerContextFactory() { if (loggerContextFactoryClass != null) { @@ -254,6 +264,7 @@ public LoggerContextFactory getLoggerContextFactory() { * * @return the {@code ThreadContextMap} implementation class or {@code null} if unspecified or a loading error * occurred. + * @since 2.0.1 */ public @Nullable Class loadThreadContextMap() { if (threadContextMapClass != null) { @@ -307,7 +318,7 @@ public ThreadContextMap getThreadContextMapInstance() { * * @return the URL corresponding to the Provider {@code META-INF/log4j-provider.properties} file or {@code null} * for a provider class. - * @deprecated since 2.24.0, without replacement. + * @deprecated since 2.24.0, without a replacement. */ @Deprecated public @Nullable URL getUrl() { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/spi/ThreadContextMapFactory.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/ThreadContextMapFactory.java index 418beb4583c..bf97c1aebba 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/spi/ThreadContextMapFactory.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/spi/ThreadContextMapFactory.java @@ -46,6 +46,8 @@ public final class ThreadContextMapFactory { /** * Initializes static variables based on system properties. Normally called when this class is initialized by the VM * and when Log4j is reconfigured. + * + * @since 2.11.0 */ public static void init() { ProviderUtil.getProvider().getThreadContextMapInstance(); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusConsoleListener.java b/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusConsoleListener.java index 6261c172aa9..ce23ff5aa9b 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusConsoleListener.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusConsoleListener.java @@ -142,7 +142,7 @@ public void log(final StatusData data) { * Adds package name filters to exclude. * * @param filters An array of package names to exclude. - * @deprecated This method is ineffective and only kept for binary backward compatibility. + * @deprecated since 2.23.0, this method is ineffective and only kept for binary backward compatibility. */ @Deprecated public void setFilters(final String... filters) {} diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusData.java b/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusData.java index b100ade3eda..55f13201e7c 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusData.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusData.java @@ -60,6 +60,7 @@ public class StatusData implements Serializable { * @param message a message * @param throwable the error occurred * @param threadName the thread name + * @since 2.4 */ public StatusData( @Nullable final StackTraceElement caller, @@ -93,6 +94,7 @@ public StatusData( * Returns the instant of the event. * * @return the event's instant + * @since 2.23.0 */ public Instant getInstant() { return instant; @@ -102,7 +104,7 @@ public Instant getInstant() { * Returns the instant of the event. * * @return the event's instant - * @deprecated Use {@link #getInstant()} instead. + * @deprecated since 2.23.0, use {@link #getInstant()} instead. */ @Deprecated public long getTimestamp() { @@ -141,6 +143,7 @@ public Message getMessage() { * Returns the name of the thread associated with the event. * * @return the name of the thread associated with the event + * @since 2.4 */ public String getThreadName() { return threadName; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusLogger.java b/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusLogger.java index 64938962a95..6aec303cba4 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusLogger.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/status/StatusLogger.java @@ -581,6 +581,7 @@ public static void setLogger(final StatusLogger logger) { * Returns the fallback listener. * * @return the fallback listener + * @since 2.23.0 */ public StatusConsoleListener getFallbackListener() { return fallbackListener; @@ -590,7 +591,8 @@ public StatusConsoleListener getFallbackListener() { * Sets the level of the fallback listener. * * @param level a level - * @deprecated Instead use the {@link StatusConsoleListener#setLevel(Level) setLevel(Level)} method on the fallback listener returned by {@link #getFallbackListener()}. + * @deprecated Since 2.23.0, instead use the {@link StatusConsoleListener#setLevel(Level) setLevel(Level)} method + * on the fallback listener returned by {@link #getFallbackListener()}. */ @Deprecated public void setLevel(final Level level) { @@ -633,7 +635,9 @@ public void removeListener(final StatusListener listener) { * Sets the level of the fallback listener. * * @param level a level - * @deprecated Instead use the {@link StatusConsoleListener#setLevel(Level) setLevel(Level)} method on the fallback listener returned by {@link #getFallbackListener()}. + * @since 2.6 + * @deprecated Since 2.23.0, instead use the {@link StatusConsoleListener#setLevel(Level) setLevel(Level)} method + * on the fallback listener returned by {@link #getFallbackListener()}. */ @Deprecated public void updateListenerLevel(final Level level) { @@ -689,7 +693,8 @@ private static void closeListenerSafely(final StatusListener listener) { /** * Returns buffered events. * - * @deprecated Instead of relying on the buffering provided by {@code StatusLogger}, users should register their own listeners to access to logged events. + * @deprecated Since 2.23.0, instead of relying on the buffering provided by {@code StatusLogger}, + * users should register their own listeners to access to logged events. * @return a thread-safe read-only collection of buffered events */ @Deprecated @@ -703,7 +708,8 @@ public List getStatusData() { /** * Clears the event buffer. * - * @deprecated Instead of relying on the buffering provided by {@code StatusLogger}, users should register their own listeners to access to logged events. + * @deprecated Since 2.23.0, instead of relying on the buffering provided by {@code StatusLogger}, + * users should register their own listeners to access to logged events. */ @Deprecated public void clear() { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/Activator.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/Activator.java index 3cb55e97292..44766a18d3c 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/Activator.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/Activator.java @@ -44,6 +44,7 @@ * {@link org.apache.logging.log4j.spi.LoggerContextFactory} et al. that have corresponding * {@code META-INF/log4j-provider.properties} files. As with all OSGi BundleActivator classes, this class is not for * public use and is only useful in an OSGi framework environment. + * @since 2.0.1 */ @Header(name = Constants.BUNDLE_ACTIVATOR, value = "${@class}") @Header(name = Constants.BUNDLE_ACTIVATIONPOLICY, value = Constants.ACTIVATION_LAZY) diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/Base64Util.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/Base64Util.java index f96bffd28d4..4733c1df363 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/Base64Util.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/Base64Util.java @@ -25,6 +25,8 @@ /** * Base64 encodes Strings. This utility is only necessary because the mechanism to do this changed in Java 8 and * the original method was removed in Java 9. + * + * @since 2.12.0 */ public final class Base64Util { @@ -54,6 +56,7 @@ private Base64Util() {} /** * This method does not specify an encoding for the {@code str} parameter and should not be used. + * @deprecated since 2.22.0, use {@link java.util.Base64} instead. */ @Deprecated public static String encode(final String str) { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/Cast.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/Cast.java index df97c336ee5..46f6954cc0d 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/Cast.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/Cast.java @@ -16,6 +16,9 @@ */ package org.apache.logging.log4j.util; +/** + * @since 2.22.0 + */ @InternalApi public final class Cast { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/Chars.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/Chars.java index b17e6cd0f8f..509f15811f2 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/Chars.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/Chars.java @@ -18,6 +18,7 @@ /** * Consider this class private. + * @since 2.3 */ @InternalApi public final class Chars { @@ -34,7 +35,10 @@ public final class Chars { /** Line Feed. */ public static final char LF = '\n'; - /** NUL. */ + /** + * NUL. + * @since 2.11.0 + */ public static final char NUL = 0; /** Single Quote [']. */ @@ -51,6 +55,7 @@ public final class Chars { * * @param digit a number 0 - 15 * @return the hex character for that digit or '\0' if invalid + * @since 2.8.2 */ public static char getUpperCaseHex(final int digit) { if (digit < 0 || digit >= 16) { @@ -64,6 +69,7 @@ public static char getUpperCaseHex(final int digit) { * * @param digit a number 0 - 15 * @return the hex character for that digit or '\0' if invalid + * @since 2.8.2 */ public static char getLowerCaseHex(final int digit) { if (digit < 0 || digit >= 16) { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/Constants.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/Constants.java index b2324d90012..7d665b9bff8 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/Constants.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/Constants.java @@ -67,6 +67,7 @@ public final class Constants { /** * Java major version. + * @since 2.8.1 */ public static final int JAVA_MAJOR_VERSION = getMajorVersion(); @@ -77,7 +78,8 @@ public final class Constants { * The default value is 518, which allows the StringBuilder to resize three times from its initial size. * Users can override with system property "log4j.maxReusableMsgSize". *

- * @since 2.9 + * + * @since 2.9.0 */ public static final int MAX_REUSABLE_MESSAGE_SIZE = size("log4j.maxReusableMsgSize", (128 * 2 + 2) * 2 + 2); @@ -89,6 +91,8 @@ public final class Constants { * {@code } status attribute, as well as any value set for * system property {@code org.apache.logging.log4j.simplelog.StatusLogger.level}. *

+ * + * @since 2.9.0 */ public static final String LOG4J2_DEBUG = "log4j2.debug"; @@ -112,11 +116,13 @@ private static boolean isClassAvailable(final String className) { /** * The empty array. + * @since 2.15.0 */ public static final Object[] EMPTY_OBJECT_ARRAY = {}; /** * The empty array. + * @since 2.15.0 */ public static final byte[] EMPTY_BYTE_ARRAY = {}; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/FilteredObjectInputStream.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/FilteredObjectInputStream.java index 52b71507dea..d207e41949e 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/FilteredObjectInputStream.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/FilteredObjectInputStream.java @@ -32,7 +32,7 @@ * Extends {@link ObjectInputStream} to only allow some built-in Log4j classes and caller-specified classes to be * deserialized. * - * @since 2.8.2 + * @since 2.11.0 */ public class FilteredObjectInputStream extends ObjectInputStream { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/InternalException.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/InternalException.java index 486aa8b84d5..2c011d43430 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/InternalException.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/InternalException.java @@ -19,6 +19,8 @@ /** * Exception thrown when an error occurs while accessing internal resources. This is generally used to * convert checked exceptions to runtime exceptions. + * + * @since 2.22.0 */ public class InternalException extends RuntimeException { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/LambdaUtil.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/LambdaUtil.java index ef1f3b0b321..c02fd6c8d43 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/LambdaUtil.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/LambdaUtil.java @@ -21,6 +21,7 @@ /** * Utility class for lambda support. + * @since 2.4 */ public final class LambdaUtil { /** @@ -80,6 +81,7 @@ public static Message get(final MessageSupplier supplier) { * @param supplier a lambda expression or {@code null} * @return the Message resulting from evaluating the lambda expression or the Message created by the factory for * supplied values that are not of type Message + * @since 2.6 */ public static Message getMessage(final Supplier supplier, final MessageFactory messageFactory) { if (supplier == null) { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/Lazy.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/Lazy.java index 2e0d84b3ced..3af4ed46a01 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/Lazy.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/Lazy.java @@ -24,6 +24,7 @@ * Provides a lazily-initialized value from a {@code Supplier}. * * @param type of value + * @since 2.22.0 */ public interface Lazy extends Supplier { /** diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/LazyBoolean.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/LazyBoolean.java index 26db8639de9..f287aae11c5 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/LazyBoolean.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/LazyBoolean.java @@ -20,6 +20,9 @@ import java.util.concurrent.locks.ReentrantLock; import java.util.function.BooleanSupplier; +/** + * @since 2.22.0 + */ public class LazyBoolean implements BooleanSupplier { private final BooleanSupplier supplier; private final Lock lock = new ReentrantLock(); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/LoaderUtil.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/LoaderUtil.java index 001ad3a5f5b..b326734ccb7 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/LoaderUtil.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/LoaderUtil.java @@ -37,6 +37,7 @@ * @see RuntimePermission * @see Thread#getContextClassLoader() * @see ClassLoader#getSystemClassLoader() + * @since 2.0.1 */ @InternalApi public final class LoaderUtil { @@ -86,11 +87,15 @@ private LoaderUtil() {} * Returns the ClassLoader to use. * * @return the ClassLoader. + * @since 2.22.0 */ public static ClassLoader getClassLoader() { return getClassLoader(LoaderUtil.class, null); } + /** + * @since 2.22.0 + */ // TODO: this method could use some explanation public static ClassLoader getClassLoader(final Class class1, final Class class2) { PrivilegedAction action = () -> { @@ -349,7 +354,7 @@ public static T newCheckedInstanceOfProperty(final String propertyName, fina * @throws IllegalAccessException if the class can't be instantiated through a public constructor * @throws InstantiationException if the provided class is abstract or an interface * @throws InvocationTargetException if an exception is thrown by the constructor - * @since 2.22 + * @since 2.22.0 */ public static T newCheckedInstanceOfProperty( final String propertyName, final Class clazz, final Supplier defaultSupplier) diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/OsgiServiceLocator.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/OsgiServiceLocator.java index 46157290c18..26eeae17185 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/OsgiServiceLocator.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/OsgiServiceLocator.java @@ -26,6 +26,9 @@ import org.osgi.framework.FrameworkUtil; import org.osgi.framework.wiring.BundleRevision; +/** + * @since 2.18.0 + */ public class OsgiServiceLocator { private static final Logger LOGGER = StatusLogger.getLogger(); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/ProcessIdUtil.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/ProcessIdUtil.java index be34c4926a4..a1be559a565 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/ProcessIdUtil.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/ProcessIdUtil.java @@ -23,7 +23,7 @@ /** * Provides the PID of the current JVM. * - * @since 2.9 + * @since 2.9.0 */ public class ProcessIdUtil { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesPropertySource.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesPropertySource.java index 311247c85f7..8ff065ecce9 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesPropertySource.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesPropertySource.java @@ -38,6 +38,9 @@ public PropertiesPropertySource(final Properties properties) { this(properties, DEFAULT_PRIORITY); } + /** + * @since 2.18.0 + */ public PropertiesPropertySource(final Properties properties, final int priority) { this.properties = properties; this.priority = priority; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java index 30b92854b0c..145216b3332 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java @@ -160,6 +160,7 @@ public void removePropertySource(final PropertySource propertySource) { * * @param name the name of the property to verify * @return {@code true} if the specified property is defined, regardless of its value + * @since 2.9.0 */ public boolean hasProperty(final String name) { return environment.containsKey(name); @@ -196,6 +197,7 @@ public boolean getBooleanProperty(final String name, final boolean defaultValue) * @param defaultValueIfAbsent the default value to use if the property is undefined * @param defaultValueIfPresent the default value to use if the property is defined but not assigned * @return the boolean value of the property or {@code defaultValue} if undefined. + * @since 2.9.0 */ public boolean getBooleanProperty( final String name, final boolean defaultValueIfAbsent, final boolean defaultValueIfPresent) { @@ -228,6 +230,7 @@ public Boolean getBooleanProperty(final String[] prefixes, final String key, fin * * @param name the name of the property to look up * @return the Charset value of the property or {@link Charset#defaultCharset()} if undefined. + * @since 2.8 */ public Charset getCharsetProperty(final String name) { return getCharsetProperty(name, Charset.defaultCharset()); @@ -240,6 +243,7 @@ public Charset getCharsetProperty(final String name) { * @param name the name of the property to look up * @param defaultValue the default value to use if the property is undefined * @return the Charset value of the property or {@code defaultValue} if undefined. + * @since 2.8 */ public Charset getCharsetProperty(final String name, final Charset defaultValue) { final String charsetName = getStringProperty(name); @@ -270,6 +274,7 @@ public Charset getCharsetProperty(final String name, final Charset defaultValue) * @param name the name of the property to look up * @param defaultValue the default value to use if the property is undefined * @return the parsed double value of the property or {@code defaultValue} if it was undefined or could not be parsed. + * @since 2.6 */ public double getDoubleProperty(final String name, final double defaultValue) { final String prop = getStringProperty(name); @@ -596,6 +601,7 @@ private boolean containsKey(final String key) { * @param properties The Properties to evaluate. * @param prefix The prefix to extract. * @return The subset of properties. + * @since 2.4 */ public static Properties extractSubset(final Properties properties, final String prefix) { final Properties subset = new Properties(); @@ -673,6 +679,7 @@ public static Map partitionOnCommonPrefixes( * Returns true if system properties tell us we are running on Windows. * * @return true if system properties tell us we are running on Windows. + * @since 2.5 */ public boolean isOsWindows() { return SystemPropertiesPropertySource.getSystemProperty("os.name", "").startsWith("Windows"); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertyFilePropertySource.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertyFilePropertySource.java index 3440af04602..acb4310c3c3 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertyFilePropertySource.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertyFilePropertySource.java @@ -37,6 +37,9 @@ public PropertyFilePropertySource(final String fileName) { this(fileName, true); } + /** + * @since 2.18.0 + */ public PropertyFilePropertySource(final String fileName, final boolean useTccl) { super(loadPropertiesFile(fileName, useTccl)); } diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertySource.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertySource.java index 399c4ea010c..63c8173c443 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertySource.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertySource.java @@ -56,6 +56,7 @@ default void forEach(final BiConsumer action) {} * Returns the list of all property names. * * @return list of property names + * @since 2.18.0 */ default Collection getPropertyNames() { return Collections.emptySet(); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/ProviderActivator.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/ProviderActivator.java index bbb69664851..f2d61dbe5e8 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/ProviderActivator.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/ProviderActivator.java @@ -24,6 +24,8 @@ /** * Utility class to register Log4j2 providers in an OSGI environment. + * + * @since 2.19.0 */ public abstract class ProviderActivator implements BundleActivator { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/ServiceLoaderUtil.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/ServiceLoaderUtil.java index cbd0b4de0b6..38d6702b339 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/ServiceLoaderUtil.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/ServiceLoaderUtil.java @@ -47,6 +47,8 @@ *
  • skip faulty services, allowing for a partial retrieval of the good ones,
    • *
  • allow to integrate other sources of services like OSGi services.
    • * + * + * @since 2.18.0 */ @InternalApi public final class ServiceLoaderUtil { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/SortedArrayStringMap.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/SortedArrayStringMap.java index 2d2a67c2579..ac6b3ed199b 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/SortedArrayStringMap.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/SortedArrayStringMap.java @@ -109,6 +109,9 @@ public SortedArrayStringMap(final ReadOnlyStringMap other) { } } + /** + * @since 2.8 + */ public SortedArrayStringMap(final Map map) { resize(ceilingNextPowerOfTwo(map.size())); for (final Map.Entry entry : map.entrySet()) { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/StackLocator.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/StackLocator.java index 8871b44a11b..13cf6b39eb9 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/StackLocator.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/StackLocator.java @@ -49,6 +49,8 @@ * environments may fall back to using {@link Throwable#getStackTrace()} which is significantly slower due to * examination of every virtual frame of execution. *

    + * + * @since 2.9.0 */ @InternalApi public final class StackLocator { @@ -206,6 +208,9 @@ public Class getCallerClass(final Class anchor) { return Object.class; } + /** + * @since 2.17.2 + */ // migrated from ThrowableProxy @PerformanceSensitive public Deque> getCurrentStackTrace() { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/StackLocatorUtil.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/StackLocatorUtil.java index e37f781d98a..89e35aa616f 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/StackLocatorUtil.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/StackLocatorUtil.java @@ -23,6 +23,8 @@ /** * Consider this class private. Provides various methods to determine the caller class. + * + * @since 2.9.0 */ @InternalApi public final class StackLocatorUtil { @@ -84,6 +86,7 @@ public static Class getCallerClass(final String fqcn, final String pkg) { * @param depth The stack frame count to walk. * @return A class or null. * @throws IndexOutOfBoundsException if depth is negative. + * @since 2.17.2 */ @PerformanceSensitive public static ClassLoader getCallerClassLoader(final int depth) { @@ -97,6 +100,7 @@ public static ClassLoader getCallerClassLoader(final int depth) { * @param sentinelClass Sentinel class at which to begin searching * @param callerPredicate Predicate checked after the sentinelClass is found * @return the first matching class after sentinelClass is found. + * @since 2.15.0 */ @PerformanceSensitive public static Class getCallerClass(final Class sentinelClass, final Predicate> callerPredicate) { @@ -109,6 +113,9 @@ public static Class getCallerClass(final Class anchor) { return stackLocator.getCallerClass(anchor); } + /** + * @since 2.17.2 + */ // migrated from ThrowableProxy @PerformanceSensitive public static Deque> getCurrentStackTrace() { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/StringBuilders.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/StringBuilders.java index aae5892f5b9..8f697d53f1f 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/StringBuilders.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/StringBuilders.java @@ -22,6 +22,7 @@ /** * Consider this class private. + * @since 2.3 */ @InternalApi public final class StringBuilders { @@ -92,6 +93,7 @@ public static StringBuilder appendKeyDqValue(final StringBuilder sb, final Strin * * @param stringBuilder the StringBuilder to append the value to * @param obj the object whose text representation to append to the StringBuilder + * @since 2.7 */ public static void appendValue(final StringBuilder stringBuilder, final Object obj) { if (!appendSpecificTypes(stringBuilder, obj)) { @@ -99,6 +101,9 @@ public static void appendValue(final StringBuilder stringBuilder, final Object o } } + /** + * @since 2.10.0 + */ public static boolean appendSpecificTypes(final StringBuilder stringBuilder, final Object obj) { if (obj == null || obj instanceof String) { stringBuilder.append((String) obj); @@ -155,6 +160,7 @@ private static boolean isDate(final Object obj) { * @param rightOffset start index in the right CharSequence * @param rightLength length of the section in the right CharSequence * @return true if equal, false otherwise + * @since 2.8 */ public static boolean equals( final CharSequence left, @@ -185,6 +191,7 @@ public static boolean equals( * @param rightOffset start index in the right CharSequence * @param rightLength length of the section in the right CharSequence * @return true if equal ignoring case, false otherwise + * @since 2.8 */ public static boolean equalsIgnoreCase( final CharSequence left, @@ -210,7 +217,7 @@ public static boolean equalsIgnoreCase( * * @param stringBuilder the StringBuilder to check * @param maxSize the maximum number of characters the StringBuilder is allowed to have - * @since 2.9 + * @since 2.9.0 */ public static void trimToMaxSize(final StringBuilder stringBuilder, final int maxSize) { if (stringBuilder != null && stringBuilder.capacity() > maxSize) { @@ -219,6 +226,9 @@ public static void trimToMaxSize(final StringBuilder stringBuilder, final int ma } } + /** + * @since 2.10.0 + */ public static void escapeJson(final StringBuilder toAppendTo, final int start) { int escapeCount = 0; for (int i = start; i < toAppendTo.length(); i++) { @@ -295,6 +305,9 @@ private static int escapeAndDecrement(final StringBuilder toAppendTo, int lastPo return lastPos; } + /** + * @since 2.10.0 + */ public static void escapeXml(final StringBuilder toAppendTo, final int start) { int escapeCount = 0; for (int i = start; i < toAppendTo.length(); i++) { diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/Strings.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/Strings.java index ce7093c790f..b33de7dd025 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/Strings.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/Strings.java @@ -45,12 +45,14 @@ public final class Strings { /** * The empty array. + * @since 2.15.0 */ public static final String[] EMPTY_ARRAY = {}; /** * OS-dependent line separator, defaults to {@code "\n"} if the system property {@code ""line.separator"} cannot be * read. + * @since 2.7 */ public static final String LINE_SEPARATOR = System.lineSeparator(); @@ -59,6 +61,7 @@ public final class Strings { * * @param str a String * @return {@code "str"} + * @since 2.3 */ public static String dquote(final String str) { return Chars.DQUOTE + str + Chars.DQUOTE; @@ -70,6 +73,7 @@ public static String dquote(final String str) { * * @param s the String to check, may be {@code null} * @return {@code true} if the String is {@code null}, empty, or all characters are {@link Character#isWhitespace(char)} + * @since 2.0.1 */ public static boolean isBlank(final String s) { if (s == null || s.isEmpty()) { @@ -118,6 +122,7 @@ public static boolean isEmpty(final CharSequence cs) { * * @param s the String to check, may be {@code null} * @return {@code true} if the String is non-{@code null} and has content after being trimmed. + * @since 2.0.1 */ public static boolean isNotBlank(final String s) { return !isBlank(s); @@ -157,6 +162,7 @@ public static boolean isNotEmpty(final CharSequence cs) { * @param iterable the {@code Iterable} providing the values to join together, may be null * @param separator the separator character to use * @return the joined String, {@code null} if null iterator input + * @since 2.7 */ public static String join(final Iterable iterable, final char separator) { if (iterable == null) { @@ -175,6 +181,7 @@ public static String join(final Iterable iterable, final char separator) { * @param iterator the {@code Iterator} of values to join together, may be null * @param separator the separator character to use * @return the joined String, {@code null} if null iterator input + * @since 2.7 */ public static String join(final Iterator iterator, final char separator) { @@ -207,6 +214,9 @@ public static String join(final Iterator iterator, final char separator) { return buf.toString(); } + /** + * @since 2.17.2 + */ public static String[] splitList(final String string) { return string != null ? string.split(COMMA_DELIMITED_RE) : new String[0]; } @@ -234,6 +244,7 @@ public static String[] splitList(final String string) { * @param str the String to get the leftmost characters from, may be null * @param len the length of the required String * @return the leftmost characters, {@code null} if null String input + * @since 2.11.2 */ public static String left(final String str, final int len) { if (str == null) { @@ -253,6 +264,7 @@ public static String left(final String str, final int len) { * * @param str a String * @return {@code 'str'} + * @since 2.3 */ public static String quote(final String str) { return Chars.QUOTE + str + Chars.QUOTE; @@ -296,6 +308,7 @@ private Strings() { * @param str The string to upper case. * @return a new string * @see String#toLowerCase(Locale) + * @since 2.17.2 */ public static String toRootLowerCase(final String str) { return str.toLowerCase(Locale.ROOT); @@ -306,6 +319,7 @@ public static String toRootLowerCase(final String str) { * @param str The string to lower case. * @return a new string * @see String#toLowerCase(Locale) + * @since 2.6 */ public static String toRootUpperCase(final String str) { return str.toUpperCase(Locale.ROOT); @@ -316,6 +330,7 @@ public static String toRootUpperCase(final String str) { * @param str1 the first string. * @param str2 the second string. * @return the concatenated String. + * @since 2.15.0 */ public static String concat(final String str1, final String str2) { if (isEmpty(str1)) { @@ -338,6 +353,7 @@ public static String concat(final String str1, final String str2) { * @param count the repetition count * @return the new string * @throws IllegalArgumentException if either {@code str} is null or {@code count} is negative + * @since 2.14.0 */ public static String repeat(final String str, final int count) { Objects.requireNonNull(str, "str"); diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/SystemPropertiesPropertySource.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/SystemPropertiesPropertySource.java index e49dad0dd57..3471f1db8e4 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/SystemPropertiesPropertySource.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/SystemPropertiesPropertySource.java @@ -49,6 +49,9 @@ public static PropertySource provider() { return INSTANCE; } + /** + * @since 2.20.0 + */ public static String getSystemProperty(final String key, final String defaultValue) { final String value = INSTANCE.getProperty(key); return value != null ? value : defaultValue; diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/Timer.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/Timer.java index f85fb1a1c02..d4d614ad4d0 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/Timer.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/Timer.java @@ -23,12 +23,17 @@ * Primarily used in unit tests, but can be used to track elapsed time for a request or portion of any other operation * so long as all the timer methods are called on the same thread in which it was started. Calling start on * multiple threads will cause the times to be aggregated. + * + * @since 2.12.0 */ public class Timer implements Serializable, StringBuilderFormattable { private static final long serialVersionUID = 9175191792439630013L; private final String name; // The timer's name + /** + * @since 2.12.0 + */ public enum Status { Started, Stopped,