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    }