Modified: tiles/framework/trunk/tiles-core/src/main/java/org/apache/tiles/factory/TilesContainerFactory.java URL: http://svn.apache.org/viewvc/tiles/framework/trunk/tiles-core/src/main/java/org/apache/tiles/factory/TilesContainerFactory.java?view=diff&rev=519037&r1=519036&r2=519037 ============================================================================== --- tiles/framework/trunk/tiles-core/src/main/java/org/apache/tiles/factory/TilesContainerFactory.java (original) +++ tiles/framework/trunk/tiles-core/src/main/java/org/apache/tiles/factory/TilesContainerFactory.java Fri Mar 16 09:17:54 2007 @@ -50,22 +50,43 @@ */ public class TilesContainerFactory { + /** + * Initialization parameter that represents the container factory class + * name. + */ public static final String CONTAINER_FACTORY_INIT_PARAM = "org.apache.tiles.CONTAINER_FACTORY"; + /** + * Initialization parameter that indicates if the container factory is + * mutable. + */ public static final String CONTAINER_FACTORY_MUTABLE_INIT_PARAM = "org.apache.tiles.CONTAINER_FACTORY.mutable"; + /** + * Initialization parameter that represents the context factory class name. + */ public static final String CONTEXT_FACTORY_INIT_PARAM = "org.apache.tiles.CONTEXT_FACTORY"; + /** + * Initialization parameter that represents the definitions factory class + * name. + */ public static final String DEFINITIONS_FACTORY_INIT_PARAM = "org.apache.tiles.DEFINITIONS_FACTORY"; + /** + * Initialization parameter that represents the preparer factory class name. + */ public static final String PREPARER_FACTORY_INIT_PARAM = "org.apache.tiles.PREPARER_FACTORY"; + /** + * Default configuration parameters. + */ private static final Map<String, String> DEFAULTS = new HashMap<String, String>(); @@ -76,6 +97,9 @@ DEFAULTS.put(PREPARER_FACTORY_INIT_PARAM, BasicPreparerFactory.class.getName()); } + /** + * The default configuration to be used by the factory. + */ protected Map<String, String> defaultConfiguration = new HashMap<String, String>(DEFAULTS); @@ -100,17 +124,16 @@ } /** - * Retrieve a factory instance as configured through the - * specified context. - * <p/> - * The context will be queried and if a init parameter - * named 'org.apache.tiles.CONTAINER_FACTORY' is discovered - * this class will be instantiated and returned. Otherwise, - * the factory will attempt to utilize one of it's internal - * factories. - * - * @param context the executing applications context. - * Typically a ServletContext or PortletContext + * Retrieve a factory instance as configured through the specified context. + * <p/> The context will be queried and if a init parameter named + * 'org.apache.tiles.CONTAINER_FACTORY' is discovered this class will be + * instantiated and returned. Otherwise, the factory will attempt to utilize + * one of it's internal factories. + * + * @param context the executing applications context. Typically a + * ServletContext or PortletContext + * @param defaults Default configuration parameters values, used if the + * context object has not the corresponding parameters. * @return a tiles container * @throws TilesException if an error occurs creating the factory. */ @@ -126,6 +149,13 @@ return factory; } + /** + * Creates a Tiles container. + * + * @param context The (application) context object. + * @return The created container. + * @throws TilesException If something goes wrong during instantiation. + */ public TilesContainer createContainer(Object context) throws TilesException { String value = getInitParameter(context, CONTAINER_FACTORY_MUTABLE_INIT_PARAM); if (Boolean.parseBoolean(value)) { @@ -135,16 +165,34 @@ } } + /** + * Sets the default configuration parameters. + * + * @param defaultConfiguration The default configuration parameters. + */ public void setDefaultConfiguration(Map<String, String> defaultConfiguration) { if (defaultConfiguration != null) { this.defaultConfiguration.putAll(defaultConfiguration); } } + /** + * Sets one default configuration parameter value. + * + * @param key The key of the configuration parameter. + * @param value The value of the configuration parameter. + */ public void setDefaultValue(String key, String value) { this.defaultConfiguration.put(key, value); } + /** + * Creates an immutable Tiles container. + * + * @param context The (application) context object. + * @return The created Tiles container. + * @throws TilesException If something goes wrong during initialization. + */ public TilesContainer createTilesContainer(Object context) throws TilesException { BasicTilesContainer container = new BasicTilesContainer(); @@ -152,6 +200,13 @@ return container; } + /** + * Creates a mutable Tiles container. + * + * @param context The (application) context object. + * @return The created Tiles container. + * @throws TilesException If something goes wrong during initialization. + */ public MutableTilesContainer createMutableTilesContainer(Object context) throws TilesException { CachingTilesContainer container = new CachingTilesContainer(); @@ -159,6 +214,13 @@ return container; } + /** + * Initializes a container. + * + * @param context The (application) context object to use. + * @param container The container to be initialized. + * @throws TilesException If something goes wrong during initialization. + */ protected void initializeContainer(Object context, BasicTilesContainer container) throws TilesException { @@ -171,6 +233,17 @@ container.init(initParameterMap); } + /** + * Stores container dependencies, that is called before + * [EMAIL PROTECTED] TilesContainer#init(Map)} + * + * @param context The (application) context object to use. + * @param initParameters The initialization parameters. + * @param configuration The merged configuration parameters (both defaults + * and context ones). + * @param container The container to use. + * @throws TilesException If something goes wrong during initialization. + */ protected void storeContainerDependencies(Object context, Map<String, String> initParameters, Map<String, String> configuration, @@ -198,12 +271,31 @@ } + /** + * Creates a factory instance. + * + * @param configuration The merged configuration parameters (both defaults + * and context ones). + * @param initParameterName The initialization parameter name from which the + * class name is got. + * @return The created factory. + * @throws TilesException If something goes wrong during creation. + */ protected static Object createFactory(Map<String, String> configuration, String initParameterName) throws TilesException { String factoryName = resolveFactoryName(configuration, initParameterName); return ClassUtil.instantiate(factoryName); } + /** + * Resolves a factory class name. + * + * @param configuration The merged configuration parameters (both defaults + * and context ones). + * @param parameterName The name of the initialization parameter to use. + * @return The factory class name. + * @throws TilesException If something goes wrong during resolution. + */ protected static String resolveFactoryName(Map<String, String> configuration, String parameterName) throws TilesException { Object factoryName = configuration.get(parameterName); @@ -212,6 +304,14 @@ : factoryName.toString(); } + /** + * Returns the value of an initialization parameter. + * + * @param context The (application) context object to use. + * @param parameterName The parameter name to retrieve. + * @return The parameter value. + * @throws TilesException If the context has not been recognized. + */ protected static String getInitParameter(Object context, String parameterName) throws TilesException { Object value; @@ -227,6 +327,13 @@ return value == null ? null : value.toString(); } + /** + * Returns a map containing parameters name-value entries. + * + * @param context The (application) context object to use. + * @return The initialization parameters map. + * @throws TilesException If the context object has not been recognized. + */ @SuppressWarnings("unchecked") protected static Map<String, String> getInitParameterMap(Object context) throws TilesException {
Modified: tiles/framework/trunk/tiles-core/src/main/java/org/apache/tiles/impl/BasicTilesContainer.java URL: http://svn.apache.org/viewvc/tiles/framework/trunk/tiles-core/src/main/java/org/apache/tiles/impl/BasicTilesContainer.java?view=diff&rev=519037&r1=519036&r2=519037 ============================================================================== --- tiles/framework/trunk/tiles-core/src/main/java/org/apache/tiles/impl/BasicTilesContainer.java (original) +++ tiles/framework/trunk/tiles-core/src/main/java/org/apache/tiles/impl/BasicTilesContainer.java Fri Mar 16 09:17:54 2007 @@ -79,12 +79,29 @@ private static final Log LOG = LogFactory.getLog(BasicTilesContainer.class); + /** + * The Tiles application context object. + */ private TilesApplicationContext context; + + /** + * The definitions factory. + */ private DefinitionsFactory definitionsFactory; + + /** + * The preparer factory. + */ private PreparerFactory preparerFactory; + /** + * The Tiles context factory. + */ private TilesContextFactory contextFactory; + /** + * Initialization flag. If set, this container cannot be changed. + */ private boolean initialized = false; /** @@ -106,22 +123,35 @@ initParameters); } + /** [EMAIL PROTECTED] */ public ComponentContext startContext(Object... requestItems) { TilesRequestContext tilesContext = getRequestContext(requestItems); return startContext(tilesContext); } + /** [EMAIL PROTECTED] */ public void endContext(Object... requestItems) { TilesRequestContext tilesContext = getRequestContext(requestItems); endContext(tilesContext); } + /** + * Starts a component context inside the container. + * + * @param tilesContext The request context to use. + * @return The newly created component context. + */ private ComponentContext startContext(TilesRequestContext tilesContext) { ComponentContext context = new BasicComponentContext(); BasicComponentContext.pushContext(context, tilesContext); return context; } + /** + * Releases and removes a previously created component context. + * + * @param tilesContext The request context to use. + */ private void endContext(TilesRequestContext tilesContext) { BasicComponentContext.popContext(tilesContext); } @@ -185,16 +215,28 @@ return context; } + /** + * Sets the Tiles application context to use. + * + * @param context The Tiles application context. + */ public void setApplicationContext(TilesApplicationContext context) { this.context = context; } + /** [EMAIL PROTECTED] */ public ComponentContext getComponentContext(Object... requestItems) { TilesRequestContext tilesContext = getRequestContext(requestItems); return getComponentContext(tilesContext); } + /** + * Returns the current component context. + * + * @param tilesContext The request context to use. + * @return The current component context. + */ private ComponentContext getComponentContext(TilesRequestContext tilesContext) { ComponentContext context = BasicComponentContext.getContext(tilesContext); if (context == null) { @@ -204,6 +246,12 @@ return context; } + /** + * Creates a Tiles request context from request items. + * + * @param requestItems The request items. + * @return The created Tiles request context. + */ private TilesRequestContext getRequestContext(Object... requestItems) { return getContextFactory().createRequestContext( getApplicationContext(), @@ -211,19 +259,29 @@ ); } + /** + * Returns the context factory. + * + * @return The context factory. + */ public TilesContextFactory getContextFactory() { return contextFactory; } + /** + * Sets the context factory. + * + * @param contextFactory The context factory. + */ public void setContextFactory(TilesContextFactory contextFactory) { checkInit(); this.contextFactory = contextFactory; } /** - * Standard Getter + * Returns the definitions factory. * - * @return the definitions factory used by this container. + * @return The definitions factory used by this container. */ public DefinitionsFactory getDefinitionsFactory() { return definitionsFactory; @@ -259,6 +317,7 @@ this.preparerFactory = preparerFactory; } + /** [EMAIL PROTECTED] */ public void prepare(String preparer, Object... requestItems) throws TilesException { TilesRequestContext requestContext = getContextFactory().createRequestContext( @@ -268,6 +327,17 @@ prepare(requestContext, preparer, false); } + /** + * Execute a preparer. + * + * @param context The request context. + * @param preparerName The name of the preparer. + * @param ignoreMissing If <code>true</code> if the preparer is not found, + * it ignores the problem. + * @throws TilesException If the preparer is not found (and + * <code>ignoreMissing</code> is not set) or if the preparer itself threw an + * exception. + */ private void prepare(TilesRequestContext context, String preparerName, boolean ignoreMissing) throws TilesException { @@ -294,12 +364,7 @@ } } - /** - * Render the specified definition. - * @param requestItems the TilesRequestContext - * - * @throws TilesException - */ + /** [EMAIL PROTECTED] */ public void render(String definitionName, Object... requestItems) throws TilesException { TilesRequestContext requestContext = getContextFactory().createRequestContext( @@ -309,6 +374,13 @@ render(requestContext, definitionName); } + /** + * Renders the specified definition. + * + * @param request The request context. + * @param definitionName The name of the definition to render. + * @throws TilesException If something goes wrong during rendering. + */ private void render(TilesRequestContext request, String definitionName) throws TilesException { @@ -362,6 +434,7 @@ } } + /** [EMAIL PROTECTED] */ public void render(ComponentAttribute attr, Writer writer, Object... requestItems) throws TilesException, IOException { ComponentContext context = getComponentContext(requestItems); @@ -388,11 +461,26 @@ } } + /** + * Checks if an attribute contains a definition. + * + * @param attr The attribute to check. + * @param requestItems The request items. + * @return <code>true</code> if the attribute is a definition. + */ private boolean isDefinition(ComponentAttribute attr, Object... requestItems) { return ComponentAttribute.DEFINITION.equals(attr.getType()) || isValidDefinition(attr.getValue().toString(), requestItems); } + /** + * Calculates the type of an attribute. + * + * @param attr The attribute to check. + * @param requestItems The request items. + * @return The calculated attribute type. + * @throws TilesException If the type is not recognized. + */ private String calculateType(ComponentAttribute attr, Object... requestItems) throws TilesException { String type = attr.getType(); @@ -416,12 +504,29 @@ return type; } + /** + * Returns a definition specifying its name. + * + * @param definitionName The name of the definition to find. + * @param request The request context. + * @return The definition, if found. + * @throws DefinitionsFactoryException If the definitions factory throws an + * exception. + */ protected ComponentDefinition getDefinition(String definitionName, TilesRequestContext request) throws DefinitionsFactoryException { ComponentDefinition definition = definitionsFactory.getDefinition(definitionName, request); return definition; } + /** + * Checks if the current user is in one of the comma-separated roles + * specified in the <code>role</code> parameter. + * + * @param request The request context. + * @param role The comma-separated list of roles. + * @return <code>true</code> if the current user is in one of those roles. + */ private boolean isPermitted(TilesRequestContext request, String role) { if (role == null) { return true; @@ -484,10 +589,19 @@ return filenames; } + /** [EMAIL PROTECTED] */ public boolean isValidDefinition(String definitionName, Object... requestItems) { return isValidDefinition(getRequestContext(requestItems), definitionName); } + /** + * Checks if a string is a valid definition name. + * + * @param context The request context. + * @param definitionName The name of the definition to find. + * @return <code>true</code> if <code>definitionName</code> is a valid + * definition name. + */ private boolean isValidDefinition(TilesRequestContext context, String definitionName) { try { ComponentDefinition definition = getDefinition(definitionName, context);
