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