001// Copyright 2006, 2007, 2008, 2009, 2010, 2011, 2012 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.MixinAfter; 018import org.apache.tapestry5.annotations.Persist; 019import org.apache.tapestry5.annotations.SupportsInformalParameters; 020import org.apache.tapestry5.ioc.Resource; 021import org.slf4j.Logger; 022 023import java.util.List; 024import java.util.Set; 025 026/** 027 * Defines a component in terms of its capabilities, parameters, sub-components, etc. During <em>runtime</em>, the 028 * component model is immutable. During <em>construction</em> time, when the class is being transformed and loaded, the 029 * model is mutable. 030 * 031 * @see org.apache.tapestry5.model.MutableComponentModel 032 */ 033public interface ComponentModel 034{ 035 /** 036 * Returns the name of the library that defines this component; this may be the empty string for 037 * an application page or component, or will be a name of a library (possibly including "core" for built-in 038 * components). 039 * Library names are defined by the {@link org.apache.tapestry5.services.LibraryMapping} contributions 040 * to the {@link org.apache.tapestry5.services.ComponentClassResolver} service. 041 * 042 * @return library name containing the component, or empty string for application components 043 * @since 5.4 044 */ 045 String getLibraryName(); 046 047 /** 048 * Is this a model of a page (rather than a component, mixin, or base-class)? 049 * 050 * @return true if a page 051 * @since 5.3 052 */ 053 boolean isPage(); 054 055 /** 056 * Returns the resource corresponding to the class file for this component. This is used to find related resources, 057 * such as the component's template and message catalog. 058 */ 059 Resource getBaseResource(); 060 061 /** 062 * The fully qualified class name of the component. 063 */ 064 String getComponentClassName(); 065 066 /** 067 * Returns the ids of all embedded components defined within the component class (via the {@link 068 * org.apache.tapestry5.annotations.Component} annotation), including those defined by any super-class. 069 */ 070 List<String> getEmbeddedComponentIds(); 071 072 /** 073 * Returns an embedded component defined by this component or by a super-class. 074 * 075 * @param componentId 076 * the id of the embedded component 077 * @return the embedded component model, or null if no component exists with that id 078 */ 079 EmbeddedComponentModel getEmbeddedComponentModel(String componentId); 080 081 /** 082 * Returns the persistent strategy associated with the field. 083 * 084 * @param fieldName 085 * @return the corresponding strategy, or the empty string 086 * @throws IllegalArgumentException 087 * if the named field is not marked as persistent 088 */ 089 String getFieldPersistenceStrategy(String fieldName); 090 091 /** 092 * Returns object that will be used to log warnings and errors related to this component. 093 * 094 * @see org.apache.tapestry5.annotations.Log 095 */ 096 Logger getLogger(); 097 098 /** 099 * Returns a list of the class names of mixins that are part of the component's implementation. 100 */ 101 List<String> getMixinClassNames(); 102 103 /** 104 * Return a single parameter model by parameter name, or null if the parameter is not defined (is not 105 * a formal parameter). This may be a parameter defined by this component, or from a base class. 106 * 107 * @param parameterName 108 * the name of the parameter (case is ignored) 109 * @return the parameter model if found in this model or a parent model, or null if not found 110 */ 111 ParameterModel getParameterModel(String parameterName); 112 113 /** 114 * Returns true if the named parameter is formally defined (there's a ParameterModel). 115 * 116 * @param parameterName 117 * name of the parameter (case is ignored) 118 * @since 5.2.0 119 */ 120 boolean isFormalParameter(String parameterName); 121 122 /** 123 * Returns an alphabetically sorted list of the names of all formal parameters. This includes parameters defined by 124 * a base class. 125 */ 126 127 List<String> getParameterNames(); 128 129 /** 130 * Returns an alphabetically sorted list of the names of all formal parameters defined by this specific class 131 * (parameters inherited from base classes are not identified). 132 */ 133 List<String> getDeclaredParameterNames(); 134 135 /** 136 * Returns a list of the names of all persistent fields (within this class, or any super-class). The names are 137 * sorted alphabetically. 138 * 139 * @see Persist 140 */ 141 List<String> getPersistentFieldNames(); 142 143 /** 144 * Returns true if the modeled component is a root class, a component class whose parent class is not a component 145 * class. We may in the future require that components only extend from Object. 146 * 147 * @return true if a root class, false if a subclass 148 */ 149 boolean isRootClass(); 150 151 /** 152 * Returns true if the model indicates that informal parameters, additional parameters beyond the formal parameter 153 * defined for the component, are supported. This is false in most cases, but may be set to true for specific 154 * classes (when the {@link SupportsInformalParameters} annotation is present, or inherited from a super-class). 155 * 156 * @return true if this component model supports informal parameters 157 */ 158 boolean getSupportsInformalParameters(); 159 160 /** 161 * Returns the component model for this component's super-class, if it exists. Remember that only classes in the 162 * correct packages, are considered component classes. 163 * 164 * @return the parent class model, or null if this component's super class is not itself a component class 165 */ 166 ComponentModel getParentModel(); 167 168 /** 169 * Relevant for component mixins only. Indicates that the mixin behavior should occur <em>after</em> (not before) 170 * the component. Normally, this flag is set by the presence of the {@link MixinAfter} annotation. 171 * 172 * @return true if the mixin should operate after, not before, the component 173 */ 174 boolean isMixinAfter(); 175 176 /** 177 * Gets a meta value identified by the given key. If the current model does not provide a value for the key, then 178 * the parent component model (if any) is searched. 179 * 180 * @param key 181 * identifies the value to be accessed 182 * @return the value for the key (possibly inherited from a parent model), or null 183 */ 184 String getMeta(String key); 185 186 /** 187 * Returns a set of all the render phases that this model (including parent models) that are handled. Render phases 188 * are represented by the corresponding annotation ({@link org.apache.tapestry5.annotations.BeginRender}, {@link 189 * org.apache.tapestry5.annotations.AfterRender}, etc.). 190 * 191 * @return set of classes 192 * @since 5.0.19, 5.1.0.0 193 */ 194 Set<Class> getHandledRenderPhases(); 195 196 /** 197 * Determines if the component has an event handler for the indicated event name (case insensitive). This includes 198 * handlers in the component class itself, or its super-classes, but does not include event handlers supplied by 199 * implementation or instance mixins. 200 * 201 * @param eventType 202 * name of event to check (case insensitive) 203 * @return true if event handler present 204 */ 205 boolean handlesEvent(String eventType); 206 207 /** 208 * @param mixinClassName 209 * class name of the mixin for which the ordering is desired 210 * @return the ordering constraint(s) for the mixin, potentially null. 211 * @since 5.2.0 212 */ 213 String[] getOrderForMixin(String mixinClassName); 214 215 /** 216 * Relevant for pages only, indicates that the component handle the {@link org.apache.tapestry5.EventConstants.ACTIVATE} 217 * events with a catch all rules 218 * 219 * @since 5.4 220 * @see {@link MutableComponentModel.doHandleActivationEventContext()} 221 * @return <code>true</code> in case the page implement a catch all rules for the activate event context, 222 * <code>false</code> otherwise 223 */ 224 boolean handleActivationEventContext(); 225}