Add PropertyEnvironment to log4j-sdk

This PR creates a simplified version of `PropertyEnvironment` in
`log4j-sdk` that supports Spring-like property classes.

It provides aggregation features to allow the conversion of multiple
properties at once in a typesafe way.

Author: ppkarwasz

log4j-sdk/pom.xml

@@ -60,6 +60,12 @@
       <scope>test</scope>
     </dependency>
 
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-params</artifactId>
+      <scope>test</scope>
+    </dependency>
+
     <dependency>
       <groupId>org.javassist</groupId>
       <artifactId>javassist</artifactId>

log4j-sdk/src/main/java/org/apache/logging/log4j/sdk/env/ConfigurablePropertyEnvironment.java

@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.logging.log4j.sdk.env;
+
+/**
+ * Provides methods to modify the set of {@link PropertySource}s used by a {@link PropertyEnvironment}.
+ */
+public interface ConfigurablePropertyEnvironment extends PropertyEnvironment {
+
+    /**
+     * Adds a property source to the environment.
+     * @param source A property source.
+     */
+    void addPropertySource(PropertySource source);
+
+    /**
+     * Removes a property source from the environment.
+     * @param source A property source.
+     */
+    void removePropertySource(PropertySource source);
+}

log4j-sdk/src/main/java/org/apache/logging/log4j/sdk/env/Log4jProperty.java

@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.logging.log4j.sdk.env;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotates a class or parameter that stores Log4j API configuration properties.
+ * <p>
+ *     This annotation is required for root property classes.
+ * </p>
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.PARAMETER, ElementType.FIELD})
+public @interface Log4jProperty {
+
+    /**
+     * Provides a name for the configuration property.
+     * <p>
+     *
+     * </p>
+     */
+    String name() default "";
+
+    /**
+     * Provides the default value of the property.
+     * <p>
+     *     This only applies to scalar values.
+     * </p>
+     */
+    String defaultValue() default "";
+}

log4j-sdk/src/main/java/org/apache/logging/log4j/sdk/env/PropertyEnvironment.java

@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.logging.log4j.sdk.env;
+
+import java.nio.charset.Charset;
+import java.time.Duration;
+import org.apache.logging.log4j.sdk.env.internal.PropertiesUtilPropertyEnvironment;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Represents the main access point to Log4j properties.
+ * <p>
+ *     It provides as typesafe way to access properties stored in multiple {@link PropertySource}s, type conversion
+ *     methods and property aggregation methods (cf. {@link #getProperty(Class)}).
+ * </p>
+ */
+public interface PropertyEnvironment {
+
+    static PropertyEnvironment getGlobal() {
+        return PropertiesUtilPropertyEnvironment.INSTANCE;
+    }
+
+    /**
+     * Gets the named property as a boolean value. If the property matches the string {@code "true"} (case-insensitive),
+     * then it is returned as the boolean value {@code true}. Any other non-{@code null} text in the property is
+     * considered {@code false}.
+     *
+     * @param name the name of the property to look up
+     * @return the boolean value of the property or {@code false} if undefined.
+     */
+    default boolean getBooleanProperty(final String name) {
+        return getBooleanProperty(name, false);
+    }
+
+    /**
+     * Gets the named property as a boolean value.
+     *
+     * @param name         the name of the property to look up
+     * @param defaultValue the default value to use if the property is undefined
+     * @return the boolean value of the property or {@code defaultValue} if undefined.
+     */
+    @Nullable
+    Boolean getBooleanProperty(String name, @Nullable Boolean defaultValue);
+
+    /**
+     * Gets the named property as a Charset value.
+     *
+     * @param name the name of the property to look up
+     * @return the Charset value of the property or {@link Charset#defaultCharset()} if undefined.
+     */
+    default Charset getCharsetProperty(final String name) {
+        return getCharsetProperty(name, Charset.defaultCharset());
+    }
+
+    /**
+     * Gets the named property as a Charset value.
+     *
+     * @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.
+     */
+    @Nullable
+    Charset getCharsetProperty(String name, @Nullable Charset defaultValue);
+
+    /**
+     * Gets the named property as a Class value.
+     *
+     * @param name         the name of the property to look up
+     * @return the Class value of the property or {@code null} if it can not be loaded.
+     */
+    default @Nullable Class<?> getClassProperty(final String name) {
+        return getClassProperty(name, null);
+    }
+
+    /**
+     * Gets the named property as a Class value.
+     *
+     * @param name         the name of the property to look up
+     * @param defaultValue the default value to use if the property is undefined
+     * @return the Class value of the property or {@code defaultValue} if it can not be loaded.
+     */
+    default @Nullable Class<?> getClassProperty(final String name, final @Nullable Class<?> defaultValue) {
+        return getClassProperty(name, defaultValue, Object.class);
+    }
+
+    /**
+     * Gets the named property as a subclass of {@code upperBound}.
+     *
+     * @param name         the name of the property to look up
+     * @param defaultValue the default value to use if the property is undefined
+     * @return the Class value of the property or {@code defaultValue} if it can not be loaded.
+     */
+    <T> @Nullable Class<? extends T> getClassProperty(
+            String name, @Nullable Class<? extends T> defaultValue, Class<T> upperBound);
+
+    /**
+     * Gets the named property as {@link Duration}.
+     *
+     * @param name The property name.
+     * @return The value of the String as a Duration or {@link Duration#ZERO} if it was undefined or could not be parsed.
+     */
+    default Duration getDurationProperty(final String name) {
+        return getDurationProperty(name, Duration.ZERO);
+    }
+
+    /**
+     * Gets the named property as {@link Duration}.
+     *
+     * @param name The property name.
+     * @param defaultValue The default value.
+     * @return The value of the String as a Duration or {@code defaultValue} if it was undefined or could not be parsed.
+     */
+    Duration getDurationProperty(String name, Duration defaultValue);
+
+    /**
+     * Gets the named property as an integer.
+     *
+     * @param name         the name of the property to look up
+     * @return the parsed integer value of the property or {@code 0} if it was undefined or could not be
+     * parsed.
+     */
+    default int getIntegerProperty(final String name) {
+        return getIntegerProperty(name, 0);
+    }
+
+    /**
+     * Gets the named property as an integer.
+     *
+     * @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 integer value of the property or {@code defaultValue} if it was undefined or could not be
+     * parsed.
+     */
+    Integer getIntegerProperty(String name, Integer defaultValue);
+
+    /**
+     * Gets the named property as a long.
+     *
+     * @param name         the name of the property to look up
+     * @return the parsed long value of the property or {@code 0} if it was undefined or could not be
+     * parsed.
+     */
+    default long getLongProperty(final String name) {
+        return getLongProperty(name, 0L);
+    }
+
+    /**
+     * Gets the named property as a long.
+     *
+     * @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 long value of the property or {@code defaultValue} if it was undefined or could not be parsed.
+     */
+    Long getLongProperty(String name, Long defaultValue);
+
+    /**
+     * Gets the named property as a String.
+     *
+     * @param name the name of the property to look up
+     * @return the String value of the property or {@code null} if undefined.
+     */
+    @Nullable
+    String getStringProperty(String name);
+
+    /**
+     * Gets the named property as a String.
+     *
+     * @param name         the name of the property to look up
+     * @param defaultValue the default value to use if the property is undefined
+     * @return the String value of the property or {@code defaultValue} if undefined.
+     */
+    default String getStringProperty(final String name, final String defaultValue) {
+        final String prop = getStringProperty(name);
+        return (prop == null) ? defaultValue : prop;
+    }
+
+    /**
+     * Binds properties to class {@code T}.
+     * <p>
+     *     The implementation should at least support binding Java records with a single public constructor and enums.
+     * </p>
+     * @param propertyClass a class annotated by {@link Log4jProperty}.
+     * @return an instance of T with all JavaBean properties bound.
+     */
+    <T> T getProperty(final Class<T> propertyClass);
+}

log4j-sdk/src/main/java/org/apache/logging/log4j/sdk/env/PropertySource.java

@@ -0,0 +1,48 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.logging.log4j.sdk.env;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Basic interface to retrieve property values.
+ * <p>
+ *     We can not reuse the property sources from 2.x, since those required some sort of {@code log4j} prefix to be
+ *     included. In 3.x we want to use keys without a prefix.
+ * </p>
+ */
+public interface PropertySource {
+    /**
+     * Provides the priority of the property source.
+     * <p>
+     *     Property sources are ordered according to the natural ordering of their priority. Sources with lower
+     *     numerical value take precedence over those with higher numerical value.
+     * </p>
+     *
+     * @return priority value
+     */
+    int getPriority();
+
+    /**
+     * Gets the named property as a String.
+     *
+     * @param name the name of the property to look up
+     * @return the String value of the property or {@code null} if undefined.
+     */
+    @Nullable
+    String getProperty(String name);
+}