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