Home » xml-commons-external-1.4.01-src » javax » xml » parsers » [javadoc | source]

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
   10    *
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   
   18   // $Id: SAXParserFactory.java 884950 2009-11-27 18:46:18Z mrglavas $
   19   
   20   package javax.xml.parsers;
   21   
   22   import javax.xml.validation.Schema;
   23   
   24   import org.xml.sax.SAXException;
   25   import org.xml.sax.SAXNotRecognizedException;
   26   import org.xml.sax.SAXNotSupportedException;
   27   
   28   /**
   29    * Defines a factory API that enables applications to configure and
   30    * obtain a SAX based parser to parse XML documents.
   31    *
   32    * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
   33    * @version $Revision: 884950 $, $Date: 2009-11-27 13:46:18 -0500 (Fri, 27 Nov 2009) $
   34    */
   35   public abstract class SAXParserFactory {
   36   
   37       /**
   38        * <p>Should Parsers be validating?</p>
   39        */
   40       private boolean validating = false;
   41       
   42       /**
   43        * <p>Should Parsers be namespace aware?</p>
   44        */
   45       private boolean namespaceAware = false;
   46       
   47       /**
   48        * <p>Protected constructor to force use of {@link #newInstance()}.</p>
   49        */
   50       protected SAXParserFactory () {
   51       
   52       }
   53   
   54       /**
   55        * Obtain a new instance of a <code>SAXParserFactory</code>. This
   56        * static method creates a new factory instance
   57        * This method uses the following ordered lookup procedure to determine
   58        * the <code>SAXParserFactory</code> implementation class to
   59        * load:
   60        * <ul>
   61        * <li>
   62        * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
   63        * property.
   64        * </li>
   65        * <li>
   66        * Use the properties file "lib/jaxp.properties" in the JRE directory.
   67        * This configuration file is in standard <code>java.util.Properties
   68        * </code> format and contains the fully qualified name of the
   69        * implementation class with the key being the system property defined
   70        * above.
   71        * 
   72        * The jaxp.properties file is read only once by the JAXP implementation
   73        * and it's values are then cached for future use.  If the file does not exist
   74        * when the first attempt is made to read from it, no further attempts are
   75        * made to check for its existence.  It is not possible to change the value
   76        * of any property in jaxp.properties after it has been read for the first time.
   77        * </li>
   78        * <li>
   79        * Use the Services API (as detailed in the JAR specification), if
   80        * available, to determine the classname. The Services API will look
   81        * for a classname in the file
   82        * <code>META-INF/services/javax.xml.parsers.SAXParserFactory</code>
   83        * in jars available to the runtime.
   84        * </li>
   85        * <li>
   86        * Platform default <code>SAXParserFactory</code> instance.
   87        * </li>
   88        * </ul>
   89        *
   90        * Once an application has obtained a reference to a
   91        * <code>SAXParserFactory</code> it can use the factory to
   92        * configure and obtain parser instances.
   93        * 
   94        * 
   95        * 
   96        * <h2>Tip for Trouble-shooting</h2>
   97        * <p>Setting the <code>jaxp.debug</code> system property will cause
   98        * this method to print a lot of debug messages
   99        * to <tt>System.err</tt> about what it is doing and where it is looking at.</p>
  100        * 
  101        * <p> If you have problems loading {@link SAXParser}s, try:</p>
  102        * <pre>
  103        * java -Djaxp.debug=1 YourProgram ....
  104        * </pre>
  105        * 
  106        * 
  107        * @return A new instance of a SAXParserFactory.
  108        *
  109        * @exception FactoryConfigurationError if the implementation is
  110        * not available or cannot be instantiated.
  111        */
  112   
  113       public static SAXParserFactory newInstance() {
  114           try {
  115               return (SAXParserFactory) FactoryFinder.find(
  116                   /* The default property name according to the JAXP spec */
  117                   "javax.xml.parsers.SAXParserFactory",
  118                   /* The fallback implementation class name */
  119                   "org.apache.xerces.jaxp.SAXParserFactoryImpl");
  120           } 
  121           catch (FactoryFinder.ConfigurationError e) {
  122               throw new FactoryConfigurationError(e.getException(), e.getMessage());
  123           }
  124       }
  125       
  126       /**
  127        * @return A new instance of a SAXParserFactory.
  128        *
  129        * @exception FactoryConfigurationError if the implementation is
  130        * not available or cannot be instantiated.
  131        */
  132       public static SAXParserFactory newInstance(String factoryClassName,
  133               ClassLoader classLoader) {
  134           if (factoryClassName == null) {
  135               throw new FactoryConfigurationError("factoryClassName cannot be null.");
  136           }
  137           if (classLoader == null) {
  138               classLoader = SecuritySupport.getContextClassLoader();
  139           }
  140           try {
  141               return (SAXParserFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
  142           }
  143           catch (FactoryFinder.ConfigurationError e) {
  144               throw new FactoryConfigurationError(e.getException(), e.getMessage());
  145           }
  146       }
  147       
  148       /**
  149        * <p>Creates a new instance of a SAXParser using the currently
  150        * configured factory parameters.</p>
  151        *
  152        * @return A new instance of a SAXParser.
  153        *
  154        * @exception ParserConfigurationException if a parser cannot
  155        *   be created which satisfies the requested configuration.
  156        * @exception SAXException for SAX errors.
  157        */
  158       
  159       public abstract SAXParser newSAXParser()
  160           throws ParserConfigurationException, SAXException;
  161   
  162       
  163       /**
  164        * Specifies that the parser produced by this code will
  165        * provide support for XML namespaces. By default the value of this is set
  166        * to <code>false</code>.
  167        *
  168        * @param awareness true if the parser produced by this code will
  169        *                  provide support for XML namespaces; false otherwise.
  170        */
  171       
  172       public void setNamespaceAware(boolean awareness) {
  173           this.namespaceAware = awareness;
  174       }
  175   
  176       /**
  177        * Specifies that the parser produced by this code will
  178        * validate documents as they are parsed. By default the value of this is
  179        * set to <code>false</code>.
  180        * 
  181        * <p>
  182        * Note that "the validation" here means
  183        * <a href="http://www.w3.org/TR/REC-xml#proc-types">a validating
  184        * parser</a> as defined in the XML recommendation.
  185        * In other words, it essentially just controls the DTD validation.
  186        * (except the legacy two properties defined in JAXP 1.2.
  187        * See <a href="#validationCompatibility">here</a> for more details.)
  188        * </p>
  189        * 
  190        * <p>
  191        * To use modern schema languages such as W3C XML Schema or
  192        * RELAX NG instead of DTD, you can configure your parser to be
  193        * a non-validating parser by leaving the {@link #setValidating(boolean)}
  194        * method <tt>false</tt>, then use the {@link #setSchema(Schema)}
  195        * method to associate a schema to a parser.
  196        * </p>
  197        *
  198        * @param validating true if the parser produced by this code will
  199        *                   validate documents as they are parsed; false otherwise.
  200        */
  201       
  202       public void setValidating(boolean validating) {
  203           this.validating = validating;
  204       }
  205   
  206       /**
  207        * Indicates whether or not the factory is configured to produce
  208        * parsers which are namespace aware.
  209        *
  210        * @return true if the factory is configured to produce
  211        *         parsers which are namespace aware; false otherwise.
  212        */
  213       
  214       public boolean isNamespaceAware() {
  215           return namespaceAware;
  216       }
  217   
  218       /**
  219        * Indicates whether or not the factory is configured to produce
  220        * parsers which validate the XML content during parse.
  221        *
  222        * @return true if the factory is configured to produce parsers which validate
  223        *         the XML content during parse; false otherwise.
  224        */
  225       
  226       public boolean isValidating() {
  227           return validating;
  228       }
  229   
  230       /**
  231        *
  232        * <p>Sets the particular feature in the underlying implementation of
  233        * org.xml.sax.XMLReader.
  234        * A list of the core features and properties can be found at
  235        * <a href="http://www.saxproject.org/">http://www.saxproject.org/</a></p>
  236        *
  237   	 * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
  238   	 * When the feature is</p>
  239   	 * <ul>
  240   	 *   <li>
  241   	 *     <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
  242   	 *     Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
  243   	 *     If XML processing is limited for security reasons, it will be reported via a call to the registered
  244   	 *     {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
  245   	 *     See {@link SAXParser} <code>parse</code> methods for handler specification.
  246   	 *   </li>
  247   	 *   <li>
  248   	 *     When the feature is <code>false</code>, the implementation will processing XML according to the XML specifications without
  249   	 *     regard to possible implementation limits.
  250   	 *   </li>
  251   	 * </ul>
  252   	 * 
  253        * @param name The name of the feature to be set.
  254        * @param value The value of the feature to be set.
  255        * 
  256        * @exception ParserConfigurationException if a parser cannot
  257        *     be created which satisfies the requested configuration.
  258        * @exception SAXNotRecognizedException When the underlying XMLReader does
  259        *            not recognize the property name.
  260        * @exception SAXNotSupportedException When the underlying XMLReader
  261        *            recognizes the property name but doesn't support the
  262        *            property.
  263        * @throws NullPointerException If the <code>name</code> parameter is null.
  264        *
  265        * @see org.xml.sax.XMLReader#setFeature
  266        */
  267       public abstract void setFeature(String name, boolean value)
  268           throws ParserConfigurationException, SAXNotRecognizedException,
  269                   SAXNotSupportedException;
  270   
  271       /**
  272        *
  273        * <p>Returns the particular property requested for in the underlying
  274        * implementation of org.xml.sax.XMLReader.</p>
  275        *
  276        * @param name The name of the property to be retrieved.
  277        * 
  278        * @return Value of the requested property.
  279        *
  280        * @exception ParserConfigurationException if a parser cannot be created which satisfies the requested configuration.
  281        * @exception SAXNotRecognizedException When the underlying XMLReader does not recognize the property name.
  282        * @exception SAXNotSupportedException When the underlying XMLReader recognizes the property name but doesn't support the property.
  283        *
  284        * @see org.xml.sax.XMLReader#getProperty
  285        */
  286       public abstract boolean getFeature(String name)
  287           throws ParserConfigurationException, SAXNotRecognizedException,
  288                   SAXNotSupportedException;
  289       
  290       /**
  291        * Gets the {@link Schema} object specified through
  292        * the {@link #setSchema(Schema schema)} method.
  293        * 
  294        * 
  295        * @throws UnsupportedOperationException
  296        *      For backward compatibility, when implementations for
  297        *      earlier versions of JAXP is used, this exception will be
  298        *      thrown.
  299        * 
  300        * @return
  301        *      the {@link Schema} object that was last set through
  302        *      the {@link #setSchema(Schema)} method, or null
  303        *      if the method was not invoked since a {@link SAXParserFactory}
  304        *      is created.
  305        * 
  306        * @since 1.5
  307        */
  308       public Schema getSchema() {
  309           throw new UnsupportedOperationException(
  310               "This parser does not support specification \""
  311               + this.getClass().getPackage().getSpecificationTitle()
  312               + "\" version \""
  313               + this.getClass().getPackage().getSpecificationVersion()
  314               + "\""
  315               );
  316       }
  317       
  318       /**
  319        * <p>Set the {@link Schema} to be used by parsers created
  320        * from this factory.</p>
  321        * 
  322        * <p>When a {@link Schema} is non-null, a parser will use a validator
  323        * created from it to validate documents before it passes information
  324        * down to the application.</p>
  325        * 
  326        * <p>When warnings/errors/fatal errors are found by the validator, the parser must
  327        * handle them as if those errors were found by the parser itself. 
  328        * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
  329        * is set, it must receive those errors, and if not, they must be
  330        * treated according to the implementation specific
  331        * default error handling rules.
  332        * 
  333        * <p>A validator may modify the SAX event stream (for example by
  334        * adding default values that were missing in documents), and a parser
  335        * is responsible to make sure that the application will receive
  336        * those modified event stream.</p>  
  337        * 
  338        * <p>Initially, <code>null</code> is set as the {@link Schema}.</p> 
  339        * 
  340        * <p>This processing will take effect even if
  341        * the {@link #isValidating()} method returns <code>false</code>.
  342        * 
  343        * <p>It is an error to use
  344        * the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code>
  345        * property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code>
  346        * property in conjunction with a non-null {@link Schema} object.
  347        * Such configuration will cause a {@link SAXException}
  348        * exception when those properties are set on a {@link SAXParser}.</p>
  349        * 
  350        * <h4>Note for implementors</h4>
  351        * <p>
  352        * A parser must be able to work with any {@link Schema}
  353        * implementation. However, parsers and schemas are allowed
  354        * to use implementation-specific custom mechanisms
  355        * as long as they yield the result described in the specification.
  356        * </p>
  357        * 
  358        * @param schema <code>Schema</code> to use, <code>null</code> to remove a schema.
  359        * 
  360        * @throws UnsupportedOperationException
  361        *      For backward compatibility, when implementations for
  362        *      earlier versions of JAXP is used, this exception will be
  363        *      thrown.
  364        * 
  365        * @since 1.5
  366        */
  367       public void setSchema(Schema schema) {
  368           throw new UnsupportedOperationException(
  369               "This parser does not support specification \""
  370               + this.getClass().getPackage().getSpecificationTitle()
  371               + "\" version \""
  372               + this.getClass().getPackage().getSpecificationVersion()
  373               + "\""
  374               );
  375       }
  376   
  377       /**
  378        * <p>Set state of XInclude processing.</p>
  379        * 
  380        * <p>If XInclude markup is found in the document instance, should it be
  381        * processed as specified in <a href="http://www.w3.org/TR/xinclude/">
  382        * XML Inclusions (XInclude) Version 1.0</a>.</p>
  383        * 
  384        * <p>XInclude processing defaults to <code>false</code>.</p>
  385        * 
  386        * @param state Set XInclude processing to <code>true</code> or
  387        *   <code>false</code>
  388        * 
  389        * @throws UnsupportedOperationException
  390        *      For backward compatibility, when implementations for
  391        *      earlier versions of JAXP is used, this exception will be
  392        *      thrown.
  393        * 
  394        * @since 1.5
  395        */
  396       public void setXIncludeAware(final boolean state) {
  397           throw new UnsupportedOperationException(
  398               "This parser does not support specification \""
  399               + this.getClass().getPackage().getSpecificationTitle()
  400               + "\" version \""
  401               + this.getClass().getPackage().getSpecificationVersion()
  402               + "\""
  403               );
  404       }
  405   
  406       /**
  407        * <p>Get state of XInclude processing.</p>
  408        * 
  409        * @return current state of XInclude processing
  410        * 
  411        * @throws UnsupportedOperationException
  412        *      For backward compatibility, when implementations for
  413        *      earlier versions of JAXP is used, this exception will be
  414        *      thrown.
  415        * 
  416        * @since 1.5
  417        */
  418       public boolean isXIncludeAware() {
  419           throw new UnsupportedOperationException(
  420               "This parser does not support specification \""
  421               + this.getClass().getPackage().getSpecificationTitle()
  422               + "\" version \""
  423               + this.getClass().getPackage().getSpecificationVersion()
  424               + "\""
  425               );
  426       }
  427   }
  428   

Home » xml-commons-external-1.4.01-src » javax » xml » parsers » [javadoc | source]