    001    // Copyright 2010, 2011 The Apache Software Foundation
    002    //
    003    // Licensed under the Apache License, Version 2.0 (the "License");
    004    // you may not use this file except in compliance with the License.
    005    // You may obtain a copy of the License at
    006    //
    007    // http://www.apache.org/licenses/LICENSE-2.0
    008    //
    009    // Unless required by applicable law or agreed to in writing, software
    010    // distributed under the License is distributed on an "AS IS" BASIS,
    011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012    // See the License for the specific language governing permissions and
    013    // limitations under the License.
    014
    015    package org.apache.tapestry5.services;
    016
    017    import java.lang.reflect.Field;
    018
    019    import org.apache.tapestry5.ioc.AnnotationProvider;
    020    import org.apache.tapestry5.ioc.services.FieldValueConduit;
    021
    022    /**
    023     * A field defined by (or created within) a {@link ClassTransformation},
    024     * allowing the details of the field to be
    025     * accessed or modified.
    026     *
    027     * @since 5.2.0
    028     */
    029    public interface TransformField extends AnnotationProvider, Comparable<TransformField>
    030    {
    031        /**
    032         * Returns the name of the field.
    033         */
    034        String getName();
    035
    036        /**
    037         * Returns the field's type, either a primitive name (such as "int" or "boolean")
    038         * or a fully qualified class name, or an array type name
    039         * (in Java source syntax, i.e., "java.lang.String[]").
    040         */
    041        String getType();
    042
    043        /**
    044         * Returns the field's fully qualified generic type, or null if not defined.
    045         * (in Java source syntax, i.e., "()Ljava/util/List<Ljava/lang/String;>;"
    046         *
    047         * @since 5.3
    048         */
    049        String getSignature();
    050
    051        /**
    052         * Claims the field so as to ensure that only a single annotation is applied to any single field.
    053         * When a transformation occurs (driven by a field annotation), the field is claimed (using the
    054         * annotation object as the tag). If a field has multiple conflicting annotations, this will be discovered when
    055         * the code attempts to claim the field a second time.
    056         *
    057         * @param tag
    058         *            a non-null object that represents why the field is being tagged (this is typically
    059         *            a specific annotation on the field)
    060         * @throws IllegalStateException
    061         *             if the field is already claimed for some other tag
    062         */
    063        void claim(Object tag);
    064
    065        /**
    066         * Replaces read and write field access with a conduit.
    067         *
    068         * @param conduitProvider
    069         *            provides the actual conduit at class instantiation time
    070         */
    071        void replaceAccess(ComponentValueProvider<FieldValueConduit> conduitProvider);
    072
    073        /**
    074         * Replaces read and write field access with a conduit.
    075         *
    076         * @param conduitField
    077         *            identifies the field containing (via injection) an instance of {@link FieldValueConduit}
    078         */
    079        void replaceAccess(TransformField conduitField);
    080
    081        /**
    082         * Replaces read and write field access with a conduit. A new field is created for the conduit instance.
    083         *
    084         * @param conduit
    085         *            used to replace read and write access to the field
    086         */
    087        void replaceAccess(FieldValueConduit conduit);
    088
    089        /**
    090         * Returns the modifiers for the field.
    091         *
    092         * @see Field#getModifiers()
    093         */
    094        int getModifiers();
    095
    096        /**
    097         * Converts this field into a read only field whose value is the provided
    098         * value. This is used when converting an existing field into a read-only injected value.
    099         *
    100         * @param value
    101         *            the value provided by the field
    102         */
    103        void inject(Object value);
    104
    105        /**
    106         * Like {@link #inject(Object)}, except that the value to be injected is obtained
    107         * from a {@link ComponentValueProvider}. It is assumed that the provider will return an object
    108         * assignable to the field.
    109         *
    110         * @param <T>
    111         *            type of field
    112         * @param provider
    113         *            provides the value to be assigned to the field
    114         */
    115        <T> void injectIndirect(ComponentValueProvider<T> provider);
    116
    117        /**
    118         * Returns an object that can be used to access the value of the field for read and update.
    119         * Changes to the field will honor any {@link FieldValueConduit} that has been applied to the field.
    120         */
    121        FieldAccess getAccess();
    122    }