001 // Copyright 2006, 2007, 2008, 2009 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 */
038 void addParameter(String name, boolean required, boolean allowNull, String defaultBindingPrefix);
039
040 /**
041 * Defines a new embedded component.
042 *
043 * @param id the unique id for the embedded component, which must not already exist.
044 * @param type the type of the component (posslibly blank)
045 * @param componentClassName the fully qualified class name (derived from the field), used if the type is
046 * blank
047 * @param inheritInformalParameters if true, then the component will inherit informal parameters provided to its
048 * container
049 * @param location where the component is defined @return a mutable model allowing parameters to be
050 * set
051 */
052 MutableEmbeddedComponentModel addEmbeddedComponent(String id, String type, String componentClassName,
053 boolean inheritInformalParameters, Location location);
054
055 /**
056 * Used to define the field persistence strategy for a particular field name. Returns a logical name for the field,
057 * which is guaranteed to be unique (this is necessary for handling the case where a subclass has a persistent field
058 * with the same name as a persistent field from a super-class).
059 *
060 * @param fieldName the name of the field which is to be made persistent
061 * @param strategy the strategy for persisting the field, from {@link Persist#value()}. This value may be blank, in
062 * which case the stategy is inherited from the component, or the component's container.
063 * @return a logical name for the field, to be used with {@link ComponentModel#getFieldPersistenceStrategy(String)},
064 * and with {@link InternalComponentResources#persistFieldChange(String, Object)}, etc.
065 */
066 String setFieldPersistenceStrategy(String fieldName, String strategy);
067
068 /**
069 * Adds a mixin to the component's implementation.
070 */
071 void addMixinClassName(String mixinClassName);
072
073 /**
074 * Sets the internal flag to indicate that this model (and all models that extend from it) support informal
075 * parameters.
076 */
077 void enableSupportsInformalParameters();
078
079 /**
080 * Changes the value of the mixinAfter flag. The default value is false.
081 */
082 void setMixinAfter(boolean mixinAfter);
083
084 /**
085 * Stores a meta data value under the indicated key.
086 */
087 void setMeta(String key, String value);
088
089 /**
090 * Identifies that the component does handle the render phase.
091 *
092 * @param renderPhase annotation class corresponding to the render phase
093 * @see ComponentModel#getHandledRenderPhases()
094 * @since 5.0.19, 5.1.0.0
095 */
096 void addRenderPhase(Class renderPhase);
097
098 /**
099 * Identifies that the component includes an event handler for the indicated event type.
100 *
101 * @param eventType of handled event
102 * @since 5.1.0.0
103 */
104 void addEventHandler(String eventType);
105 }