001: // Copyright 2006, 2007 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.tapestry.model;
016:
017: import java.util.List;
018:
019: import org.apache.commons.logging.Log;
020: import org.apache.tapestry.annotations.MixinAfter;
021: import org.apache.tapestry.annotations.Persist;
022: import org.apache.tapestry.annotations.SupportsInformalParameters;
023: import org.apache.tapestry.ioc.Resource;
024:
025: /**
026: * Defines a component in terms of its capabilities, parameters, sub-components, etc. During
027: * <em>runtime</em>, the component model is immutable. During <em>construction</em> time, when
028: * the class is being transformed and loaded, the model is mutable.
029: *
030: * @see MutableComponentModel
031: */
032: public interface ComponentModel {
033: /**
034: * Returns the resource corresponding to the class file for this component. This is used to find
035: * related resources, such as the component's template and message catalog.
036: */
037: Resource getBaseResource();
038:
039: /** The FQCN of the component. */
040: String getComponentClassName();
041:
042: /**
043: * Returns the ids of all embedded components defined within the component class (via the
044: * {@link org.apache.tapestry.annotations.Component} annotation).
045: */
046: List<String> getEmbeddedComponentIds();
047:
048: /**
049: * Returns an embedded component.
050: *
051: * @param componentId
052: * the id of the embedded component
053: * @return the embedded component model, or null if no component exists with that id
054: */
055: EmbeddedComponentModel getEmbeddedComponentModel(String componentId);
056:
057: /**
058: * Returns the persistent strategy associated with the field.
059: *
060: * @param fieldName
061: * @return the corresponding strategy, or the empty string
062: * @throw IllegalArgumentException if the named field is not marked as persistent
063: */
064: String getFieldPersistenceStrategy(String fieldName);
065:
066: /** Returns object that will be used to log warnings and errors related to this component. */
067: Log getLog();
068:
069: /** Returns a list of the class names of mixins that are part of the component's implementation. */
070: List<String> getMixinClassNames();
071:
072: /**
073: * Return a single parameter model by parameter name, or null if the parameter is not defined.
074: *
075: * @param parameterName
076: * the name of the parameter (case is ignored)
077: */
078: ParameterModel getParameterModel(String parameterName);
079:
080: /**
081: * Returns an alphabetically sorted list of the names of all formal parameters. This includes
082: * parameters defined by a base class.
083: */
084:
085: List<String> getParameterNames();
086:
087: /**
088: * Returns an alphabetically sorted list of the names of all formal parameters defined by this
089: * specific class (parameters inherited from base classes are not identified).
090: */
091: List<String> getDeclaredParameterNames();
092:
093: /**
094: * Returns a list of the names of all persistent fields (within this class, or any super-class).
095: * The names are sorted alphabetically.
096: *
097: * @see Persist
098: */
099: List<String> getPersistentFieldNames();
100:
101: /**
102: * Returns true if the modeled component is a root class, a component class whose parent does
103: * not have the {@link ComponentClass} annotation. This is often used to determine whether to
104: * invoke the super-class implementation of certain methods.
105: *
106: * @return true if a root class, false if a subclass
107: */
108: boolean isRootClass();
109:
110: /**
111: * Returns true if the model indicates that informal parameters, additional parameters beyond
112: * the formal parameter defined for the component, are supported. This is false in most cases,
113: * but may be set to true for specific classes (when the {@link SupportsInformalParameters}
114: * annotation is present, or inherited from a super-class).
115: *
116: * @return true if this component model supports informal parameters
117: */
118: boolean getSupportsInformalParameters();
119:
120: /**
121: * Returns the component model for this component's super-class, if it exists. Remember that
122: * only classes with the {@link ComponentClass} annotation, and in the correct packages, are
123: * considered component classes.
124: *
125: * @return the parent class model, or null if this component's super class is not itself a
126: * component class
127: */
128: ComponentModel getParentModel();
129:
130: /**
131: * Relevant for component mixins only. Indicates that the mixin behavior should occur
132: * <em>after</em> (not before) the component. Normally, this flag is set by the presence of
133: * the {@link MixinAfter} annotation.
134: *
135: * @return true if the mixin should operate after, not before, the component
136: */
137: boolean isMixinAfter();
138:
139: /**
140: * Gets a meta value identified by the given key. If the current model does not provide a value
141: * for the key, then the parent component model (if any) is searched.
142: *
143: * @param key
144: * identifies the value to be accessed
145: * @return the value for the key (possibly inherited from a parent model), or null
146: */
147: String getMeta(String key);
148: }
|