/******************************************************************************
* Copyright (C) 2016 Yevgeny Krasik *
* *
* Licensed 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 com.github.ykrasik.jaci.reflection;
import java.lang.reflect.Constructor;
/**
* Reflection information about a field.
* Used due to lack of support for java.lang.reflect classes in GWT.
*
* @author Yevgeny Krasik
*/
public interface ReflectionField {
/**
* Returns a {@code Class} object that identifies the
* declared type for the field represented by this
* {@code Field} object.
*
* @return a {@code Class} object identifying the declared
* type of the field represented by this object
*/
Class<?> getType();
/**
* 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
*/
void setAccessible(boolean flag);
/**
* Sets the field represented by this {@code Field} object on the
* specified object argument to the specified new value. The new
* value is automatically unwrapped if the underlying field has a
* primitive type.
*
* <p>The operation proceeds as follows:
*
* <p>If the underlying field is static, the {@code obj} argument is
* ignored; it may be null.
*
* <p>Otherwise the underlying field is an instance field. If the
* specified object argument is null, the method throws a
* {@code NullPointerException}. If the specified object argument is not
* an instance of the class or interface declaring the underlying
* field, the method throws an {@code IllegalArgumentException}.
*
* <p>If this {@code Field} object is enforcing Java language access control, and
* the underlying field is inaccessible, the method throws an
* {@code IllegalAccessException}.
*
* <p>If the underlying field is final, the method throws an
* {@code IllegalAccessException} unless {@code setAccessible(true)}
* has succeeded for this {@code Field} object
* and the field is non-static. Setting a final field in this way
* is meaningful only during deserialization or reconstruction of
* instances of classes with blank final fields, before they are
* made available for access by other parts of a program. Use in
* any other context may have unpredictable effects, including cases
* in which other parts of a program continue to use the original
* value of this field.
*
* <p>If the underlying field is of a primitive type, an unwrapping
* conversion is attempted to convert the new value to a value of
* a primitive type. If this attempt fails, the method throws an
* {@code IllegalArgumentException}.
*
* <p>If, after possible unwrapping, the new value cannot be
* converted to the type of the underlying field by an identity or
* widening conversion, the method throws an
* {@code IllegalArgumentException}.
*
* <p>If the underlying field is static, the class that declared the
* field is initialized if it has not already been initialized.
*
* <p>The field is set to the possibly unwrapped and widened new value.
*
* <p>If the field is hidden in the type of {@code obj},
* the field's value is set according to the preceding rules.
*
* @param obj the object whose field should be modified
* @param value the new value for the field of {@code obj}
* being modified
*
* @exception IllegalAccessException if this {@code Field} object
* is enforcing Java language access control and the underlying
* field is either inaccessible or final.
* @exception IllegalArgumentException if the specified object is not an
* instance of the class or interface declaring the underlying
* field (or a subclass or implementor thereof),
* or if an unwrapping conversion fails.
* @exception NullPointerException if the specified object is null
* and the field is an instance field.
* @exception ExceptionInInitializerError if the initialization provoked
* by this method fails.
*/
void set(Object obj, Object value) throws Exception;
}