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}