element.java

Java的面向对象数据库系统的源代码

      * The behaviour of this method is defined in the
      * <a href="http://www.w3.org/TR/xpath">XPath specification</a>.
      *
      * This method returns the string-value of all the contained
      * {@link Text}, {@link CDATA}, {@link Entity} and {@link Element} nodes
      * all appended together.
      *
      * @return the text from all the child Text and Element nodes appended
      * together.
      */
    public String getStringValue();


    /** Accesses the data of this element which may implement data typing
      * bindings such as XML Schema or
      * Java Bean bindings or will return the same value as {@link #getText}
      */
    public Object getData();

    /** Sets the data value of this element if this element supports data
      * binding or calls {@link #setText} if it doesn't
      */
    public void setData(Object data);


    // Attribute methods
    //-------------------------------------------------------------------------


    /** <p>Returns the {@link Attribute} instances this element contains as
      * a backed {@link List} so that the attributes may be modified directly
      * using the {@link List} interface.
      * The <code>List</code> is backed by the <code>Element</code> so that
      * changes to the list are reflected in the element and vice versa.</p>
      *
      * @return the attributes that this element contains as a <code>List</code>
      */
    public List attributes();

    /** Sets the attributes that this element contains
      */
    public void setAttributes(List attributes);

    /** @return the number of attributes this element contains
      */
    public int attributeCount();

    /** @return an iterator over the attributes of this element
      */
    public Iterator attributeIterator();

    /** Returns the attribute at the specified indexGets the
      *
      * @return the attribute at the specified index where
      * index >= 0 and index < number of attributes or throws
      * an IndexOutOfBoundsException if the index is not within the
      * allowable range
      */
    public Attribute attribute(int index);

    /** Returns the attribute with the given name
      *
      * @return the attribute for the given local name in any namespace.
      * If there are more than one attributes with the given local name
      * in different namespaces then the first one is returned.
      */
    public Attribute attribute(String name);

    /** @param qname is the fully qualified name
      * @return the attribute for the given fully qualified name or null if
      * it could not be found.
      */
    public Attribute attribute(QName qname);

    /** <p>This returns the attribute value for the attribute with the
      * given name and any namespace or null if there is no such
      * attribute or the empty string if the attribute value is empty.</p>
      *
      * @param name is the name of the attribute value to be returnd
      * @return the value of the attribute, null if the attribute does
      * not exist or the empty string
      */
    public String attributeValue(String name);

    /** <p>This returns the attribute value for the attribute with the
      * given name and any namespace or the default value if there is
      * no such attribute value.</p>
      *
      * @param name is the name of the attribute value to be returnd
      * @param defaultValue is the default value to be returned if the
      *    attribute has no value defined.
      * @return the value of the attribute or the defaultValue if the
      *    attribute has no value defined.
      */
    public String attributeValue(String name, String defaultValue);

    /** <p>This returns the attribute value for the attribute with the
      * given fully qualified name or null if there is no such
      * attribute or the empty string if the attribute value is empty.</p>
      *
      * @param qName is the fully qualified name
      * @return the value of the attribute, null if the attribute does
      * not exist or the empty string
      */
    public String attributeValue(QName qName);

    /** <p>This returns the attribute value for the attribute with the
      * given fully qualified name or the default value if
      * there is no such attribute value.</p>
      *
      * @param qName is the fully qualified name
      * @param defaultValue is the default value to be returned if the
      *    attribute has no value defined.
      * @return the value of the attribute or the defaultValue if the
      *    attribute has no value defined.
      */
    public String attributeValue(QName qName, String defaultValue);


    /** <p>Sets the attribute value of the given local name.</p>
      *
      * @param name is the name of the attribute whose value is to be added
      * or updated
      * @param value is the attribute's value
      *
      * @deprecated As of version 0.5. Please use
      *    {@link #addAttribute(String,String)} instead.
      */
    public void setAttributeValue(String name, String value);

    /** <p>Sets the attribute value of the given fully qualified name.</p>
      *
      * @param qName is the fully qualified name of the attribute
      * whose value is to be added or updated
      * @param value is the attribute's value
      *
      * @deprecated As of version 0.5. Please use
      *    {@link #addAttribute(org.dom4j.QName,String)} instead.
      */
    public void setAttributeValue(QName qName, String value);


    // Content methods
    //-------------------------------------------------------------------------


    /** Returns the first element for the given local name and any namespace.
      *
      * @return the first element with the given local name
      */
    public Element element(String name);

    /** Returns the first element for the given fully qualified name.
      *
      * @param qname is the fully qualified name to search for
      * @return the first element with the given fully qualified name
      */
    public Element element(QName qname);

    /** <p>Returns the elements contained in this element.
      * If this element does not contain any elements then this method returns
      * an empty list.
      *
      * The list is backed by the element such that changes to the list will
      * be reflected in the element though the reverse is not the case.</p>
      *
      * @return a list of all the elements in this element.
      */
    public List elements();

    /** <p>Returns the elements contained in this element with the given
      * local name and any namespace.
      * If no elements are found then this method returns an empty list.
      *
      * The list is backed by the element such that changes to the list will
      * be reflected in the element though the reverse is not the case.</p>
      *
      * @return a list of all the elements in this element for the given
      * local name
      */
    public List elements(String name);

    /** <p>Returns the elements contained in this element with the given
      * fully qualified name.
      * If no elements are found then this method returns an empty list.
      *
      * The list is backed by the element such that changes to the list will
      * be reflected in the element though the reverse is not the case.</p>
      *
      * @param qName is the fully qualified name to search for
      * @return a list of all the elements in this element for the
      * given fully qualified name.
      */
    public List elements(QName qName);

    /** Returns an iterator over all this elements child elements.
      *
      * @return an iterator over the contained elements
      */
    public Iterator elementIterator();

    /** Returns an iterator over the elements contained in this element
      * which match the given local name and any namespace.
      *
      * @return an iterator over the contained elements matching the given
      * local name
      */
    public Iterator elementIterator(String name);

    /** Returns an iterator over the elements contained in this element
      * which match the given fully qualified name.
      *
      * @param qname is the fully qualified name to search for
      * @return an iterator over the contained elements matching the given
      * fully qualified name
      */
    public Iterator elementIterator(QName qname);



    // Helper methods
    //-------------------------------------------------------------------------

    /** @return true if this element is the root element of a document
      * and this element supports the parent relationship else false.
      */
    public boolean isRootElement();

    /** <p>Returns true if this <code>Element</code> has mixed content.
      * Mixed content means that an element contains both textual data and
      * child elements.
      *
      * @return true if this element contains mixed content.
      */
    public boolean hasMixedContent();

    /** <p>Returns true if this <code>Element</code> has text only content.
      *
      * @return true if this element is empty or only contains text content.
      */
    public boolean isTextOnly();


    /** Appends the attributes of the given element to me.
      * This method behaves like the {@link java.util.Collection#addAll(java.util.Collection)}
      * method.
      *
      * @param element is the element whose attributes will be added to me.
      */
    public void appendAttributes(Element element);

    /** <p>Creates a deep copy of this element
      * The new element is detached from its parent, and getParent() on the
      * clone will return null.</p>
      *
      * @return a new deep copy Element
      */
    public Element createCopy();

    /** <p>Creates a deep copy of this element with the given local name
      * The new element is detached from its parent, and getParent() on the
      * clone will return null.</p>
      *
      * @return a new deep copy Element
      */
    public Element createCopy(String name);

    /** <p>Creates a deep copy of this element with the given fully qualified name.
      * The new element is detached from its parent, and getParent() on the
      * clone will return null.</p>
      *
      * @return a new deep copy Element
      */
    public Element createCopy(QName qName);

    public String elementText(String name);
    public String elementText(QName qname);
    public String elementTextTrim(String name);
    public String elementTextTrim(QName qname);

    /** Returns a node at the given index suitable for an XPath result set.
      * This means the resulting Node will either be null or it will support
      * the parent relationship.
      *
      * @return the Node for the given index which will support the parent
      * relationship or null if there is not a node at the given index.
      */
    public Node getXPathResult(int index);


}




/*
 * Redistribution and use of this software and associated documentation
 * ("Software"), with or without modification, are permitted provided
 * that the following conditions are met:
 *
 * 1. Redistributions of source code must retain copyright
 *    statements and notices.  Redistributions must also contain a
 *    copy of this document.
 *
 * 2. Redistributions in binary form must reproduce the
 *    above copyright notice, this list of conditions and the
 *    following disclaimer in the documentation and/or other
 *    materials provided with the distribution.
 *
 * 3. The name "DOM4J" must not be used to endorse or promote
 *    products derived from this Software without prior written
 *    permission of MetaStuff, Ltd.  For written permission,
 *    please contact [e-mail].
 *
 * 4. Products derived from this Software may not be called "DOM4J"
 *    nor may "DOM4J" appear in their names without prior written
 *    permission of MetaStuff, Ltd. DOM4J is a registered
 *    trademark of MetaStuff, Ltd.
 *
 * 5. Due credit should be given to the DOM4J Project
 *    (http://dom4j.org/).
 *
 * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
 * METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved.
 *
 * $Id: Element.java,v 1.5 2003/11/02 17:58:36 per_nyfelt Exp $
 */