ConfigBuilder


1   /*
2    * Copyright (c) 2003, Inversoft
3    *
4    * This software is distribuable under the GNU Lesser General Public License.
5    * For more information visit gnu.org.
6    */
7   package com.inversoft.config;
8   
9   
10  import java.util.Map  ;
11  
12  import org.jdom.Document;
13  
14  
15  /**
16   * <p>
17   * This interface is used to parse and build configuration
18   * objects from XML based configuration files or sources.
19   * </p>
20   *
21   * <p>
22   * Implementations of this interface are used by the {@link
23   * ConfigMediator ConfigMediator} to parse and build
24   * individual configuration files or sources via the {@link
25   * #build(org.jdom.Document, ConfigRegistry) build} method.
26   * </p>
27   *
28   * <p>
29   * The ConfigMediator also uses implementations of this
30   * interface to do a second pass validation. Second pass
31   * validation is used to verify the entire configuration for
32   * a sub-system, which could span mutilple files, is valid.
33   * This also provides the opportunity for configuration that
34   * has cross cutting concerns, that is relies on
35   * configuration from other sub-systems, to be validated.
36   * </p>
37   *
38   * @author  Brian Pontarelli
39   * @since   2.0
40   * @version 2.0
41   */
42  public interface ConfigBuilder {
43  
44      /**
45       * <p>
46       * Parses and builds the configuration from the given JDOM Document. The
47       * implementation classes can handle parsing and configuration however they
48       * see fit. The ConfigRegistry provided, may be null depending on whether or
49       * not the associated {@link ConfigFactory ConfigFactory} builds registry's
50       * or not. This registry can be used to store the configuration objects
51       * created or whatever else the implementations wish
52       * </p>
53       *
54       * @param   document The JDOM Document to parse and build the configuration
55       *          from
56       * @param   registry (Optional) The ConfigRegistry, which may be null, and
57       *          which is retrieved either manually, if this class is being used
58       *          outside the configuration system, or from the ConfigFactory
59       *          if this class is being used within the Inversoft configuration
60       *          system
61       * @throws  ConfigurationException If there were any problems during parsing
62       *          and/or building. Any exceptions thrown should contain all the
63       *          errors encountered rather than the first error. These errors
64       *          should be stored in the ErrorList within the exception
65       */
66      void build(Document document, ConfigRegistry registry)
67      throws ConfigurationException;
68  
69      /**
70       * <p>
71       * Parses and rebuilds the configuration from the given JDOM Document. The
72       * implementation classes can handle the process of rebuilding however they
73       * see fit, but should be aware that duplication errors may no longer be 
74       * valid. Likewise, since the same Registry instance may be passed in, this
75       * method may not be thread safe. Implementations must consider how they 
76       * implement this method, the validate method, the {@link ConfigFactory 
77       * ConfigFactory} and {@link ConfigRegistry ConfigRegistry} implementations 
78       * in order or ignore thread safety. 
79       * </p>
80       *
81       * @param   document The JDOM Document to parse and build the configuration
82       *          from
83       * @param   registry (Optional) The ConfigRegistry, which may be null, and
84       *          which is retrieved either manually, if this class is being used
85       *          outside the configuration system, or from the ConfigFactory
86       *          if this class is being used within the Inversoft configuration
87       *          system
88       * @throws  ConfigurationException If there were any problems during parsing
89       *          and/or building. Any exceptions thrown should contain all the
90       *          errors encountered rather than the first error. These errors
91       *          should be stored in the ErrorList within the exception
92       */
93      void rebuild(Document document, ConfigRegistry registry)
94      throws ConfigurationException;
95  
96      /**
97       * <p>
98       * Validates the configuration after all the configuration for all sub-systems
99       * has been parsed and built. This is called by the ConfigMediator after all
100      * sub-systems and all configuration files and/or sources have been read.
101      * </p>
102      *
103      * <p>
104      * The Map given is a Map of all the ConfigRegistry objects that were used by
105      * the sub-systems. The key of the ConfigRegistry's in the Map is the name of
106      * the sub-system, which is also the root element of the configuration file
107      * for that sub-system, which is also the name the ConfigFactory is registered
108      * under with the ConfigFactoryRegistry.
109      * </p>
110      *
111      * <p>
112      * Since a single Factory (and likewise builder) can be used for multiple
113      * document types, this method will be called multiple times for a builder
114      * used for multiple document types. The ConfigRegistry passed in could also
115      * be the same, depending on the Factory implementation. It is up to the
116      * implementation of this interface to handle these cases gracefully.
117      * </p>
118      *
119      * @param   registry The ConfigRegistry of sub-system currently being parsed
120      *          and built. This may be null if the current sub-system's
121      *          ConfigFactory returned null from the createRegistry method.
122      * @param   otherRegistries The Map of the registries for all the sub-systems,
123      *          excluding the current sub-system
124      * @throws  ConfigurationException If there were any configuration errors.
125      *          This exception should contain all the errors rather than the
126      *          first error. These errors should be stored in the ErrorList
127      *          withing the exception
128      */
129     void validate(ConfigRegistry registry, Map   otherRegistries)
130     throws ConfigurationException;
131 
132     /**
133      * <p>
134      * Allows the building the chance to store the registry or do any other post
135      * build processing. This method is called only after a successful build and
136      * validate of this builder. If other builders fails, that has no bearing on
137      * this builder.
138      * </p>
139      *
140      * <p>
141      * Usually, this gives the builder the chance to store the new registry for
142      * the application to access. This method should be written in such a manner
143      * as that it will not fail. Failures should only occur in build, rebuild and
144      * validate.
145      * </p>
146      *
147      * @param   registry The ConfigRegistry of sub-system currently being parsed
148      *          and built. This may be null if the current sub-system's
149      *          ConfigFactory returned null from the createRegistry method.
150      * @param   otherRegistries The Map of the registries for all the sub-systems,
151      *          excluding the current sub-system
152      */
153     void commit(ConfigRegistry registry, Map   otherRegistries);
154 }
155
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags