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    
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         * 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    }