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    
026    package 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     */
034    public 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