Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]

    1   /*   Copyright 2004 The Apache Software Foundation
    2    *
    3    *   Licensed under the Apache License, Version 2.0 (the "License");
    4    *   you may not use this file except in compliance with the License.
    5    *   You may obtain a copy of the License at\\
    6    *
    7    *       http://www.apache.org/licenses/LICENSE-2.0
    8    *
    9    *   Unless required by applicable law or agreed to in writing, software
   10    *   distributed under the License is distributed on an "AS IS" BASIS,
   11    *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   12    *   See the License for the specific language governing permissions and
   13    *  limitations under the License.
   14    */
   15   
   16   package org.apache.xmlbeans;
   17   
   18   import org.apache.xmlbeans.xml.stream.XMLInputStream;
   19   
   20   import java.io.InputStream;
   21   import java.io.OutputStream;
   22   import java.io.Reader;
   23   import java.io.Writer;
   24   import java.io.File;
   25   import java.io.IOException;
   26   
   27   import javax.xml.stream.XMLStreamReader;
   28   
   29   import org.w3c.dom.Node;
   30   
   31   import org.xml.sax.ContentHandler;
   32   import org.xml.sax.ext.LexicalHandler;
   33   import org.xml.sax.SAXException;
   34   
   35   /**
   36    * Represents a holder of XML that can return an {@link XmlCursor}
   37    * or copy itself to various media such as
   38    * {@link Writer Writers} or {@link File Files}.
   39    * Both {@link XmlObject}
   40    * (and thus all XML Beans) and {@link XmlCursor} are
   41    * XmlTokenSource implementations.
   42    * 
   43    * @see XmlObject
   44    * @see XmlCursor
   45    */ 
   46   public interface XmlTokenSource
   47   {
   48       /**
   49        * Returns the synchronization object for the document.  If concurrent
   50        * multithreaded access to a document is required, the access should should
   51        * be protected by synchronizing on this monitor() object.  There is one
   52        * monitor per XML document tree.
   53        */
   54       Object monitor();
   55       
   56       /**
   57        * Returns the XmlDocumentProperties object for the document this token
   58        * source is associated with.
   59        */
   60       XmlDocumentProperties documentProperties();
   61   
   62       /**
   63        * Returns a new XML cursor.
   64        *
   65        * A cursor provides random access to all the tokens in the XML
   66        * data, plus the ability to extract strongly-typed XmlObjects
   67        * for the data. If the data is not read-only, the XML cursor
   68        * also allows modifications to the data.
   69        *
   70        * Using a cursor for the first time typically forces the XML
   71        * document into memory.
   72        */
   73       XmlCursor newCursor();
   74   
   75       /**
   76        * Returns a new XmlInputStream.
   77        *
   78        * The stream starts at the current begin-tag or begin-document
   79        * position and ends at the matching end-tag or end-document.
   80        *
   81        * This is a fail-fast stream, so if the underlying data is changed
   82        * while the stream is being read, the stream throws a
   83        * ConcurrentModificationException.
   84        *
   85        * Throws an IllegalStateException if the XmlTokenSource is not
   86        * positioned at begin-tag or begin-document (e.g., if it is at
   87        * an attribute).
   88        * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
   89        */
   90       XMLInputStream newXMLInputStream();
   91       
   92       /**
   93        * Returns a new XMLStreamReader.
   94        *
   95        * The stream starts at the current begin-tag or begin-document
   96        * position and ends at the matching end-tag or end-document.
   97        *
   98        * This is a fail-fast stream, so if the underlying data is changed
   99        * while the stream is being read, the stream throws a
  100        * ConcurrentModificationException.
  101        */
  102       XMLStreamReader newXMLStreamReader();
  103       
  104       /**
  105        * Returns standard XML text.
  106        * <p>
  107        * The text returned represents the document contents starting at
  108        * the current begin-tag or begin-document and ending at the matching
  109        * end-tag or end-document. This is same content as newReader, but
  110        * it is returned as a single string.
  111        * <p>
  112        * Throws an IllegalStateException if the XmlTokenSource is not
  113        * positioned at begin-tag or begin-document (e.g., if it is at
  114        * an attribute).
  115        * <p>
  116        * Note that this method does not produce XML with the XML declaration, 
  117        * including the encoding information. To save the XML declaration with 
  118        * the XML, see {@link #save(OutputStream)} or {@link #save(OutputStream, XmlOptions)}.
  119        */
  120       String xmlText();
  121   
  122       /**
  123        * Returns a new stream containing standard XML text, encoded
  124        * according to the given encoding.
  125        *
  126        * The byte stream contains contents starting at the current
  127        * begin-tag or begin-document and ending at the matching
  128        * end-tag or end-document.  The specified encoding is used
  129        * and also emitted in a PI at the beginning of the stream.
  130        *
  131        * This is a fail-fast stream, so if the underlying data is changed
  132        * while the stream is being read, the stream throws a
  133        * ConcurrentModificationException.
  134        *
  135        * Throws an IllegalStateException if the XmlTokenSource is not
  136        * positioned at begin-tag or begin-document (e.g., if it is at
  137        * an attribute).
  138        */
  139       InputStream newInputStream();
  140   
  141       /**
  142        * Returns a new character reader containing XML text.
  143        *
  144        * The contents of the reader represents the document contents
  145        * starting at the current begin-tag or begin-document and ending at
  146        * the matching end-tag or end-document.  No encoding annotation
  147        * will be made in the text itself.
  148        *
  149        * This is a fail-fast reader, so if the underlying data is changed
  150        * while the reader is being read, the reader throws a
  151        * ConcurrentModificationException.
  152        *
  153        * Throws an IllegalStateException if the XmlTokenSource is not
  154        * positioned at begin-tag or begin-document (e.g., if it is at
  155        * an attribute).
  156        */
  157       Reader newReader();
  158       
  159       /**
  160        * Returns a W3C DOM Node containing the XML
  161        * represented by this source.  This is a copy of the XML, it is
  162        * not a live with the underlying store of this token source.
  163        * If this is the document node, then a Document is returned, else
  164        * a DocumentFragment is returned.
  165        */
  166       Node newDomNode();
  167   
  168       /**
  169        * Returns a W3C DOM Node containing the XML represented by this source.
  170        * This is a live DOM node, not a copy.  Any changes made through this node
  171        * are immediately reflected in the document associated with this token
  172        * source.  Depending on the kind of token this XmlTokenSource represents,
  173        * an appropriate node will be returned.
  174        */
  175       Node getDomNode();
  176   
  177       /**
  178        * Writes the XML represented by this source to the given SAX content and
  179        * lexical handlers.
  180        * Note that this method does not save the XML declaration, including the encoding information. 
  181        * To save the XML declaration with the XML, see {@link #save(OutputStream)}, 
  182        * {@link #save(OutputStream, XmlOptions)}, {@link #save(File)} or {@link #save(File, XmlOptions)}.
  183        */
  184       void save ( ContentHandler ch, LexicalHandler lh ) throws SAXException;
  185       
  186       /**
  187        * Writes the XML represented by this source to the given File.
  188        * This method will save the XML declaration, including encoding information,
  189        * with the XML.
  190        */
  191       void save ( File file ) throws IOException;
  192       
  193       /**
  194        * Writes the XML represented by this source to the given output stream.
  195        * This method will save the XML declaration, including encoding information,
  196        * with the XML.
  197        */
  198       void save ( OutputStream os ) throws IOException;
  199   
  200       /**
  201        * Writes the XML represented by this source to the given output.
  202        * Note that this method does not save the XML declaration, including the encoding information. 
  203        * To save the XML declaration with the XML, see {@link #save(OutputStream)}, 
  204        * {@link #save(OutputStream, XmlOptions)}, {@link #save(File)} or {@link #save(File, XmlOptions)}.
  205        */
  206       void save ( Writer w ) throws IOException;
  207   
  208       /**
  209        * <p>Just like newXMLInputStream() but with any of a number of options. Use the 
  210        * <em>options</em> parameter to specify the following:</p>
  211        * 
  212        * <table>
  213        * <tr><th>To specify this</th><th>Use this method</th></tr>
  214        * <tr>
  215        *  <td>The character encoding to use when converting the character
  216        *  data in the XML to bytess.</td>
  217        *  <td>{@link XmlOptions#setCharacterEncoding}</td>
  218        * </tr>
  219        * <tr>
  220        *  <td>Prefix-to-namespace mappings that should be assumed
  221        *  when saving this XML. This is useful when the resulting
  222        *  XML will be part of a larger XML document, ensuring that this 
  223        *  inner document will take advantage of namespaces defined in 
  224        *  the outer document.</td>
  225        *  <td>{@link XmlOptions#setSaveImplicitNamespaces}</td>
  226        * </tr>
  227        * <tr>
  228        *  <td>Suggested namespace prefixes to use when saving. Used only
  229        *  when a namespace attribute needs to be synthesized.</td>
  230        *  <td>{@link XmlOptions#setSaveSuggestedPrefixes}</td>
  231        * </tr>
  232        * <tr>
  233        *  <td>That namespace attributes should occur first in elements when
  234        * the XML is saved. By default, they occur last.</td>
  235        *  <td>{@link XmlOptions#setSaveNamespacesFirst}</td>
  236        * </tr>
  237        * <tr>
  238        *  <td>The XML should be pretty printed when saved. Note that this 
  239        *  should only be used for debugging.</td>
  240        *  <td>{@link XmlOptions#setSavePrettyPrint}</td>
  241        * </tr>
  242        * <tr>
  243        *  <td>The number of spaces to use when indenting for pretty printing. 
  244        *  The default is 2.</td>
  245        *  <td>{@link XmlOptions#setSavePrettyPrintIndent}</td>
  246        * </tr>
  247        * <tr>
  248        *  <td>The additional number of spaces indented from the left
  249        *  for pretty printed XML.</td>
  250        *  <td>{@link XmlOptions#setSavePrettyPrintOffset}</td>
  251        * </tr>
  252        * <tr>
  253        *  <td>To minimize the number of namespace attributes generated for the 
  254        *  saved XML. Note that this can reduce performance significantly.</td>
  255        *  <td>{@link XmlOptions#setSaveAggresiveNamespaces}</td>
  256        * </tr>
  257        * <tr>
  258        *  <td>To reduce the size of the saved document
  259        *  by allowing the use of the default namespace. Note that this can 
  260        *  potentially change the semantic meaning of the XML if unprefixed QNames are 
  261        *  present as the value of an attribute or element.</td>
  262        *  <td>{@link XmlOptions#setUseDefaultNamespace}</td>
  263        * </tr>
  264        * <tr>
  265        *  <td>To filter out processing instructions with the specified target name.</td>
  266        *  <td>{@link XmlOptions#setSaveFilterProcinst}</td>
  267        * </tr>
  268        * <tr>
  269        *  <td>Change the QName of the synthesized root element when saving. This 
  270        *  replaces "xml-fragment" with "fragment" in the namespace 
  271        *  http://www.openuri.org/fragment</td>
  272        *  <td>{@link XmlOptions#setSaveUseOpenFrag}</td>
  273        * </tr>
  274        * <tr>
  275        *  <td>Saving should begin on the element's contents.</td>
  276        *  <td>{@link XmlOptions#setSaveInner}</td>
  277        * </tr>
  278        * <tr>
  279        *  <td>Saving should begin on the element, rather than its contents.</td>
  280        *  <td>{@link XmlOptions#setSaveOuter}</td>
  281        * </tr>
  282        * <tr>
  283        *  <td>To rename the document element, or to specify the document element
  284        *  for this XML.</td>
  285        *  <td>{@link XmlOptions#setSaveSyntheticDocumentElement}</td>
  286        * </tr>
  287        * </table>
  288        * 
  289        * @see XmlOptions
  290        * 
  291        * @param options Any of the described options.
  292        * @return A new validating XMLInputStream.
  293        * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
  294        */
  295       XMLInputStream newXMLInputStream(XmlOptions options);
  296   
  297       /**
  298        * Just like newXMLInputStream() but with options.
  299        * Options map may be null.
  300        * @see XmlOptions
  301        */
  302       XMLStreamReader newXMLStreamReader(XmlOptions options);
  303       
  304       /**
  305        * Just like xmlText() but with options.
  306        * Options map may be null.
  307        * <p>
  308        * Note that this method does not produce XML with the XML declaration, 
  309        * including the encoding information. To save the XML declaration with 
  310        * the XML, see {@link #save(OutputStream)} or {@link #save(OutputStream, XmlOptions)}.
  311        *
  312        * @see XmlOptions
  313        */
  314       String xmlText(XmlOptions options);
  315       
  316       /**
  317        *
  318        * Just like newInputStream(String encoding) but with options.
  319        * Options map may be null.
  320        * @see XmlOptions
  321        */
  322       InputStream newInputStream(XmlOptions options);
  323       
  324       /**
  325        * Just like newReader() but with options.
  326        * Options map may be null.
  327        * @see XmlOptions
  328        */
  329       Reader newReader(XmlOptions options);
  330       
  331       /**
  332        * Just like newDomNode() but with options.
  333        * Options map may be null.
  334        * @see XmlOptions
  335        */
  336   
  337       Node newDomNode(XmlOptions options);
  338       
  339       /**
  340        * Writes the XML represented by this source to the given SAX content and
  341        * lexical handlers.
  342        * Note that this method does not save the XML declaration, including the encoding information. 
  343        * To save the XML declaration with the XML, see {@link #save(OutputStream)}, 
  344        * {@link #save(OutputStream, XmlOptions)}, {@link #save(File)} or {@link #save(File, XmlOptions)}.
  345        */
  346       void save ( ContentHandler ch, LexicalHandler lh, XmlOptions options ) throws SAXException;
  347       
  348       /**
  349        * Writes the XML represented by this source to the given File.
  350        * This method will save the XML declaration, including encoding information,
  351        * with the XML.
  352        */
  353       void save ( File file, XmlOptions options ) throws IOException;
  354       
  355       /**
  356        * Writes the XML represented by this source to the given output stream.
  357        * This method will save the XML declaration, including encoding information,
  358        * with the XML.
  359        */
  360       void save ( OutputStream os, XmlOptions options ) throws IOException;
  361   
  362       /**
  363        * Writes the XML represented by this source to the given output.
  364        * Note that this method does not save the XML declaration, including the encoding information. 
  365        * To save the XML declaration with the XML, see {@link #save(OutputStream)}, 
  366        * {@link #save(OutputStream, XmlOptions)}, {@link #save(File)} or {@link #save(File, XmlOptions)}.
  367        */
  368       void save ( Writer w, XmlOptions options ) throws IOException;
  369   
  370       /**
  371        * Prints to stdout the state of the document in which this token source is positioned.
  372        * This is very implementation specific and may change at any time.  Dump can be useful
  373        * for debugging purposes.  It is very different from the save methods which produce
  374        * XML text which only approximates the actual state of the document.
  375        */
  376   
  377       void dump ( );
  378   }

Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]