001: /*
002: * $Id: Node.java,v 1.14 2006/03/30 00:59:39 ofung Exp $
003: * $Revision: 1.14 $
004: * $Date: 2006/03/30 00:59:39 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: /**
031: * A representation of a node (element) in an XML document.
032: * This interface extnends the standard DOM Node interface with methods for
033: * getting and setting the value of a node, for
034: * getting and setting the parent of a node, and for removing a node.
035: */
036: public interface Node extends org.w3c.dom.Node {
037: /**
038: * Returns the value of this node if this is a <code>Text</code> node or the
039: * value of the immediate child of this node otherwise.
040: * If there is an immediate child of this <code>Node</code> that it is a
041: * <code>Text</code> node then it's value will be returned. If there is
042: * more than one <code>Text</code> node then the value of the first
043: * <code>Text</code> Node will be returned.
044: * Otherwise <code>null</code> is returned.
045: *
046: * @return a <code>String</code> with the text of this node if this is a
047: * <code>Text</code> node or the text contained by the first
048: * immediate child of this <code>Node</code> object that is a
049: * <code>Text</code> object if such a child exists;
050: * <code>null</code> otherwise.
051: */
052: public String getValue();
053:
054: /**
055: * If this is a Text node then this method will set its value,
056: * otherwise it sets the value of the immediate (Text) child of this node.
057: * The value of the immediate child of this node can be set only if, there is
058: * one child node and that node is a <code>Text</code> node, or if
059: * there are no children in which case a child <code>Text</code> node will be
060: * created.
061: *
062: * @exception IllegalStateException if the node is not a <code>Text</code>
063: * node and either has more than one child node or has a child
064: * node that is not a <code>Text</code> node.
065: *
066: * @since SAAJ 1.2
067: */
068: public void setValue(String value);
069:
070: /**
071: * Sets the parent of this <code>Node</code> object to the given
072: * <code>SOAPElement</code> object.
073: *
074: * @param parent the <code>SOAPElement</code> object to be set as
075: * the parent of this <code>Node</code> object
076: *
077: * @exception SOAPException if there is a problem in setting the
078: * parent to the given element
079: * @see #getParentElement
080: */
081: public void setParentElement(SOAPElement parent)
082: throws SOAPException;
083:
084: /**
085: * Returns the parent element of this <code>Node</code> object.
086: * This method can throw an <code>UnsupportedOperationException</code>
087: * if the tree is not kept in memory.
088: *
089: * @return the <code>SOAPElement</code> object that is the parent of
090: * this <code>Node</code> object or <code>null</code> if this
091: * <code>Node</code> object is root
092: *
093: * @exception UnsupportedOperationException if the whole tree is not
094: * kept in memory
095: * @see #setParentElement
096: */
097: public SOAPElement getParentElement();
098:
099: /**
100: * Removes this <code>Node</code> object from the tree.
101: */
102: public void detachNode();
103:
104: /**
105: * Notifies the implementation that this <code>Node</code>
106: * object is no longer being used by the application and that the
107: * implementation is free to reuse this object for nodes that may
108: * be created later.
109: * <P>
110: * Calling the method <code>recycleNode</code> implies that the method
111: * <code>detachNode</code> has been called previously.
112: */
113: public void recycleNode();
114:
115: }
|