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
015package org.apache.tapestry5.services;
016
017import java.lang.reflect.Field;
018
019import org.apache.tapestry5.ioc.AnnotationProvider;
020import 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 */
029public 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}