001 /*
002 * Copyright 2001-2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.xml.soap;
017
018 /**
019 * A representation of a node (element) in a DOM representation of an XML document
020 * that provides some tree manipulation methods.
021 * This interface provides methods for getting the value of a node, for
022 * getting and setting the parent of a node, and for removing a node.
023 */
024 public interface Node extends org.w3c.dom.Node {
025
026 /**
027 * Returns the the value of the immediate child of this <code>Node</code>
028 * object if a child exists and its value is text.
029 * @return a <code>String</code> with the text of the immediate child of
030 * this <code>Node</code> object if (1) there is a child and
031 * (2) the child is a <code>Text</code> object;
032 * <code>null</code> otherwise
033 */
034 public abstract String getValue();
035
036 /**
037 * Sets the parent of this <code>Node</code> object to the given
038 * <code>SOAPElement</code> object.
039 * @param parent the <code>SOAPElement</code> object to be set as
040 * the parent of this <code>Node</code> object
041 * @throws SOAPException if there is a problem in setting the
042 * parent to the given element
043 * @see #getParentElement() getParentElement()
044 */
045 public abstract void setParentElement(SOAPElement parent)
046 throws SOAPException;
047
048 /**
049 * Returns the parent element of this <code>Node</code> object.
050 * This method can throw an <code>UnsupportedOperationException</code>
051 * if the tree is not kept in memory.
052 * @return the <code>SOAPElement</code> object that is the parent of
053 * this <code>Node</code> object or <code>null</code> if this
054 * <code>Node</code> object is root
055 * @throws java.lang.UnsupportedOperationException if the whole tree is not kept in memory
056 * @see #setParentElement(javax.xml.soap.SOAPElement) setParentElement(javax.xml.soap.SOAPElement)
057 */
058 public abstract SOAPElement getParentElement();
059
060 /**
061 * Removes this <code>Node</code> object from the tree. Once
062 * removed, this node can be garbage collected if there are no
063 * application references to it.
064 */
065 public abstract void detachNode();
066
067 /**
068 * Notifies the implementation that this <code>Node</code>
069 * object is no longer being used by the application and that the
070 * implementation is free to reuse this object for nodes that may
071 * be created later.
072 * <P>
073 * Calling the method <code>recycleNode</code> implies that the method
074 * <code>detachNode</code> has been called previously.
075 */
076 public abstract void recycleNode();
077
078 /**
079 * If this is a Text node then this method will set its value, otherwise it
080 * sets the value of the immediate (Text) child of this node. The value of
081 * the immediate child of this node can be set only if, there is one child
082 * node and that node is a Text node, or if there are no children in which
083 * case a child Text node will be created.
084 *
085 * @param value the text to set
086 * @throws IllegalStateException if the node is not a Text node and
087 * either has more than one child node or has a child node that
088 * is not a Text node
089 */
090
091 public abstract void setValue(String value);
092 }