View Javadoc

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