001/*
002// $Id: //open/util/resgen/src/org/eigenbase/xom/DOMWrapper.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// dsommerfield, 16 July, 2001
024*/
025
026package org.eigenbase.xom;
027
028/**
029 * DOMWrapper implements a Wrapper around the Element class from any DOM-style
030 * XML parser.  The wrapper is used to isolate ElementParser, ElementDef, and
031 * all ElementDef subclasses from the specifics of the underlying XML
032 * parser.
033 */
034public interface DOMWrapper {
035
036    /**
037     * UNKNOWN is used for DOM Element types unsupported by the
038     * wrapper.
039     */
040    public static final int UNKNOWN = 0;
041
042    /**
043     * FREETEXT is a type of DOM Element representing a piece of text (but not
044     * a CDATA section).  For example, <code>Some text</code>.  FREETEXT
045     * elements always have a tag name of NULL and have no children.  It
046     * maps to a {@link TextDef}.
047     **/
048    public static final int FREETEXT = 1;
049
050    /**
051     * ELEMENT is a type of DOM Element representing a named tag, possibly
052     * containing attributes, child elements, and text.  It maps to a {@link
053     * ElementDef} (or a generated class derived from it), or a {@link
054     * GenericDef}.
055     **/
056    public static final int ELEMENT = 2;
057
058    /**
059     * COMMENT is a type of DOM Element representing an XML comment.  It maps
060     * to a {@link CommentDef}.
061     **/
062    public static final int COMMENT = 3;
063
064    /**
065     * CDATA is a type of DOM Element representing a piece of text embedded in
066     * a CDATA section, for example,
067     * <code>&lt;&#33;[CDATA[Some text]]&gt;</code>.
068     * CDATA elements always have a tag name of NULL and have no children.  It
069     * maps to a {@link CdataDef}.
070     **/
071    public static final int CDATA = 4;
072
073    /**
074     * Returns the type of this element/node.  DOMWrapper supports only four
075     * possibilities: {@link #FREETEXT}, {@link #ELEMENT}, {@link #COMMENT},
076     * {@link #CDATA}.
077     */
078    public int getType();
079
080    /**
081     * Returns the tag name of this element, or null for TEXT elements.
082     */
083    public String getTagName();
084
085    /**
086     * Returns the value of the attribute with the given attrName.  If the
087     * attribute is not defined, this method returns null.
088     */
089    public String getAttribute(String attrName);
090
091    /**
092     * Returns a list of attribute names.
093     **/
094    public String[] getAttributeNames();
095
096    /**
097     * Returns a flattened representation of the text inside thie element.
098     * For a TEXT element, this returns the text itself.  For an ELEMENT
099     * element, this returns all pieces of text within the element,
100     * with all markup removed.
101     */
102    public String getText();
103
104    /**
105     * Returns this node serialized as XML.
106     **/
107    public String toXML();
108
109    /**
110     * Returns all children of this element, including TEXT elements, as
111     * an array of DOMWrappers.
112     */
113    public DOMWrapper[] getChildren();
114
115    /**
116     * Returns all element children of this element as an array of
117     * DOMWrappers.
118     */
119    public DOMWrapper[] getElementChildren();
120
121    /**
122     * Returns the location of this element.
123     */
124    public Location getLocation();
125}
126
127
128// End DOMWrapper.java