/*

 * Copyright 1997-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.lang.reflect;

import java.security.AccessController;

import sun.reflect.ReflectionFactory;

import java.lang.annotation.Annotation;

/**

 * The AccessibleObject class is the base class for Field, Method and

 * Constructor objects.  It provides the ability to flag a reflected

 * object as suppressing default Java language access control checks

 * when it is used.  The access checks--for public, default (package)

 * access, protected, and private members--are performed when Fields,

 * Methods or Constructors are used to set or get fields, to invoke

 * methods, or to create and initialize new instances of classes,

 * respectively.

 *

 * <p>Setting the {@code accessible} flag in a reflected object

 * permits sophisticated applications with sufficient privilege, such

 * as Java Object Serialization or other persistence mechanisms, to

 * manipulate objects in a manner that would normally be prohibited.

 *

 * @see Field

 * @see Method

 * @see Constructor

 * @see ReflectPermission

 *

 * @since 1.2

 */

public class AccessibleObject implements AnnotatedElement {

    /**

     * The Permission object that is used to check whether a client

     * has sufficient privilege to defeat Java language access

     * control checks.

     */

    static final private java.security.Permission ACCESS_PERMISSION =

        new ReflectPermission("suppressAccessChecks");

    /**

     * Convenience method to set the {@code accessible} flag for an

     * array of objects with a single security check (for efficiency).

     *

     * <p>First, if there is a security manager, its

     * {@code checkPermission} method is called with a

     * {@code ReflectPermission("suppressAccessChecks")} permission.

     *

     * <p>A {@code SecurityException} is raised if {@code flag} is

     * {@code true} but accessibility of any of the elements of the input

     * {@code array} may not be changed (for example, if the element

     * object is a {@link Constructor} object for the class {@link

     * java.lang.Class}).  In the event of such a SecurityException, the

     * accessibility of objects is set to {@code flag} for array elements

     * upto (and excluding) the element for which the exception occurred; the

     * accessibility of elements beyond (and including) the element for which

     * the exception occurred is unchanged.

     *

     * @param array the array of AccessibleObjects

     * @param flag  the new value for the {@code accessible} flag

     *              in each object

     * @throws SecurityException if the request is denied.

     * @see SecurityManager#checkPermission

     * @see java.lang.RuntimePermission

     */

    public static void setAccessible(AccessibleObject[] array, boolean flag)

        throws SecurityException {

        SecurityManager sm = System.getSecurityManager();

        if (sm != null) sm.checkPermission(ACCESS_PERMISSION);

        for (int i = 0; i < array.length; i++) {

            setAccessible0(array[i], flag);

        }

    }

    /**

     * Set the {@code accessible} flag for this object to

     * the indicated boolean value.  A value of {@code true} indicates that

     * the reflected object should suppress Java language access

     * checking when it is used.  A value of {@code false} indicates

     * that the reflected object should enforce Java language access checks.

     *

     * <p>First, if there is a security manager, its

     * {@code checkPermission} method is called with a

     * {@code ReflectPermission("suppressAccessChecks")} permission.

     *

     * <p>A {@code SecurityException} is raised if {@code flag} is

     * {@code true} but accessibility of this object may not be changed

     * (for example, if this element object is a {@link Constructor} object for

     * the class {@link java.lang.Class}).

     *

     * <p>A {@code SecurityException} is raised if this object is a {@link

     * java.lang.reflect.Constructor} object for the class

     * {@code java.lang.Class}, and {@code flag} is true.

     *

     * @param flag the new value for the {@code accessible} flag

     * @throws SecurityException if the request is denied.

     * @see SecurityManager#checkPermission

     * @see java.lang.RuntimePermission

     */

    public void setAccessible(boolean flag) throws SecurityException {

        SecurityManager sm = System.getSecurityManager();

        if (sm != null) sm.checkPermission(ACCESS_PERMISSION);

        setAccessible0(this, flag);

    }

    /* Check that you aren't exposing java.lang.Class.<init>. */

    private static void setAccessible0(AccessibleObject obj, boolean flag)

        throws SecurityException

    {

        if (obj instanceof Constructor && flag == true) {

            Constructor c = (Constructor)obj;

            if (c.getDeclaringClass() == Class.class) {

                throw new SecurityException("Can not make a java.lang.Class" +

                                            " constructor accessible");

            }

        }

        obj.override = flag;

    }

    /**

     * Get the value of the {@code accessible} flag for this object.

     *

     * @return the value of the object's {@code accessible} flag

     */

    public boolean isAccessible() {

        return override;

    }

    /**

     * Constructor: only used by the Java Virtual Machine.

     */

    protected AccessibleObject() {}

    // Indicates whether language-level access checks are overridden

    // by this object. Initializes to "false". This field is used by

    // Field, Method, and Constructor.

    //

    // NOTE: for security purposes, this field must not be visible

    // outside this package.

    boolean override;

    // Reflection factory used by subclasses for creating field,

    // method, and constructor accessors. Note that this is called

    // very early in the bootstrapping process.

    static final ReflectionFactory reflectionFactory = (ReflectionFactory)

        AccessController.doPrivileged

            (new sun.reflect.ReflectionFactory.GetReflectionFactoryAction());

    /**

     * @throws NullPointerException {@inheritDoc}

     * @since 1.5

     */

    public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {

        throw new AssertionError("All subclasses should override this method");

    }

    /**

     * @throws NullPointerException {@inheritDoc}

     * @since 1.5

     */

    public boolean isAnnotationPresent(

        Class<? extends Annotation> annotationClass) {

        return getAnnotation(annotationClass) != null;

    }

    /**

     * @since 1.5

     */

    public Annotation[] getAnnotations() {

        return getDeclaredAnnotations();

    }

    /**

     * @since 1.5

     */

    public Annotation[] getDeclaredAnnotations()  {

        throw new AssertionError("All subclasses should override this method");

    }

}