01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one
03: * or more contributor license agreements. See the NOTICE file
04: * distributed with this work for additional information
05: * regarding copyright ownership. The ASF licenses this file
06: * to you under the Apache License, Version 2.0 (the
07: * "License"); you may not use this file except in compliance
08: * with the License. You may obtain a copy of the License at
09: *
10: * http://www.apache.org/licenses/LICENSE-2.0
11: *
12: * Unless required by applicable law or agreed to in writing,
13: * software distributed under the License is distributed on an
14: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15: * KIND, either express or implied. See the License for the
16: * specific language governing permissions and limitations
17: * under the License.
18: */
19: package javax.xml.soap;
20:
21: /**
22: * A representation of a node (element) in a DOM representation of an XML document that provides
23: * some tree manipulation methods. This interface provides methods for getting the value of a node,
24: * for getting and setting the parent of a node, and for removing a node.
25: */
26: public interface Node extends org.w3c.dom.Node {
27:
28: /**
29: * Returns the the value of the immediate child of this <code>Node</code> object if a child
30: * exists and its value is text.
31: *
32: * @return a <code>String</code> with the text of the immediate child of this <code>Node</code>
33: * object if (1) there is a child and (2) the child is a <code>Text</code> object;
34: * <code>null</code> otherwise
35: */
36: public abstract String getValue();
37:
38: /**
39: * Sets the parent of this <code>Node</code> object to the given <code>SOAPElement</code>
40: * object.
41: *
42: * @param parent the <code>SOAPElement</code> object to be set as the parent of this
43: * <code>Node</code> object
44: * @throws SOAPException if there is a problem in setting the parent to the given element
45: * @see #getParentElement() getParentElement()
46: */
47: public abstract void setParentElement(SOAPElement parent)
48: throws SOAPException;
49:
50: /**
51: * Returns the parent element of this <code>Node</code> object. This method can throw an
52: * <code>UnsupportedOperationException</code> if the tree is not kept in memory.
53: *
54: * @return the <code>SOAPElement</code> object that is the parent of this <code>Node</code>
55: * object or <code>null</code> if this <code>Node</code> object is root
56: * @throws UnsupportedOperationException
57: * if the whole tree is not kept in memory
58: * @see #setParentElement(SOAPElement) setParentElement(javax.xml.soap.SOAPElement)
59: */
60: public abstract SOAPElement getParentElement();
61:
62: /**
63: * Removes this <code>Node</code> object from the tree. Once removed, this node can be garbage
64: * collected if there are no application references to it.
65: */
66: public abstract void detachNode();
67:
68: /**
69: * Notifies the implementation that this <code>Node</code> object is no longer being used by the
70: * application and that the implementation is free to reuse this object for nodes that may be
71: * created later.
72: * <p/>
73: * Calling the method <code>recycleNode</code> implies that the method <code>detachNode</code>
74: * has been called previously.
75: */
76: public abstract void recycleNode();
77:
78: /**
79: * If this is a Text node then this method will set its value, otherwise it sets the value of
80: * the immediate (Text) child of this node. The value of the immediate child of this node can be
81: * set only if, there is one child node and that node is a Text node, or if there are no
82: * children in which case a child Text node will be created.
83: *
84: * @param value the text to set
85: * @throws IllegalStateException if the node is not a Text node and either has more than one
86: * child node or has a child node that is not a Text node
87: */
88:
89: public abstract void setValue(String value);
90: }
|