001    /*
002    // $Id: //open/util/resgen/src/org/eigenbase/xom/Parser.java#4 $
003    // Package org.eigenbase.xom is an XML Object Mapper.
004    // Copyright (C) 2005-2005 The Eigenbase Project
005    // Copyright (C) 2005-2005 Disruptive Tech
006    // Copyright (C) 2005-2005 LucidEra, Inc.
007    // Portions Copyright (C) 2001-2005 Kana Software, Inc. and others.
008    //
009    // This library is free software; you can redistribute it and/or modify it
010    // under the terms of the GNU Lesser General Public License as published by the
011    // Free Software Foundation; either version 2 of the License, or (at your
012    // option) any later version approved by The Eigenbase Project.
013    //
014    // This library is distributed in the hope that it will be useful,
015    // but WITHOUT ANY WARRANTY; without even the implied warranty of
016    // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
017    // GNU Lesser General Public License for more details.
018    //
019    // You should have received a copy of the GNU Lesser General Public License
020    // along with this library; if not, write to the Free Software
021    // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
022    //
023    // jhyde, 2 August, 2001
024    */
025    
026    package org.eigenbase.xom;
027    import java.io.InputStream;
028    import java.io.Reader;
029    import java.net.URL;
030    
031    /**
032     * The <code>Parser</code> interface abstracts the behavior which the
033     * <code>org.eigenbase.xom</code> package needs from an XML parser.
034     *
035     * <p>If you don't care which implementation you get, call {@link
036     * XOMUtil#createDefaultParser} to create a parser.</p>
037     *
038     * @author jhyde
039     * @since 2 August, 2001
040     * @version $Id: //open/util/resgen/src/org/eigenbase/xom/Parser.java#4 $
041     **/
042    public interface Parser {
043        /**
044         * Sets whether to retain position information.
045         * @param keepPositions Whether to keep position information.
046         */
047        void setKeepPositions(boolean keepPositions);
048    
049        /**
050         * Returns whether the parser is retaining position information.
051         *
052         * @return Whether to keep position information.
053         */
054        boolean isKeepPositions();
055    
056        /**
057         * Parses a string and returns a wrapped element.
058         *
059         * @param sXml XML string
060         * @return Wrapped element
061         * @throws XOMException on error
062         */
063        DOMWrapper parse(String sXml) throws XOMException;
064    
065        /**
066         * Parses an input stream and returns a wrapped element.
067         *
068         * @param is Input stream
069         * @return Wrapped element
070         * @throws XOMException on error
071         */
072        DOMWrapper parse(InputStream is) throws XOMException;
073    
074        /**
075         * Parses the contents of a URL and returns a wrapped element.
076         *
077         * @param url URL
078         * @return Wrapped element
079         * @throws XOMException on error
080         */
081        DOMWrapper parse(URL url) throws XOMException;
082    
083        /**
084         * Parses the contents of a reader and returns a wrapped element.
085         *
086         * @param reader Reader
087         * @return Wrapped element
088         * @throws XOMException on error
089         */
090        DOMWrapper parse(Reader reader) throws XOMException;
091    
092        /**
093         * Creates a wrapper representing an XML element.
094         *
095         * @param tagName Name of element
096         * @return Wrapper element
097         */
098        DOMWrapper create(String tagName);
099    }
100    
101    // End Parser.java