001// Licensed under the Apache License, Version 2.0 (the "License");
002// you may not use this file except in compliance with the License.
003// You may obtain a copy of the License at
004//
005//     http://www.apache.org/licenses/LICENSE-2.0
006//
007// Unless required by applicable law or agreed to in writing, software
008// distributed under the License is distributed on an "AS IS" BASIS,
009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010// See the License for the specific language governing permissions and
011// limitations under the License.
012
013package org.apache.tapestry5.model;
014
015import org.apache.tapestry5.EventConstants;
016import org.apache.tapestry5.annotations.*;
017import org.apache.tapestry5.commons.Resource;
018import org.apache.tapestry5.services.ComponentClassResolver;
019import org.apache.tapestry5.services.LibraryMapping;
020import org.slf4j.Logger;
021
022import java.util.List;
023import java.util.Set;
024
025/**
026 * Defines a component in terms of its capabilities, parameters, sub-components, etc. During <em>runtime</em>, the
027 * component model is immutable. During <em>construction</em> time, when the class is being transformed and loaded, the
028 * model is mutable.
029 *
030 * @see org.apache.tapestry5.model.MutableComponentModel
031 */
032public interface ComponentModel
033{
034    /**
035     * Returns the name of the library that defines this component; this may be the empty string for
036     * an application page or component, or will be a name of a library (possibly including "core" for built-in
037     * components).
038     * Library names are defined by the {@link LibraryMapping} contributions
039     * to the {@link ComponentClassResolver} service.
040     *
041     * @return library name containing the component, or empty string for application components
042     * @since 5.4
043     */
044    String getLibraryName();
045
046    /**
047     * Is this a model of a page (rather than a component, mixin, or base-class)?
048     *
049     * @return true if a page
050     * @since 5.3
051     */
052    boolean isPage();
053
054    /**
055     * Returns the resource corresponding to the class file for this component. This is used to find related resources,
056     * such as the component's template and message catalog.
057     */
058    Resource getBaseResource();
059
060    /**
061     * The fully qualified class name of the component.
062     */
063    String getComponentClassName();
064
065    /**
066     * Returns the ids of all embedded components defined within the component class (via the {@link
067     * Component} annotation), including those defined by any super-class.
068     */
069    List<String> getEmbeddedComponentIds();
070
071    /**
072     * Returns an embedded component defined by this component or by a super-class.
073     *
074     * @param componentId
075     *         the id of the embedded component
076     * @return the embedded component model, or null if no component exists with that id
077     */
078    EmbeddedComponentModel getEmbeddedComponentModel(String componentId);
079
080    /**
081     * Returns the persistent strategy associated with the field.
082     *
083     * @param fieldName
084     * @return the corresponding strategy, or the empty string
085     * @throws IllegalArgumentException
086     *         if the named field is not marked as persistent
087     */
088    String getFieldPersistenceStrategy(String fieldName);
089
090    /**
091     * Returns object that will be used to log warnings and errors related to this component.
092     *
093     * @see org.apache.tapestry5.annotations.Log
094     */
095    Logger getLogger();
096
097    /**
098     * Returns a list of the class names of mixins that are part of the component's implementation.
099     */
100    List<String> getMixinClassNames();
101
102    /**
103     * Return a single parameter model by parameter name, or null if the parameter is not defined (is not
104     * a formal parameter). This may be a parameter defined by this component, or from a base class.
105     *
106     * @param parameterName
107     *         the name of the parameter (case is ignored)
108     * @return the parameter model if found in this model or a parent model, or null if not found
109     */
110    ParameterModel getParameterModel(String parameterName);
111
112    /**
113     * Returns true if the named parameter is formally defined (there's a ParameterModel).
114     *
115     * @param parameterName
116     *         name of the parameter (case is ignored)
117     * @since 5.2.0
118     */
119    boolean isFormalParameter(String parameterName);
120
121    /**
122     * Returns an alphabetically sorted list of the names of all formal parameters. This includes parameters defined by
123     * a base class.
124     */
125
126    List<String> getParameterNames();
127
128    /**
129     * Returns an alphabetically sorted list of the names of all formal parameters defined by this specific class
130     * (parameters inherited from base classes are not identified).
131     */
132    List<String> getDeclaredParameterNames();
133
134    /**
135     * Returns a list of the names of all persistent fields (within this class, or any super-class). The names are
136     * sorted alphabetically.
137     *
138     * @see Persist
139     */
140    List<String> getPersistentFieldNames();
141
142    /**
143     * Returns true if the modeled component is a root class, a component class whose parent class is not a component
144     * class.  We may in the future require that components only extend from Object.
145     *
146     * @return true if a root class, false if a subclass
147     */
148    boolean isRootClass();
149
150    /**
151     * Returns true if the model indicates that informal parameters, additional parameters beyond the formal parameter
152     * defined for the component, are supported. This is false in most cases, but may be set to true for specific
153     * classes (when the {@link SupportsInformalParameters} annotation is present, or inherited from a super-class).
154     *
155     * @return true if this component model supports informal parameters
156     */
157    boolean getSupportsInformalParameters();
158
159    /**
160     * Returns the component model for this component's super-class, if it exists. Remember that only classes in the
161     * correct packages, are considered component classes.
162     *
163     * @return the parent class model, or null if this component's super class is not itself a component class
164     */
165    ComponentModel getParentModel();
166
167    /**
168     * Relevant for component mixins only. Indicates that the mixin behavior should occur <em>after</em> (not before)
169     * the component. Normally, this flag is set by the presence of the {@link MixinAfter} annotation.
170     *
171     * @return true if the mixin should operate after, not before, the component
172     */
173    boolean isMixinAfter();
174
175    /**
176     * Gets a meta value identified by the given key. If the current model does not provide a value for the key, then
177     * the parent component model (if any) is searched.
178     *
179     * @param key
180     *         identifies the value to be accessed
181     * @return the value for the key (possibly inherited from a parent model), or null
182     */
183    String getMeta(String key);
184
185    /**
186     * Returns a set of all the render phases that this model (including parent models) that are handled. Render phases
187     * are represented by the corresponding annotation ({@link BeginRender}, {@link AfterRender}, etc.).
188     *
189     * @return set of classes
190     * @since 5.0.19, 5.1.0.0
191     */
192    Set<Class> getHandledRenderPhases();
193
194    /**
195     * Determines if the component has an event handler for the indicated event name (case insensitive). This includes
196     * handlers in the component class itself, or its super-classes, but does not include event handlers supplied by
197     * implementation or instance mixins.
198     *
199     * @param eventType
200     *         name of event to check (case insensitive)
201     * @return true if event handler present
202     */
203    boolean handlesEvent(String eventType);
204
205    /**
206     * @param mixinClassName
207     *         class name of the mixin for which the ordering is desired
208     * @return the ordering constraint(s) for the mixin, potentially null.
209     * @since 5.2.0
210     */
211    String[] getOrderForMixin(String mixinClassName);
212
213    /**
214     * Relevant for pages only, indicates that the component handle the {@link EventConstants#ACTIVATE}
215     * events with a catch all rules
216     *
217     * @return true if the page implements catch all rules for the activate event context, or false otherwise
218     * @see MutableComponentModel#doHandleActivationEventContext()
219     * @since 5.4
220     */
221    boolean handleActivationEventContext();
222}