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 * Claims the field so as to ensure that only a single annotation is applied to any single field.
045 * When a transformation occurs (driven by a field annotation), the field is claimed (using the
046 * annotation object as the tag). If a field has multiple conflicting annotations, this will be discovered when
047 * the code attempts to claim the field a second time.
048 *
049 * @param tag
050 * a non-null object that represents why the field is being tagged (this is typically
051 * a specific annotation on the field)
052 * @throws IllegalStateException
053 * if the field is already claimed for some other tag
054 */
055 void claim(Object tag);
056
057 /**
058 * Replaces read and write field access with a conduit.
059 *
060 * @param conduitProvider
061 * provides the actual conduit at class instantiation time
062 */
063 void replaceAccess(ComponentValueProvider<FieldValueConduit> conduitProvider);
064
065 /**
066 * Replaces read and write field access with a conduit.
067 *
068 * @param conduitField
069 * identifies the field containing (via injection) an instance of {@link FieldValueConduit}
070 */
071 void replaceAccess(TransformField conduitField);
072
073 /**
074 * Replaces read and write field access with a conduit. A new field is created for the conduit instance.
075 *
076 * @param conduit
077 * used to replace read and write access to the field
078 */
079 void replaceAccess(FieldValueConduit conduit);
080
081 /**
082 * Returns the modifiers for the field.
083 *
084 * @see Field#getModifiers()
085 */
086 int getModifiers();
087
088 /**
089 * Converts this field into a read only field whose value is the provided
090 * value. This is used when converting an existing field into a read-only injected value.
091 *
092 * @param value
093 * the value provided by the field
094 */
095 void inject(Object value);
096
097 /**
098 * Like {@link #inject(Object)}, except that the value to be injected is obtained
099 * from a {@link ComponentValueProvider}. It is assumed that the provider will return an object
100 * assignable to the field.
101 *
102 * @param <T>
103 * type of field
104 * @param provider
105 * provides the value to be assigned to the field
106 */
107 <T> void injectIndirect(ComponentValueProvider<T> provider);
108
109 /**
110 * Returns an object that can be used to access the value of the field for read and update.
111 * Changes to the field will honor any {@link FieldValueConduit} that has been applied to the field.
112 */
113 FieldAccess getAccess();
114 }