View Javadoc

1   /*
2    * $Id: DefinitionsFactory.java 822631 2009-10-07 09:21:12Z apetrelli $
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   * http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  package org.apache.tiles.definition;
23  
24  import org.apache.tiles.context.TilesRequestContext;
25  import org.apache.tiles.Definition;
26  
27  import java.util.Map;
28  
29  /***
30   * Interface for creating a {@link Definition}s and managing their contents.
31   * <p/>
32   * <p>
33   * DefinitionsFactory implementations are responsible for maintaining the data
34   * sources of Tiles configuration data and using the data to create Definitions
35   * sets. Implementations also know how to append locale-specific configuration
36   * data to an existing Definitions set.
37   * </p>
38   *
39   * @version $Rev: 822631 $ $Date: 2009-10-07 11:21:12 +0200 (mer, 07 ott 2009) $
40   */
41  public interface DefinitionsFactory {
42  
43      /***
44       * Property name that specifies the implementation of the DefinitionsReader.
45       */
46      String READER_IMPL_PROPERTY =
47          "org.apache.tiles.definition.DefinitionsReader";
48  
49      /***
50       * Property name that specifies the implementation of
51       * {@link org.apache.tiles.locale.LocaleResolver}.
52       */
53      String LOCALE_RESOLVER_IMPL_PROPERTY =
54          "org.apache.tiles.locale.LocaleResolver";
55  
56      /***
57       * Constant representing the configuration parameter
58       * used to define the tiles definition resources.
59       *
60       * @since 2.1.0
61       */
62      String DEFINITIONS_CONFIG = "org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG";
63  
64      /***
65       * Constant representing the configuration parameter used to define the
66       * definition DAO to use.
67       */
68      String DEFINITION_DAO_INIT_PARAM =
69          "org.apache.tiles.definition.DefinitionsFactory.DefinitionDAO";
70  
71  
72      /***
73       * Initializes the DefinitionsFactory and its subcomponents. <p/>
74       * Implementations may support configuration properties to be passed in via
75       * the params Map.
76       *
77       * @param params The Map of configuration properties.
78       * @throws DefinitionsFactoryException If a Tiles exception, such as an initialization
79       * error, occurs.
80       * @deprecated Parameter based initialization is deprecated, please compose your
81       * definitions factory using methods.
82       */
83      void init(Map<String, String> params);
84  
85      /***
86       * Returns a Definition object that matches the given name and
87       * Tiles context.
88       *
89       * @param name         The name of the Definition to return.
90       * @param tilesContext The Tiles context to use to resolve the definition.
91       * @return the Definition matching the given name or null if none
92       *         is found.
93       */
94      Definition getDefinition(String name, TilesRequestContext tilesContext);
95  
96      /***
97       * Adds a source where Definition objects are stored.
98       * <p/>
99       * Implementations should publish what type of source object they expect.
100      * The source should contain enough information to resolve a configuration
101      * source containing definitions.  The source should be a "base" source for
102      * configurations.  Internationalization and Localization properties will be
103      * applied by implementations to discriminate the correct data sources based
104      * on locale.
105      *
106      * @param source The configuration source for definitions.
107      * @deprecated Let the Definitions Factory load its sources by itself.
108      */
109     @Deprecated
110     void addSource(Object source);
111 
112     /***
113      * Creates and returns a {@link Definitions} set by reading
114      * configuration data from the applied sources.
115      *
116      * @return The read definitions.
117      * @deprecated Let the Definitions Factory use it.
118      */
119     @Deprecated
120     Definitions readDefinitions();
121 }