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 }