001 // Copyright 2006, 2007, 2008, 2009 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.model;
016
017 import org.apache.tapestry5.annotations.MixinAfter;
018 import org.apache.tapestry5.annotations.Persist;
019 import org.apache.tapestry5.annotations.SupportsInformalParameters;
020 import org.apache.tapestry5.ioc.Resource;
021 import org.slf4j.Logger;
022
023 import java.util.List;
024 import java.util.Set;
025
026 /**
027 * Defines a component in terms of its capabilities, parameters, sub-components, etc. During <em>runtime</em>, the
028 * component model is immutable. During <em>construction</em> time, when the class is being transformed and loaded, the
029 * model is mutable.
030 *
031 * @see org.apache.tapestry5.model.MutableComponentModel
032 */
033 public interface ComponentModel
034 {
035 /**
036 * Returns the resource corresponding to the class file for this component. This is used to find related resources,
037 * such as the component's template and message catalog.
038 */
039 Resource getBaseResource();
040
041 /**
042 * The FQCN of the component.
043 */
044 String getComponentClassName();
045
046 /**
047 * Returns the ids of all embedded components defined within the component class (via the {@link
048 * org.apache.tapestry5.annotations.Component} annotation), including those defined by any super-class.
049 */
050 List<String> getEmbeddedComponentIds();
051
052 /**
053 * Returns an embedded component defined by this component or by a super-class.
054 *
055 * @param componentId the id of the embedded component
056 * @return the embedded component model, or null if no component exists with that id
057 */
058 EmbeddedComponentModel getEmbeddedComponentModel(String componentId);
059
060 /**
061 * Returns the persistent strategy associated with the field.
062 *
063 * @param fieldName
064 * @return the corresponding strategy, or the empty string
065 * @throws IllegalArgumentException if the named field is not marked as persistent
066 */
067 String getFieldPersistenceStrategy(String fieldName);
068
069 /**
070 * Returns object that will be used to log warnings and errors related to this component.
071 *
072 * @see org.apache.tapestry5.annotations.Log
073 */
074 Logger getLogger();
075
076 /**
077 * Returns a list of the class names of mixins that are part of the component's implementation.
078 */
079 List<String> getMixinClassNames();
080
081 /**
082 * Return a single parameter model by parameter name, or null if the parameter is not defined.
083 *
084 * @param parameterName the name of the parameter (case is ignored)
085 */
086 ParameterModel getParameterModel(String parameterName);
087
088 /**
089 * Returns an alphabetically sorted list of the names of all formal parameters. This includes parameters defined by
090 * a base class.
091 */
092
093 List<String> getParameterNames();
094
095 /**
096 * Returns an alphabetically sorted list of the names of all formal parameters defined by this specific class
097 * (parameters inherited from base classes are not identified).
098 */
099 List<String> getDeclaredParameterNames();
100
101 /**
102 * Returns a list of the names of all persistent fields (within this class, or any super-class). The names are
103 * sorted alphabetically.
104 *
105 * @see Persist
106 */
107 List<String> getPersistentFieldNames();
108
109 /**
110 * Returns true if the modeled component is a root class, a component class whose parent class is not a component
111 * class. We may in the future require that components only extend from Object.
112 *
113 * @return true if a root class, false if a subclass
114 */
115 boolean isRootClass();
116
117 /**
118 * Returns true if the model indicates that informal parameters, additional parameters beyond the formal parameter
119 * defined for the component, are supported. This is false in most cases, but may be set to true for specific
120 * classes (when the {@link SupportsInformalParameters} annotation is present, or inherited from a super-class).
121 *
122 * @return true if this component model supports informal parameters
123 */
124 boolean getSupportsInformalParameters();
125
126 /**
127 * Returns the component model for this component's super-class, if it exists. Remember that only classes in the
128 * correct packages, are considered component classes.
129 *
130 * @return the parent class model, or null if this component's super class is not itself a component class
131 */
132 ComponentModel getParentModel();
133
134 /**
135 * Relevant for component mixins only. Indicates that the mixin behavior should occur <em>after</em> (not before)
136 * the component. Normally, this flag is set by the presence of the {@link MixinAfter} annotation.
137 *
138 * @return true if the mixin should operate after, not before, the component
139 */
140 boolean isMixinAfter();
141
142 /**
143 * Gets a meta value identified by the given key. If the current model does not provide a value for the key, then
144 * the parent component model (if any) is searched.
145 *
146 * @param key identifies the value to be accessed
147 * @return the value for the key (possibly inherited from a parent model), or null
148 */
149 String getMeta(String key);
150
151 /**
152 * Returns a set of all the render phases that this model (including parent models) that are handled. Render phases
153 * are represented by the corresponding annotation ({@link org.apache.tapestry5.annotations.BeginRender}, {@link
154 * org.apache.tapestry5.annotations.AfterRender}, etc.).
155 *
156 * @return set of classes
157 * @since 5.0.19, 5.1.0.0
158 */
159 Set<Class> getHandledRenderPhases();
160
161 /**
162 * Determines if the component has an event handler for the indicated event name (case insensitive). This includes
163 * handles in the component class itself, or its super-classes, but does not include event handles supplied by
164 * implementation or instance mixins.
165 *
166 * @param eventType name of event to check (case insensitive)
167 * @return true if event handler present
168 */
169 boolean handlesEvent(String eventType);
170 }