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