/*
 * 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.juneau.commons.reflect;

import static org.apache.juneau.commons.utils.ClassUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;

import java.lang.reflect.*;

/**
 * Defines class/field/method visibilities.
 *
 * <p>
 * Used to specify minimum levels of visibility when detecting bean classes, methods, and fields.
 *
 * <p>
 * Used in conjunction with the following bean context properties:
 * <ul class='javatree'>
 *    <li class='jm'>MarshallingContext.Builder.beanConstructorVisibility
 *    <li class='jm'>MarshallingContext.Builder.beanClassVisibility
 *    <li class='jm'>MarshallingContext.Builder.beanFieldVisibility
 *    <li class='jm'>MarshallingContext.Builder.beanMethodVisibility
 * </ul>
 *
 */
@SuppressWarnings({
   "java:S1192" // Duplicated literals (argument/property names) read more clearly inline than as constants
})
public enum Visibility {

   /** Ignore all */
   NONE,

   /** Include only <jk>public</jk> classes/fields/methods. */
   PUBLIC,

   /** Include only <jk>public</jk> or <jk>protected</jk> classes/fields/methods. */
   PROTECTED,

   /** Include all but <jk>private</jk> classes/fields/methods. */
   DEFAULT,

   /** Include all classes/fields/methods. */
   PRIVATE;

   /**
    * Shortcut for <c>isVisible(x.getModifiers());</c>
    *
    * @param x The class to check. Must not be <jk>null</jk>.
    * @return <jk>true</jk> if the class is at least as visible as this object.
    */
   public boolean isVisible(Class<?> x) {
      return isVisible(x.getModifiers());
   }

   /**
    * Shortcut for <c>isVisible(x.getModifiers());</c>
    *
    * @param x The constructor to check. Must not be <jk>null</jk>.
    * @return <jk>true</jk> if the constructor is at least as visible as this object.
    */
   public boolean isVisible(Executable x) {
      return isVisible(x.getModifiers());
   }

   /**
    * Shortcut for <c>isVisible(x.getModifiers());</c>
    *
    * @param x The field to check. Must not be <jk>null</jk>.
    * @return <jk>true</jk> if the field is at least as visible as this object.
    */
   public boolean isVisible(Field x) {
      return isVisible(x.getModifiers());
   }

   /**
    * Identifies if the specified mod matches this visibility.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jsf>PUBLIC</jsf>.isVisible(MyPublicClass.<jk>class</jk>.getModifiers()); <jc>//true</jc>
    *    <jsf>PUBLIC</jsf>.isVisible(MyPrivateClass.<jk>class</jk>.getModifiers()); <jc>//false</jc>
    *    <jsf>PRIVATE</jsf>.isVisible(MyPrivateClass.<jk>class</jk>.getModifiers()); <jc>//true</jc>
    *    <jsf>NONE</jsf>.isVisible(MyPublicClass.<jk>class</jk>.getModifiers()); <jc>//false</jc>
    * </p>
    *
    * @param mod The modifier from the object being tested (e.g. results from {@link Class#getModifiers()}.
    * @return <jk>true</jk> if this visibility matches the specified modifier attribute.
    */
   public boolean isVisible(int mod) {
      return switch (this) {
         case NONE -> false;
         case PRIVATE -> true;
         case DEFAULT -> ! Modifier.isPrivate(mod);
         case PROTECTED -> Modifier.isProtected(mod) || Modifier.isPublic(mod);
         default -> Modifier.isPublic(mod);
      };
   }

   /**
    * Makes constructor accessible if it matches the visibility requirements, or returns <jk>null</jk> if it doesn't.
    *
    * <p>
    * Security exceptions thrown on the call to {@link Constructor#setAccessible(boolean)} are quietly ignored.
    *
    * @param <T> The class type.
    * @param x The constructor. Must not be <jk>null</jk>.
    * @return
    *    The same constructor if visibility requirements met, or <jk>null</jk> if visibility requirement not
    *    met or call to {@link Constructor#setAccessible(boolean)} throws a security exception.
    * @throws IllegalArgumentException If <c>x</c> is <jk>null</jk>.
    */
   public <T> Constructor<T> transform(Constructor<T> x) {
      reqnn("x", x);
      if (isVisible(x) && ! setAccessible(x))
         return null;  // HTT
      return x;
   }

   /**
    * Makes field accessible if it matches the visibility requirements, or returns <jk>null</jk> if it doesn't.
    *
    * <p>
    * Security exceptions thrown on the call to {@link Field#setAccessible(boolean)} are quietly ignored.
    *
    * @param x The field. Must not be <jk>null</jk>.
    * @return
    *    The same field if visibility requirements met, or <jk>null</jk> if visibility requirement not
    *    met or call to {@link Field#setAccessible(boolean)} throws a security exception.
    * @throws IllegalArgumentException If <c>x</c> is <jk>null</jk>.
    */
   public Field transform(Field x) {
      reqnn("x", x);
      if (isVisible(x) && ! setAccessible(x))
         return null;  // HTT
      return x;
   }

   /**
    * Makes method accessible if it matches the visibility requirements, or returns <jk>null</jk> if it doesn't.
    *
    * <p>
    * Security exceptions thrown on the call to {@link Method#setAccessible(boolean)} are quietly ignored.
    *
    * @param x The method. Must not be <jk>null</jk>.
    * @return
    *    The same method if visibility requirements met, or <jk>null</jk> if visibility requirement not
    *    met or call to {@link Method#setAccessible(boolean)} throws a security exception.
    * @throws IllegalArgumentException If <c>x</c> is <jk>null</jk>.
    */
   public Method transform(Method x) {
      reqnn("x", x);
      if (isVisible(x) && ! setAccessible(x))
         return null;  // HTT
      return x;
   }
}