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
026package org.eigenbase.xom;
027import java.io.InputStream;
028import java.io.Reader;
029import 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 **/
042public 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