1 /*
   2  * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
   3  */
   4 /*
   5  * Licensed to the Apache Software Foundation (ASF) under one or more
   6  * contributor license agreements.  See the NOTICE file distributed with
   7  * this work for additional information regarding copyright ownership.
   8  * The ASF licenses this file to You under the Apache License, Version 2.0
   9  * (the "License"); you may not use this file except in compliance with
  10  * the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  */
  20 
  21 package com.sun.org.apache.xerces.internal.xni.parser;
  22 
  23 import java.io.IOException;
  24 import java.util.Locale;
  25 
  26 import com.sun.org.apache.xerces.internal.xni.XMLDocumentHandler;
  27 import com.sun.org.apache.xerces.internal.xni.XMLDTDHandler;
  28 import com.sun.org.apache.xerces.internal.xni.XMLDTDContentModelHandler;
  29 import com.sun.org.apache.xerces.internal.xni.XNIException;
  30 
  31 /**
  32  * Represents a parser configuration. The parser configuration maintains
  33  * a table of recognized features and properties, assembles components
  34  * for the parsing pipeline, and is responsible for initiating parsing
  35  * of an XML document.
  36  * <p>
  37  * By separating the configuration of a parser from the specific parser
  38  * instance, applications can create new configurations and re-use the
  39  * existing parser components and external API generators (e.g. the
  40  * DOMParser and SAXParser).
  41  * <p>
  42  * The internals of any specific parser configuration instance are hidden.
  43  * Therefore, each configuration may implement the parsing mechanism any
  44  * way necessary. However, the parser configuration should follow these
  45  * guidelines:
  46  * <ul>
  47  *  <li>
  48  *   Call the <code>reset</code> method on each component before parsing.
  49  *   This is only required if the configuration is re-using existing
  50  *   components that conform to the <code>XMLComponent</code> interface.
  51  *   If the configuration uses all custom parts, then it is free to
  52  *   implement everything as it sees fit as long as it follows the
  53  *   other guidelines.
  54  *  </li>
  55  *  <li>
  56  *   Call the <code>setFeature</code> and <code>setProperty</code> method
  57  *   on each component during parsing to propagate features and properties
  58  *   that have changed. This is only required if the configuration is
  59  *   re-using existing components that conform to the <code>XMLComponent</code>
  60  *   interface. If the configuration uses all custom parts, then it is free
  61  *   to implement everything as it sees fit as long as it follows the other
  62  *   guidelines.
  63  *  </li>
  64  *  <li>
  65  *   Pass the same unique String references for all symbols that are
  66  *   propagated to the registered handlers. Symbols include, but may not
  67  *   be limited to, the names of elements and attributes (including their
  68  *   uri, prefix, and localpart). This is suggested but not an absolute
  69  *   must. However, the standard parser components may require access to
  70  *   the same symbol table for creation of unique symbol references to be
  71  *   propagated in the XNI pipeline.
  72  *  </li>
  73  * </ul>
  74  *
  75  * @author Arnaud  Le Hors, IBM
  76  * @author Andy Clark, IBM
  77  *
  78  */
  79 public interface XMLParserConfiguration
  80     extends XMLComponentManager {
  81 
  82     //
  83     // XMLParserConfiguration methods
  84     //
  85 
  86     // parsing
  87 
  88     /**
  89      * Parse an XML document.
  90      * <p>
  91      * The parser can use this method to instruct this configuration
  92      * to begin parsing an XML document from any valid input source
  93      * (a character stream, a byte stream, or a URI).
  94      * <p>
  95      * Parsers may not invoke this method while a parse is in progress.
  96      * Once a parse is complete, the parser may then parse another XML
  97      * document.
  98      * <p>
  99      * This method is synchronous: it will not return until parsing
 100      * has ended.  If a client application wants to terminate
 101      * parsing early, it should throw an exception.
 102      * <p>
 103      * When this method returns, all characters streams and byte streams
 104      * opened by the parser are closed.
 105      *
 106      * @param inputSource The input source for the top-level of the
 107      *                    XML document.
 108      *
 109      * @exception XNIException Any XNI exception, possibly wrapping
 110      *                         another exception.
 111      * @exception IOException  An IO exception from the parser, possibly
 112      *                         from a byte stream or character stream
 113      *                         supplied by the parser.
 114      */
 115     public void parse(XMLInputSource inputSource)
 116         throws XNIException, IOException;
 117 
 118     // generic configuration
 119 
 120     /**
 121      * Allows a parser to add parser specific features to be recognized
 122      * and managed by the parser configuration.
 123      *
 124      * @param featureIds An array of the additional feature identifiers
 125      *                   to be recognized.
 126      */
 127     public void addRecognizedFeatures(String[] featureIds);
 128 
 129     /**
 130      * Sets the state of a feature. This method is called by the parser
 131      * and gets propagated to components in this parser configuration.
 132      *
 133      * @param featureId The feature identifier.
 134      * @param state     The state of the feature.
 135      *
 136      * @throws XMLConfigurationException Thrown if there is a configuration
 137      *                                   error.
 138      */
 139     public void setFeature(String featureId, boolean state)
 140         throws XMLConfigurationException;
 141 
 142     /**
 143      * Returns the state of a feature.
 144      *
 145      * @param featureId The feature identifier.
 146      *
 147      * @throws XMLConfigurationException Thrown if there is a configuration
 148      *                                   error.
 149      */
 150     public boolean getFeature(String featureId)
 151         throws XMLConfigurationException;
 152 
 153     /**
 154      * Allows a parser to add parser specific properties to be recognized
 155      * and managed by the parser configuration.
 156      *
 157      * @param propertyIds An array of the additional property identifiers
 158      *                    to be recognized.
 159      */
 160     public void addRecognizedProperties(String[] propertyIds);
 161 
 162     /**
 163      * Sets the value of a property. This method is called by the parser
 164      * and gets propagated to components in this parser configuration.
 165      *
 166      * @param propertyId The property identifier.
 167      * @param value      The value of the property.
 168      *
 169      * @throws XMLConfigurationException Thrown if there is a configuration
 170      *                                   error.
 171      */
 172     public void setProperty(String propertyId, Object value)
 173         throws XMLConfigurationException;
 174 
 175     /**
 176      * Returns the value of a property.
 177      *
 178      * @param propertyId The property identifier.
 179      *
 180      * @throws XMLConfigurationException Thrown if there is a configuration
 181      *                                   error.
 182      */
 183     public Object getProperty(String propertyId)
 184         throws XMLConfigurationException;
 185 
 186     // handlers
 187 
 188     /**
 189      * Sets the error handler.
 190      *
 191      * @param errorHandler The error resolver.
 192      */
 193     public void setErrorHandler(XMLErrorHandler errorHandler);
 194 
 195     /** Returns the registered error handler. */
 196     public XMLErrorHandler getErrorHandler();
 197 
 198     /**
 199      * Sets the document handler to receive information about the document.
 200      *
 201      * @param documentHandler The document handler.
 202      */
 203     public void setDocumentHandler(XMLDocumentHandler documentHandler);
 204 
 205     /** Returns the registered document handler. */
 206     public XMLDocumentHandler getDocumentHandler();
 207 
 208     /**
 209      * Sets the DTD handler.
 210      *
 211      * @param dtdHandler The DTD handler.
 212      */
 213     public void setDTDHandler(XMLDTDHandler dtdHandler);
 214 
 215     /** Returns the registered DTD handler. */
 216     public XMLDTDHandler getDTDHandler();
 217 
 218     /**
 219      * Sets the DTD content model handler.
 220      *
 221      * @param dtdContentModelHandler The DTD content model handler.
 222      */
 223     public void setDTDContentModelHandler(XMLDTDContentModelHandler dtdContentModelHandler);
 224 
 225     /** Returns the registered DTD content model handler. */
 226     public XMLDTDContentModelHandler getDTDContentModelHandler();
 227 
 228     // other settings
 229 
 230     /**
 231      * Sets the entity resolver.
 232      *
 233      * @param entityResolver The new entity resolver.
 234      */
 235     public void setEntityResolver(XMLEntityResolver entityResolver);
 236 
 237     /** Returns the registered entity resolver. */
 238     public XMLEntityResolver getEntityResolver();
 239 
 240     /**
 241      * Set the locale to use for messages.
 242      *
 243      * @param locale The locale object to use for localization of messages.
 244      *
 245      * @exception XNIException Thrown if the parser does not support the
 246      *                         specified locale.
 247      */
 248     public void setLocale(Locale locale) throws XNIException;
 249 
 250     /** Returns the locale. */
 251     public Locale getLocale();
 252 
 253     /**
 254      * Resumes the parsing process that has been stopped by the {@link #stop()}
 255      * method. The method will simply return if parsing is not stopped.
 256      * @return true if the parsing process can be stopped, false otherwise
 257      * @see javax.xml.parsers.SAXParser
 258      */
 259     public boolean stop();
 260 
 261     /**
 262      * Resumes the parsing process that has been stopped by the {@link #stop()}
 263      * method. The method will simply return if parsing is not stopped.
 264      * @return true if the parsing process is resumed successfully, false
 265      * otherwise
 266      * @see javax.xml.parsers.SAXParser
 267      */
 268     public boolean resume();
 269 } // interface XMLParserConfiguration