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    }