View Javadoc

1   /*
2    * $Id: Definitions.java 537196 2007-05-11 14:07:35Z 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 java.util.Locale;
25  import java.util.Map;
26  
27  import org.apache.tiles.Definition;
28  
29  /***
30   * Interface for managing collections of {@link Definition} objects.
31   * <p/>
32   * <p>The Definitions interface provides a pattern for managing
33   * Definition objects.  Implementations will provide a means to append
34   * new Definitions to the collection, add and retrieve lcale-specific
35   * Definitions objects, and reset the collections.</p>
36   *
37   * @version $Rev: 537196 $ $Date: 2007-05-11 16:07:35 +0200 (Fri, 11 May 2007) $
38   */
39  public interface Definitions {
40  
41      /***
42       * Returns a Definition object that matches the given name.
43       *
44       * @param name The name of the Definition to return.
45       * @return the Definition matching the given name or null if none
46       *         is found.
47       */
48      Definition getDefinition(String name);
49  
50      /***
51       * Adds new Definition objects to the internal collection and
52       * resolves inheritance attraibutes.
53       *
54       * @param defsMap The new definitions to add.
55       * @throws NoSuchDefinitionException if a Definition extends from
56       *                                   one that doesn't exist.
57       */
58      void addDefinitions(Map<String, Definition> defsMap) throws NoSuchDefinitionException;
59  
60      /***
61       * Adds new locale-specific Definition objects to the internal
62       * collection and resolves inheritance attraibutes.
63       *
64       * @param defsMap The new definitions to add.
65       * @param locale  The locale to add the definitions to.
66       * @throws NoSuchDefinitionException if a Definition extends from
67       *                                   one that doesn't exist.
68       */
69      void addDefinitions(Map<String, Definition> defsMap, Locale locale)
70              throws NoSuchDefinitionException;
71  
72      /***
73       * Returns a Definition object that matches the given name and locale.
74       *
75       * @param name   The name of the Definition to return.
76       * @param locale The locale to use to resolve the definition.
77       * @return the Definition matching the given name or null if none
78       *         is found.
79       */
80      Definition getDefinition(String name, Locale locale);
81  
82      /***
83       * Resolves configuration inheritance properties.
84       *
85       * @throws NoSuchDefinitionException If parent definitions are not found.
86       */
87      void resolveInheritances() throws NoSuchDefinitionException;
88  
89      /***
90       * Resolves locale-specific configuration inheritance properties.
91       *
92       * @param locale The locale object to use.
93       * @throws NoSuchDefinitionException If parent definitions are not found.
94       */
95      void resolveInheritances(Locale locale) throws NoSuchDefinitionException;
96  
97      /***
98       * Clears definitions.
99       */
100     void reset();
101 
102     /***
103      * Returns base definitions collection.
104      *
105      * @return A map of the type "definition name -> definition".
106      */
107     Map<String, Definition> getBaseDefinitions();
108 }