src/javax/xml/parsers/SAXParserFactory.java

Print this page




   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.parsers;
  27 
  28 import javax.xml.validation.Schema;
  29 
  30 import org.xml.sax.SAXException;
  31 import org.xml.sax.SAXNotRecognizedException;
  32 import org.xml.sax.SAXNotSupportedException;
  33 
  34 /**
  35  * Defines a factory API that enables applications to configure and
  36  * obtain a SAX based parser to parse XML documents.
  37  *
  38  * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
  39  * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
  40  *
  41  * @version $Revision: 1.9 $, $Date: 2010/05/25 16:19:44 $
  42  *
  43  */
  44 public abstract class SAXParserFactory {
  45     /** The default property name according to the JAXP spec */
  46     private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.SAXParserFactory";
  47 
  48     /**
  49      * <p>Should Parsers be validating?</p>
  50      */
  51     private boolean validating = false;
  52 
  53     /**
  54      * <p>Should Parsers be namespace aware?</p>
  55      */
  56     private boolean namespaceAware = false;
  57 
  58     /**
  59      * <p>Protected constructor to force use of {@link #newInstance()}.</p>
  60      */
  61     protected SAXParserFactory () {


  70      * load:
  71      * <ul>
  72      * <li>
  73      * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
  74      * property.
  75      * </li>
  76      * <li>
  77      * Use the properties file "lib/jaxp.properties" in the JRE directory.
  78      * This configuration file is in standard <code>java.util.Properties
  79      * </code> format and contains the fully qualified name of the
  80      * implementation class with the key being the system property defined
  81      * above.
  82      *
  83      * The jaxp.properties file is read only once by the JAXP implementation
  84      * and it's values are then cached for future use.  If the file does not exist
  85      * when the first attempt is made to read from it, no further attempts are
  86      * made to check for its existence.  It is not possible to change the value
  87      * of any property in jaxp.properties after it has been read for the first time.
  88      * </li>
  89      * <li>
  90      * Use the Services API (as detailed in the JAR specification), if
  91      * available, to determine the classname. The Services API will look
  92      * for a classname in the file
  93      * <code>META-INF/services/javax.xml.parsers.SAXParserFactory</code>
  94      * in jars available to the runtime.


  95      * </li>
  96      * <li>
  97      * Platform default <code>SAXParserFactory</code> instance.
  98      * </li>
  99      * </ul>
 100      *
 101      * Once an application has obtained a reference to a
 102      * <code>SAXParserFactory</code> it can use the factory to
 103      * configure and obtain parser instances.
 104      *
 105      *
 106      *
 107      * <h2>Tip for Trouble-shooting</h2>
 108      * <p>Setting the <code>jaxp.debug</code> system property will cause
 109      * this method to print a lot of debug messages
 110      * to <code>System.err</code> about what it is doing and where it is looking at.</p>
 111      *
 112      * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
 113      * <pre>
 114      * java -Djaxp.debug=1 YourProgram ....
 115      * </pre>
 116      *
 117      *
 118      * @return A new instance of a SAXParserFactory.
 119      *
 120      * @throws FactoryConfigurationError if the implementation is
 121      *   not available or cannot be instantiated.
 122      */
 123 
 124     public static SAXParserFactory newInstance() {
 125         try {
 126             return (SAXParserFactory) FactoryFinder.find(

 127                 /* The default property name according to the JAXP spec */
 128                 "javax.xml.parsers.SAXParserFactory",
 129                 /* The fallback implementation class name */
 130                 "com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl");
 131         } catch (FactoryFinder.ConfigurationError e) {
 132             throw new FactoryConfigurationError(e.getException(),
 133                                                 e.getMessage());
 134         }
 135     }
 136 
 137     /**
 138      * <p>Obtain a new instance of a <code>SAXParserFactory</code> from class name.
 139      * This function is useful when there are multiple providers in the classpath.
 140      * It gives more control to the application as it can specify which provider
 141      * should be loaded.</p>
 142      *
 143      * <p>Once an application has obtained a reference to a <code>SAXParserFactory</code>
 144      * it can use the factory to configure and obtain parser instances.</p>
 145      *
 146      *
 147      * <h2>Tip for Trouble-shooting</h2>
 148      * <p>Setting the <code>jaxp.debug</code> system property will cause
 149      * this method to print a lot of debug messages
 150      * to <code>System.err</code> about what it is doing and where it is looking at.</p>
 151      *
 152      * <p> If you have problems, try:</p>
 153      * <pre>


 155      * </pre>
 156      *
 157      * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.SAXParserFactory</code>.
 158      *
 159      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
 160      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
 161      *
 162      * @return New instance of a <code>SAXParserFactory</code>
 163      *
 164      * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
 165      *                                   the factory class cannot be loaded, instantiated.
 166      *
 167      * @see #newInstance()
 168      *
 169      * @since 1.6
 170      */
 171     public static SAXParserFactory newInstance(String factoryClassName, ClassLoader classLoader){
 172         try {
 173             //do not fallback if given classloader can't find the class, throw exception
 174             return (SAXParserFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
 175         } catch (FactoryFinder.ConfigurationError e) {
 176             throw new FactoryConfigurationError(e.getException(),
 177                                                 e.getMessage());
 178         }
 179     }
 180 
 181     /**
 182      * <p>Creates a new instance of a SAXParser using the currently
 183      * configured factory parameters.</p>
 184      *
 185      * @return A new instance of a SAXParser.
 186      *
 187      * @throws ParserConfigurationException if a parser cannot
 188      *   be created which satisfies the requested configuration.
 189      * @throws SAXException for SAX errors.
 190      */
 191 
 192     public abstract SAXParser newSAXParser()
 193         throws ParserConfigurationException, SAXException;
 194 
 195 
 196     /**
 197      * Specifies that the parser produced by this code will




   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.parsers;
  27 
  28 import javax.xml.validation.Schema;

  29 import org.xml.sax.SAXException;
  30 import org.xml.sax.SAXNotRecognizedException;
  31 import org.xml.sax.SAXNotSupportedException;
  32 
  33 /**
  34  * Defines a factory API that enables applications to configure and
  35  * obtain a SAX based parser to parse XML documents.
  36  *
  37  * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
  38  * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
  39  *
  40  * @version $Revision: 1.10 $, $Date: 2010-11-01 04:36:09 $
  41  *
  42  */
  43 public abstract class SAXParserFactory {
  44     /** The default property name according to the JAXP spec */
  45     private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.SAXParserFactory";
  46 
  47     /**
  48      * <p>Should Parsers be validating?</p>
  49      */
  50     private boolean validating = false;
  51 
  52     /**
  53      * <p>Should Parsers be namespace aware?</p>
  54      */
  55     private boolean namespaceAware = false;
  56 
  57     /**
  58      * <p>Protected constructor to force use of {@link #newInstance()}.</p>
  59      */
  60     protected SAXParserFactory () {


  69      * load:
  70      * <ul>
  71      * <li>
  72      * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
  73      * property.
  74      * </li>
  75      * <li>
  76      * Use the properties file "lib/jaxp.properties" in the JRE directory.
  77      * This configuration file is in standard <code>java.util.Properties
  78      * </code> format and contains the fully qualified name of the
  79      * implementation class with the key being the system property defined
  80      * above.
  81      *
  82      * The jaxp.properties file is read only once by the JAXP implementation
  83      * and it's values are then cached for future use.  If the file does not exist
  84      * when the first attempt is made to read from it, no further attempts are
  85      * made to check for its existence.  It is not possible to change the value
  86      * of any property in jaxp.properties after it has been read for the first time.
  87      * </li>
  88      * <li>
  89      * Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt 
  90      * to locate and load an implementation of the service. If there are providers other than the implementation specific
  91      * default located, then the first provider that is not the default is instantiated and returned; Otherwise
  92      * the default implementation is returned if it is on the classpath or installed as a module.
  93      * 
  94      * If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown, the error will be wrapped 
  95      * in a {@link javax.xml.parsers.FactoryConfigurationException}.</p>
  96      * </li>
  97      * <li>
  98      * Platform default <code>SAXParserFactory</code> instance.
  99      * </li>
 100      * </ul>
 101      *
 102      * Once an application has obtained a reference to a
 103      * <code>SAXParserFactory</code> it can use the factory to
 104      * configure and obtain parser instances.
 105      *
 106      *
 107      *
 108      * <h2>Tip for Trouble-shooting</h2>
 109      * <p>Setting the <code>jaxp.debug</code> system property will cause
 110      * this method to print a lot of debug messages
 111      * to <code>System.err</code> about what it is doing and where it is looking at.</p>
 112      *
 113      * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
 114      * <pre>
 115      * java -Djaxp.debug=1 YourProgram ....
 116      * </pre>
 117      *
 118      *
 119      * @return A new instance of a SAXParserFactory.
 120      *
 121      * @throws FactoryConfigurationError if the implementation is
 122      *   not available or cannot be instantiated.
 123      */
 124 
 125     public static SAXParserFactory newInstance() 
 126     {
 127         try{
 128             return (SAXParserFactory) FactoryFinder.find(SAXParserFactory.class,
 129                     /* The default property name according to the JAXP spec */
 130                     "javax.xml.parsers.SAXParserFactory",
 131                     /* The fallback implementation class name */
 132                     "com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl");
 133         } catch (FactoryConfigurationError e) {
 134             throw e;

 135         }
 136     }
 137 
 138     /**
 139      * <p>Obtain a new instance of a <code>SAXParserFactory</code> from class name.
 140      * This function is useful when there are multiple providers in the classpath.
 141      * It gives more control to the application as it can specify which provider
 142      * should be loaded.</p>
 143      *
 144      * <p>Once an application has obtained a reference to a <code>SAXParserFactory</code>
 145      * it can use the factory to configure and obtain parser instances.</p>
 146      *
 147      *
 148      * <h2>Tip for Trouble-shooting</h2>
 149      * <p>Setting the <code>jaxp.debug</code> system property will cause
 150      * this method to print a lot of debug messages
 151      * to <code>System.err</code> about what it is doing and where it is looking at.</p>
 152      *
 153      * <p> If you have problems, try:</p>
 154      * <pre>


 156      * </pre>
 157      *
 158      * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.SAXParserFactory</code>.
 159      *
 160      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
 161      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
 162      *
 163      * @return New instance of a <code>SAXParserFactory</code>
 164      *
 165      * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
 166      *                                   the factory class cannot be loaded, instantiated.
 167      *
 168      * @see #newInstance()
 169      *
 170      * @since 1.6
 171      */
 172     public static SAXParserFactory newInstance(String factoryClassName, ClassLoader classLoader){
 173         try {
 174             //do not fallback if given classloader can't find the class, throw exception
 175             return (SAXParserFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
 176         } catch (FactoryConfigurationError e) {
 177             throw e;

 178         }
 179     }
 180 
 181     /**
 182      * <p>Creates a new instance of a SAXParser using the currently
 183      * configured factory parameters.</p>
 184      *
 185      * @return A new instance of a SAXParser.
 186      *
 187      * @throws ParserConfigurationException if a parser cannot
 188      *   be created which satisfies the requested configuration.
 189      * @throws SAXException for SAX errors.
 190      */
 191 
 192     public abstract SAXParser newSAXParser()
 193         throws ParserConfigurationException, SAXException;
 194 
 195 
 196     /**
 197      * Specifies that the parser produced by this code will