    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    }