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    }