Node.java revision 325
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * This code is free software; you can redistribute it and/or modify it
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * under the terms of the GNU General Public License version 2 only, as
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * published by the Free Software Foundation. Oracle designates this
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * particular file as subject to the "Classpath" exception as provided
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * by Oracle in the LICENSE file that accompanied this code.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * This code is distributed in the hope that it will be useful, but WITHOUT
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * version 2 for more details (a copy is included in the LICENSE file that
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * accompanied this code).
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * You should have received a copy of the GNU General Public License version
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * 2 along with this work; if not, write to the Free Software Foundation,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * or visit www.oracle.com if you need additional information or have any
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * questions.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * A representation of a node (element) in an XML document.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * This interface extnends the standard DOM Node interface with methods for
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * getting and setting the value of a node, for
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * getting and setting the parent of a node, and for removing a node.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Returns the value of this node if this is a <code>Text</code> node or the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * value of the immediate child of this node otherwise.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * If there is an immediate child of this <code>Node</code> that it is a
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * <code>Text</code> node then it's value will be returned. If there is
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * more than one <code>Text</code> node then the value of the first
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * <code>Text</code> Node will be returned.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Otherwise <code>null</code> is returned.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @return a <code>String</code> with the text of this node if this is a
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * <code>Text</code> node or the text contained by the first
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * immediate child of this <code>Node</code> object that is a
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * <code>Text</code> object if such a child exists;
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * <code>null</code> otherwise.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * If this is a Text node then this method will set its value,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * otherwise it sets the value of the immediate (Text) child of this node.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * The value of the immediate child of this node can be set only if, there is
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * one child node and that node is a <code>Text</code> node, or if
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * there are no children in which case a child <code>Text</code> node will be
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @exception IllegalStateException if the node is not a <code>Text</code>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * node and either has more than one child node or has a child
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * node that is not a <code>Text</code> node.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @since SAAJ 1.2
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Sets the parent of this <code>Node</code> object to the given
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * <code>SOAPElement</code> object.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @param parent the <code>SOAPElement</code> object to be set as
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * the parent of this <code>Node</code> object
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @exception SOAPException if there is a problem in setting the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * parent to the given element
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @see #getParentElement
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk public void setParentElement(SOAPElement parent) throws SOAPException;
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Returns the parent element of this <code>Node</code> object.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * This method can throw an <code>UnsupportedOperationException</code>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * if the tree is not kept in memory.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @return the <code>SOAPElement</code> object that is the parent of
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * this <code>Node</code> object or <code>null</code> if this
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * <code>Node</code> object is root
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @exception UnsupportedOperationException if the whole tree is not
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * kept in memory
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * @see #setParentElement
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Removes this <code>Node</code> object from the tree.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk public void detachNode();
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Notifies the implementation that this <code>Node</code>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * object is no longer being used by the application and that the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * implementation is free to reuse this object for nodes that may
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * be created later.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * Calling the method <code>recycleNode</code> implies that the method
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk * <code>detachNode</code> has been called previously.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk public void recycleNode();