src/main/java/org/apache/commons/lang3/builder/AbstractReflection.java

/*
 * 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.commons.lang3.builder;

import java.lang.reflect.AccessibleObject;
import java.lang.reflect.Field;
import java.util.Set;
import java.util.function.Supplier;

import org.apache.commons.lang3.SystemProperties;
import org.apache.commons.lang3.tuple.Pair;

/**
 * Abstracts reflection access for reflection-based classes in this package.
 * <p>
 * See {@link AbstractBuilder#setForceAccessible(boolean)} for details.
 * </p>
 *
 * @since 3.21.0
 * @see AbstractBuilder#setForceAccessible(boolean)
 * @see AccessibleObject#setAccessible(boolean)
 */
public abstract class AbstractReflection {

    /**
     * Builds an instance of a subclass of {@link AbstractReflection}.
     *
     * @param <B> An AbstractBuilder subclass.
     */
    public abstract static class AbstractBuilder<B extends AbstractBuilder<B>> implements Supplier<AbstractReflection> {

        /**
         * Whether the {@link AbstractReflection} subclass will call {@link AccessibleObject#setAccessible(boolean) AccessibleObject#setAccessible(true)} on
         * inaccessible fields.
         */
        private boolean forceAccessible = getForceAccessible();

        /**
         * Constructs a new instance for a subclass.
         */
        AbstractBuilder() {
            // Empty.
        }

        /**
         * Returns {@code this} instance typed as its subclass.
         *
         * @return {@code this} instance typed as its subclass.
         */
        @SuppressWarnings("unchecked")
        protected B asThis() {
            return (B) this;
        }

        /**
         * Whether the {@link AbstractReflection} subclass will call {@link AccessibleObject#setAccessible(boolean) AccessibleObject#setAccessible(true)} on
         * inaccessible fields.
         * <p>
         * In general, controls whether the instances built by this builder will force the accessible flag for reflection.
         * </p>
         * <p>
         * Defaults to {@code getForceAccessible()}, which defaults to true for compatibility.
         * </p>
         * <p>
         * This default is read from the system property {@code "AbstractReflection.forceAccessible"}, which defaults to true for compatibility.
         * </p>
         * <p>
         * The parsing rules are as {@link Boolean#parseBoolean(String)}.
         * </p>
         * <p>
         * See subclassses for specific behavior.
         * </p>
         *
         * @param forceAccessible Whether to force accessibility by calling {@link AccessibleObject#setAccessible(boolean)
         *                        AccessibleObject#setAccessible(true)}.
         * @return {@code this} instance.
         * @see AccessibleObject#setAccessible(boolean)
         */
        public B setForceAccessible(final boolean forceAccessible) {
            this.forceAccessible = forceAccessible;
            return asThis();
        }
    }

    /**
     * Tests whether the system property {@code "AbstractReflection.forceAccessible"} is set to true.
     * <p>
     * The parsing rules are as {@link Boolean#parseBoolean(String)}.
     * </p>
     * <p>
     * If the property is not set, return true.
     * </p>
     *
     * @return whether the system property {@code "AbstractReflection.forceAccessible"} is set to true with true as the default.
     * @see Boolean#parseBoolean(String)
     */
    static boolean getForceAccessible() {
        return SystemProperties.getBoolean(AbstractReflection.class, "forceAccessible", () -> true);
    }

    static boolean isRegistered(final Object lhs, final Object rhs, final Set<Pair<IDKey, IDKey>> registry) {
        final Pair<IDKey, IDKey> pair = toRegisterPair(lhs, rhs);
        final Pair<IDKey, IDKey> swappedPair = Pair.of(pair.getRight(), pair.getLeft());
        return registry != null && (registry.contains(pair) || registry.contains(swappedPair));
    }

    static void register(final Object lhs, final Object rhs, final Set<Pair<IDKey, IDKey>> registry) {
        registry.add(toRegisterPair(lhs, rhs));
    }

    /**
     * If {@code forceAccessible} flag is true, then the field is made accessible by calling {@link AccessibleObject#setAccessible(boolean)
     * AccessibleObject#setAccessible(true)} but <em>only</em> if a field is not already accessible.
     *
     * @param forceAccessible Whether to call {@link AccessibleObject#setAccessible(boolean)} if a field is not already accessible.
     * @param field          The field to set.
     * @return true if the field is accessible, false otherwise.
     * @throws SecurityException Thrown if {@code forceAccessible} flag is true and the request is denied.
     * @see AccessibleObject#setAccessible(boolean)
     * @see SecurityManager#checkPermission
     */
    static boolean setAccessible(final boolean forceAccessible, final Field field) {
        return !field.isAccessible() && forceAccessible && setAccessibleTrue(field);
    }

    /**
     * Sets the field as accessible by calling {@link AccessibleObject#setAccessible(boolean) AccessibleObject#setAccessible(true)} but <em>only</em> if a field
     * is not already accessible.
     *
     * @param field The field to set, may be null.
     * @return true if the field is accessible, false otherwise.
     * @throws SecurityException Thrown if {@code forceAccessible} flag is true and the request is denied.
     * @see AccessibleObject#setAccessible(boolean)
     * @see SecurityManager#checkPermission
     */
    private static boolean setAccessibleTrue(final Field field) {
        if (field != null) {
            // Test isAccessible() to avoid the permission check.
            if (!field.isAccessible()) {
                field.setAccessible(true);
            }
            return field.isAccessible();
        }
        return false;
    }

    /**
     * Converters value pair into a register pair.
     *
     * @param lhs {@code this} object.
     * @param rhs the other object.
     * @return the pair.
     */
    static Pair<IDKey, IDKey> toRegisterPair(final Object lhs, final Object rhs) {
        return Pair.of(new IDKey(lhs), new IDKey(rhs));
    }

    static void unregister(final Object lhs, final Object rhs, final Set<Pair<IDKey, IDKey>> registry, final ThreadLocal<Set<Pair<IDKey, IDKey>>> registryTL) {
        registry.remove(toRegisterPair(lhs, rhs));
        if (registry.isEmpty()) {
            registryTL.remove();
        }
    }

    /**
     * Whether to call {@link AccessibleObject#setAccessible(boolean) AccessibleObject#setAccessible(true)} on inaccessible fields.
     */
    private final boolean forceAccessible;

    /**
     * Constructs a new instance.
     *
     * @param <T>     The type to build.
     * @param builder The builder.
     */
    <T extends AbstractBuilder<T>> AbstractReflection(final AbstractBuilder<T> builder) {
        this.forceAccessible = builder.forceAccessible;
    }

    /**
     * Tests whether fields should be made accessible with {@link AccessibleObject#setAccessible(boolean)}.
     *
     * @return whether fields should be made accessible with {@link AccessibleObject#setAccessible(boolean)}.
     */
    protected boolean isForceAccessible() {
        return forceAccessible;
    }

    /**
     * If {@code forceAccessible} flag is true, each field in the given array is made accessible by calling {@link AccessibleObject#setAccessible(boolean)
     * AccessibleObject#setAccessible(true)} but <em>only</em> if a field is not already accessible.
     *
     * @param field The fields to set.
     * @throws SecurityException Thrown if {@code forceAccessible} flag is true and the request is denied.
     * @return true if the field is accessible, false otherwise.
     * @see AccessibleObject#setAccessible(boolean)
     * @see SecurityManager#checkPermission
     */
    boolean setAccessible(final Field field) {
        return setAccessible(isForceAccessible(), field);
    }
}