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 }