    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
    015    package org.apache.tapestry5.model;
    016
    017    import org.apache.tapestry5.annotations.Parameter;
    018    import org.apache.tapestry5.annotations.Persist;
    019    import org.apache.tapestry5.internal.InternalComponentResources;
    020    import org.apache.tapestry5.ioc.Location;
    021
    022    /**
    023     * Mutable version of {@link org.apache.tapestry5.model.ComponentModel} used during the transformation phase.
    024     */
    025    public 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    }