    001// Copyright 2006, 2007, 2008, 2009, 2010 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.Parameter;
    018import org.apache.tapestry5.annotations.Persist;
    019import org.apache.tapestry5.internal.InternalComponentResources;
    020import org.apache.tapestry5.ioc.Location;
    021
    022/**
    023 * Mutable version of {@link org.apache.tapestry5.model.ComponentModel} used during the transformation phase.
    024 */
    025public interface MutableComponentModel extends ComponentModel
    026{
    027    /**
    028     * Adds a new formal parameter to the model. Each parameter has a unique name (though access to parameters is case
    029     * insensitive).
    030     *
    031     * @param name                 new, unique name for the parameter
    032     * @param required             if true, the parameter must be bound
    033     * @param allowNull            if true, then parameter may be bound to null, if false a null check will be added
    034     * @param defaultBindingPrefix the default binding prefix for this parameter @throws IllegalArgumentException if a
    035     *                             parameter with the given name has already been defined for this model
    036     * @see Parameter
    037     * @deprecated Use {@link #addParameter(String, boolean, boolean, String, boolean)} instead.
    038     */
    039    void addParameter(String name, boolean required, boolean allowNull, String defaultBindingPrefix);
    040
    041    /**
    042     * Adds a new formal parameter to the model. Each parameter has a unique name (though access to parameters is case
    043     * insensitive).
    044     *
    045     * @param name                 new, unique name for the parameter
    046     * @param required             if true, the parameter must be bound
    047     * @param allowNull            if true, then parameter may be bound to null, if false a null check will be added
    048     * @param defaultBindingPrefix the default binding prefix for this parameter @throws IllegalArgumentException if a
    049     *                             parameter with the given name has already been defined for this model
    050     * @param cached               if true, the parameter value should be cached within the component during rendering
    051     * @see org.apache.tapestry5.annotations.Parameter
    052     * @since 5.2.0.0
    053     */
    054    public void addParameter(String name, boolean required, boolean allowNull, String defaultBindingPrefix,boolean cached);
    055
    056
    057    /**
    058     * Defines a new embedded component.
    059     *
    060     * @param id                        the unique id for the embedded component, which must not already exist.
    061     * @param type                      the type of the component (posslibly blank)
    062     * @param componentClassName        the fully qualified class name (derived from the field), used if the type is
    063     *                                  blank
    064     * @param inheritInformalParameters if true, then the component will inherit informal parameters provided to its
    065     *                                  container
    066     * @param location                  where the component is defined @return a mutable model allowing parameters to be
    067     *                                  set
    068     */
    069    MutableEmbeddedComponentModel addEmbeddedComponent(String id, String type, String componentClassName,
    070                                                       boolean inheritInformalParameters, Location location);
    071
    072    /**
    073     * Used to define the field persistence strategy for a particular field name. Returns a logical name for the field,
    074     * which is guaranteed to be unique (this is necessary for handling the case where a subclass has a persistent field
    075     * with the same name as a persistent field from a super-class).
    076     *
    077     * @param fieldName the name of the field which is to be made persistent
    078     * @param strategy  the strategy for persisting the field, from {@link Persist#value()}. This value may be blank, in
    079     *                  which case the stategy is inherited from the component, or the component's container.
    080     * @return a logical name for the field, to be used with {@link ComponentModel#getFieldPersistenceStrategy(String)},
    081     *         and with {@link InternalComponentResources#persistFieldChange(String, Object)}, etc.
    082     */
    083    String setFieldPersistenceStrategy(String fieldName, String strategy);
    084
    085    /**
    086     * Adds a mixin to the component's implementation, optionally specifying ordering constraints, as per OrderedConfiguration.
    087     * @since 5.2.0.0
    088     */
    089    void addMixinClassName(String mixinClassName, String... order);
    090
    091    /**
    092     * Sets the internal flag to indicate that this model (and all models that extend from it) support informal
    093     * parameters.
    094     */
    095    void enableSupportsInformalParameters();
    096
    097    /**
    098     * Changes the value of the mixinAfter flag. The default value is false.
    099     */
    100    void setMixinAfter(boolean mixinAfter);
    101
    102    /**
    103     * Stores a meta data value under the indicated key.
    104     */
    105    void setMeta(String key, String value);
    106
    107    /**
    108     * Identifies that the component does handle the render phase.
    109     *
    110     * @param renderPhase annotation class corresponding to the render phase
    111     * @see ComponentModel#getHandledRenderPhases()
    112     * @since 5.0.19, 5.1.0.0
    113     */
    114    void addRenderPhase(Class renderPhase);
    115
    116    /**
    117     * Identifies that the component includes an event handler for the indicated event type.
    118     *
    119     * @param eventType of handled event
    120     * @since 5.1.0.0
    121     */
    122    void addEventHandler(String eventType);
    123
    124    /**
    125     * Relevant for pages only, identifies that the component handle {@link org.apache.tapestry5.EventConstants.ACTIVATE}
    126     * events supporting one of the three special case for catch all rules:
    127     * <ul>
    128     *     <li><code>{@link java.lang.Object}[]</code></li>
    129     *     <li><code>{@link java.util.List}</code></li>
    130     *     <li><code>{@link org.apache.tapestry5.EventContext}</code></li>
    131     * </ul>
    132     *
    133     * @since 5.4
    134     */
    135    void doHandleActivationEventContext();
    136}