KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > inversoft > config > 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 JavaDoc;
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 JavaDoc 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 JavaDoc otherRegistries);
154 }
155
Popular Tags