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 }