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}