KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > framework > configuration > DefaultConfigurationBuilder


1 /* ====================================================================
2  * The Apache Software License, Version 1.1
3  *
4  * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
5  * reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright
15  * notice, this list of conditions and the following disclaimer in
16  * the documentation and/or other materials provided with the
17  * distribution.
18  *
19  * 3. The end-user documentation included with the redistribution,
20  * if any, must include the following acknowledgment:
21  * "This product includes software developed by the
22  * Apache Software Foundation (http://www.apache.org/)."
23  * Alternately, this acknowledgment may appear in the software
24  * itself, if and wherever such third-party acknowledgments
25  * normally appear.
26  *
27  * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
28  * must not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact apache@apache.org.
31  *
32  * 5. Products derived from this software may not be called "Apache",
33  * nor may "Apache" appear in their name, without prior written
34  * permission of the Apache Software Foundation.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  * SUCH DAMAGE.
48  * ====================================================================
49  *
50  * This software consists of voluntary contributions made by many
51  * individuals on behalf of the Apache Software Foundation. For more
52  * information on the Apache Software Foundation, please see
53  * <http://www.apache.org/>.
54  */
55 package org.apache.avalon.framework.configuration;
56
57 import java.io.File JavaDoc;
58 import java.io.IOException JavaDoc;
59 import java.io.InputStream JavaDoc;
60 import javax.xml.parsers.SAXParser JavaDoc;
61 import javax.xml.parsers.SAXParserFactory JavaDoc;
62 import org.xml.sax.InputSource JavaDoc;
63 import org.xml.sax.SAXException JavaDoc;
64 import org.xml.sax.XMLReader JavaDoc;
65
66 /**
67  * A DefaultConfigurationBuilder builds <code>Configuration</code>s from XML,
68  * via a SAX2 compliant parser.
69  *
70  * <p>
71  * XML namespace support is optional, and disabled by default to preserve
72  * backwards-compatibility. To enable it, pass the {@link
73  * #DefaultConfigurationBuilder(boolean)} constructor the flag <code>true</code>, or pass
74  * a namespace-enabled <code>XMLReader</code> to the {@link
75  * #DefaultConfigurationBuilder(XMLReader)} constructor.
76  * </p>
77  * <p>
78  * The mapping from XML namespaces to {@link Configuration} namespaces is pretty
79  * straightforward, with one caveat: attribute namespaces are (deliberately) not
80  * supported. Enabling namespace processing has the following effects:</p>
81  * <ul>
82  * <li>Attributes starting with <code>xmlns:</code> are interpreted as
83  * declaring a prefix:namespaceURI mapping, and won't result in the creation of
84  * <code>xmlns</code>-prefixed attributes in the <code>Configuration</code>.
85  * </li>
86  * <li>
87  * Prefixed XML elements, like <tt>&lt;doc:title xmlns:doc="http://foo.com"&gt;,</tt>
88  * will result in a <code>Configuration</code> with <code>{@link
89  * Configuration#getName getName()}.equals("title")</code> and <code>{@link
90  * Configuration#getNamespace getNamespace()}.equals("http://foo.com")</code>.
91  * </li>
92  * </ul>
93  * <p>
94  * Whitespace handling. Since mixed content is not allowed in the
95  * configurations, whitespace is completely discarded in non-leaf nodes.
96  * For the leaf nodes the default behavior is to trim the space
97  * surrounding the value. This can be changed by specifying
98  * <code>xml:space</code> attribute with value of <code>preserve</code>
99  * in that case the whitespace is left intact.
100  * </p>
101  *
102  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
103  * @version CVS $Revision: 1.26 $ $Date: 2003/02/11 16:19:27 $
104  */
105 public class DefaultConfigurationBuilder
106 {
107     private SAXConfigurationHandler m_handler;
108     private XMLReader JavaDoc m_parser;
109
110     /**
111      * Create a Configuration Builder with a default XMLReader that ignores
112      * namespaces. In order to enable namespaces, use either the constructor
113      * that has a boolean or that allows you to pass in your own
114      * namespace-enabled XMLReader.
115      */
116     public DefaultConfigurationBuilder()
117     {
118         this( false );
119     }
120
121     /**
122      * Create a Configuration Builder, specifying a flag that determines
123      * namespace support.
124      *
125      * @param enableNamespaces If <code>true</code>, a namespace-aware
126      * <code>SAXParser</code> is used. If <code>false</code>, the default JAXP
127      * <code>SAXParser</code> (without namespace support) is used.
128      * @since 4.1
129      */
130     public DefaultConfigurationBuilder( final boolean enableNamespaces )
131     {
132         //yaya the bugs with some compilers and final variables ..
133 try
134         {
135             final SAXParserFactory JavaDoc saxParserFactory = SAXParserFactory.newInstance();
136
137             if( enableNamespaces )
138             {
139                 saxParserFactory.setNamespaceAware( true );
140             }
141
142             final SAXParser JavaDoc saxParser = saxParserFactory.newSAXParser();
143             this.setParser( saxParser.getXMLReader() );
144         }
145         catch( final Exception JavaDoc se )
146         {
147             throw new Error JavaDoc( "Unable to setup SAX parser" + se );
148         }
149     }
150
151     /**
152      * Create a Configuration Builder with your own XMLReader.
153      * @param parser an <code>XMLReader</code>
154      */
155     public DefaultConfigurationBuilder( XMLReader JavaDoc parser )
156     {
157         this.setParser( parser );
158     }
159
160     /**
161      * Internally sets up the XMLReader
162      */
163     private void setParser( XMLReader JavaDoc parser )
164     {
165         m_parser = parser;
166
167         m_handler = getHandler();
168
169         m_parser.setContentHandler( m_handler );
170         m_parser.setErrorHandler( m_handler );
171     }
172
173     /**
174      * Get a SAXConfigurationHandler for your configuration reading.
175      * @return a <code>SAXConfigurationHandler</code>
176      */
177     protected SAXConfigurationHandler getHandler()
178     {
179         try
180         {
181             if( m_parser.getFeature( "http://xml.org/sax/features/namespaces" ) )
182             {
183                 return new NamespacedSAXConfigurationHandler();
184             }
185         }
186         catch( Exception JavaDoc e )
187         {
188             // ignore error and fall through to the non-namespaced version
189 }
190
191         return new SAXConfigurationHandler();
192     }
193
194     /**
195      * Build a configuration object from a file using a filename.
196      * @param filename name of the file
197      * @return a <code>Configuration</code> object
198      * @throws SAXException if a parsing error occurs
199      * @throws IOException if an I/O error occurs
200      * @throws ConfigurationException if an error occurs
201      */
202     public Configuration buildFromFile( final String JavaDoc filename )
203         throws SAXException JavaDoc, IOException JavaDoc, ConfigurationException
204     {
205         return buildFromFile( new File JavaDoc( filename ) );
206     }
207
208     /**
209      * Build a configuration object from a file using a File object.
210      * @param file a <code>File</code> object
211      * @return a <code>Configuration</code> object
212      * @throws SAXException if a parsing error occurs
213      * @throws IOException if an I/O error occurs
214      * @throws ConfigurationException if an error occurs
215      */
216     public Configuration buildFromFile( final File JavaDoc file )
217         throws SAXException JavaDoc, IOException JavaDoc, ConfigurationException
218     {
219         synchronized( this )
220         {
221             m_handler.clear();
222             m_parser.parse( file.toURL().toString() );
223             return m_handler.getConfiguration();
224         }
225     }
226
227     /**
228      * Build a configuration object using an InputStream.
229      * @param inputStream an <code>InputStream</code> value
230      * @return a <code>Configuration</code> object
231      * @throws SAXException if a parsing error occurs
232      * @throws IOException if an I/O error occurs
233      * @throws ConfigurationException if an error occurs
234      */
235     public Configuration build( final InputStream JavaDoc inputStream )
236         throws SAXException JavaDoc, IOException JavaDoc, ConfigurationException
237     {
238         return build( new InputSource JavaDoc( inputStream ) );
239     }
240
241     /**
242      * Build a configuration object using an URI
243      * @param uri a <code>String</code> value
244      * @return a <code>Configuration</code> object
245      * @throws SAXException if a parsing error occurs
246      * @throws IOException if an I/O error occurs
247      * @throws ConfigurationException if an error occurs
248      */
249     public Configuration build( final String JavaDoc uri )
250         throws SAXException JavaDoc, IOException JavaDoc, ConfigurationException
251     {
252         return build( new InputSource JavaDoc( uri ) );
253     }
254
255     /**
256      * Build a configuration object using an XML InputSource object
257      * @param input an <code>InputSource</code> value
258      * @return a <code>Configuration</code> object
259      * @throws SAXException if a parsing error occurs
260      * @throws IOException if an I/O error occurs
261      * @throws ConfigurationException if an error occurs
262      */
263     public Configuration build( final InputSource JavaDoc input )
264         throws SAXException JavaDoc, IOException JavaDoc, ConfigurationException
265     {
266         synchronized( this )
267         {
268             m_handler.clear();
269             m_parser.parse( input );
270             return m_handler.getConfiguration();
271         }
272     }
273 }
274
Popular Tags