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