This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch doc/2.x/since-tag in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit c0daf9d5469a08975dd3e7315ac68d39d954f3d7 Author: Piotr P. Karwasz <[email protected]> AuthorDate: Sun Dec 29 07:21:11 2024 +0100 Document `log4j-api` changes in version 2.9.0 --- .../apache/logging/log4j/message/MapMessage.java | 51 +++++++++++----------- .../log4j/message/MessageCollectionMessage.java | 1 + .../logging/log4j/message/StringMapMessage.java | 2 +- .../message/StructuredDataCollectionMessage.java | 1 + .../logging/log4j/message/StructuredDataId.java | 8 ++-- .../log4j/message/StructuredDataMessage.java | 11 +++-- .../logging/log4j/message/ThreadDumpMessage.java | 4 +- .../logging/log4j/message/ThreadInformation.java | 2 + .../org/apache/logging/log4j/spi/Provider.java | 4 ++ .../java/org/apache/logging/log4j/util/Chars.java | 2 + .../org/apache/logging/log4j/util/Constants.java | 5 ++- .../apache/logging/log4j/util/ProcessIdUtil.java | 2 +- .../apache/logging/log4j/util/PropertiesUtil.java | 2 + .../apache/logging/log4j/util/StackLocator.java | 2 + .../logging/log4j/util/StackLocatorUtil.java | 2 + .../apache/logging/log4j/util/StringBuilders.java | 2 +- 16 files changed, 62 insertions(+), 39 deletions(-) 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 12b36af341..da4c02b139 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 @@ -117,6 +117,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * Constructs a new instance. * * @param initialCapacity the initial capacity. + * @since 2.9.0 */ public MapMessage(final int initialCapacity) { this.data = new SortedArrayStringMap(initialCapacity); @@ -191,7 +192,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * * @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); @@ -279,10 +280,9 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @param action The action to be performed for each key-value pair in this collection * @param <CV> 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 <CV> void forEach(final BiConsumer<String, ? super CV> action) { data.forEach(action); @@ -308,10 +308,9 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @param <CV> type of the consumer value * @param <S> 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 <CV, S> void forEach(final TriConsumer<String, ? super CV, S> action, final S state) { data.forEach(action, state); @@ -504,7 +503,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final boolean value) { // do nothing @@ -513,7 +512,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final byte value) { // do nothing @@ -522,7 +521,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final char value) { // do nothing @@ -531,7 +530,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final double value) { // do nothing @@ -540,7 +539,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final float value) { // do nothing @@ -549,7 +548,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final int value) { // do nothing @@ -558,7 +557,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final long value) { // do nothing @@ -567,7 +566,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final Object value) { // do nothing @@ -576,7 +575,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final short value) { // do nothing @@ -585,7 +584,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr /** * Default implementation does nothing. * - * @since 2.9 + * @since 2.9.0 */ protected void validate(final String key, final String value) { // do nothing @@ -607,7 +606,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { @@ -622,7 +621,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { @@ -637,7 +636,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { @@ -652,7 +651,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { @@ -667,7 +666,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { @@ -682,7 +681,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { @@ -697,7 +696,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { @@ -712,7 +711,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { @@ -727,7 +726,7 @@ public class MapMessage<M extends MapMessage<M, V>, V> implements MultiFormatStr * @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) { 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 1ebd438f3f..0b683a3c98 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 @@ package org.apache.logging.log4j.message; /** * A Message that is a collection of Messages. * @param <T> The Message type. + * @since 2.9.0 */ public interface MessageCollectionMessage<T> extends Message, Iterable<T> {} 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 d2d642a0c4..545e3533dd 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 @@ import org.apache.logging.log4j.util.PerformanceSensitive; /** * 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 fbe760bfa6..22a295ad1c 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 @@ import org.apache.logging.log4j.util.StringBuilderFormattable; /** * A collection of StructuredDataMessages. + * @since 2.9.0 */ public class StructuredDataCollectionMessage implements StringBuilderFormattable, MessageCollectionMessage<StructuredDataMessage> { 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 306e18f127..002867991a 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 @@ -61,7 +61,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 +71,7 @@ public class StructuredDataId implements Serializable, StringBuilderFormattable * 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 +94,7 @@ public class StructuredDataId implements Serializable, StringBuilderFormattable * @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; @@ -192,7 +192,7 @@ public class StructuredDataId implements Serializable, StringBuilderFormattable * @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.9.0 * @deprecated Use {@link #StructuredDataId(String, String, String[], String[], int)} instead. */ @InlineMe(replacement = "this(name, String.valueOf(enterpriseNumber), required, optional, maxLength)") 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 a282d101a3..46b757d54f 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 class StructuredDataMessage extends MapMessage<StructuredDataMessage, Str * @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 class StructuredDataMessage extends MapMessage<StructuredDataMessage, Str * @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<String, String> data, final int maxLength) { @@ -129,7 +129,7 @@ public class StructuredDataMessage extends MapMessage<StructuredDataMessage, Str * @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 class StructuredDataMessage extends MapMessage<StructuredDataMessage, Str * @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, @@ -521,6 +521,9 @@ public class StructuredDataMessage extends MapMessage<StructuredDataMessage, Str 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 4ddbdc5c5f..88ac55fca8 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 @@ public class ThreadDumpMessage implements Message, StringBuilderFormattable { * <p> * Implementations of this class are loaded via the standard java Service Provider interface. * </p> + * + * @since 2.9.0 */ - public static interface ThreadInfoFactory { + public interface ThreadInfoFactory { Map<ThreadInformation, StackTraceElement[]> 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 68e9e79ff5..c9b1d04aa9 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 @@ package org.apache.logging.log4j.message; /** * 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/spi/Provider.java b/log4j-api/src/main/java/org/apache/logging/log4j/spi/Provider.java index 4b9a1b79c5..c7718dc43e 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 @@ -133,6 +133,7 @@ public class Provider { * @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, @@ -148,6 +149,7 @@ public class 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, @@ -168,6 +170,8 @@ public class 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 : ""; 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 e67c3e74d0..e76b7eff37 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 @@ -52,6 +52,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) { @@ -65,6 +66,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 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 3391477994..9217d9cf85 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 @@ -78,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". * </p> - * @since 2.9 + * + * @since 2.9.0 */ public static final int MAX_REUSABLE_MESSAGE_SIZE = size("log4j.maxReusableMsgSize", (128 * 2 + 2) * 2 + 2); @@ -90,6 +91,8 @@ public final class Constants { * {@code <Configuration status="<level>" ...>} status attribute, as well as any value set for * system property {@code org.apache.logging.log4j.simplelog.StatusLogger.level}. * </p> + * + * @since 2.9.0 */ public static final String LOG4J2_DEBUG = "log4j2.debug"; 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 be34c4926a..a1be559a56 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 @@ import java.lang.reflect.Method; /** * 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/PropertiesUtil.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java index 33c276a28b..145216b333 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 final class PropertiesUtil { * * @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 final class PropertiesUtil { * @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) { 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 8871b44a11..c514217c37 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 @@ import org.apache.logging.log4j.status.StatusLogger; * environments may fall back to using {@link Throwable#getStackTrace()} which is significantly slower due to * examination of every virtual frame of execution. * </p> + * + * @since 2.9.0 */ @InternalApi public final class StackLocator { 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 e37f781d98..d55e97dd20 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 @@ import org.apache.logging.log4j.status.StatusLogger; /** * <em>Consider this class private.</em> Provides various methods to determine the caller class. + * + * @since 2.9.0 */ @InternalApi public final class StackLocatorUtil { 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 9a72fa6245..9fddae9d69 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 @@ -214,7 +214,7 @@ public final class StringBuilders { * * @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) {
