/* | |
* Copyright 2004,2005 The Apache Software Foundation. | |
* | |
* Licensed under the Apache License, Version 2.0 (the "License"); | |
* you may not use this file except in compliance with the License. | |
* You may obtain a copy of the License at | |
* | |
* http://www.apache.org/licenses/LICENSE-2.0 | |
* | |
* Unless required by applicable law or agreed to in writing, software | |
* distributed under the License is distributed on an "AS IS" BASIS, | |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
* See the License for the specific language governing permissions and | |
* limitations under the License. | |
*/ | |
package org.apache.ws.commons.om; | |
import javax.xml.stream.XMLStreamConstants; | |
import javax.xml.stream.XMLStreamException; | |
import javax.xml.stream.XMLStreamWriter; | |
import java.io.OutputStream; | |
import java.io.Writer; | |
/** | |
* Defines the base interface used by most of the XML object model within Axis. | |
* | |
* <p>This tree model for XML captures the idea of deferring the construction of child nodes | |
* until they are needed. The <code>isComplete</code> function identifies whether or not | |
* a particular node has been fully parsed. A node may not be fully parsed, for example, if | |
* all of the children of an element have not yet been parsed.</p> | |
* | |
* <p>In comparison to DOM, in this model, you will not find document fragments, or entities. | |
* In addition, while {@link OMDocument} and {@link OMAttribute} exist, neither is an extension | |
* of <code>OMNode</code>. | |
* </p> | |
*/ | |
public interface OMNode { | |
/** | |
* The node is an <code>Element</code>. | |
* | |
* @see #getType() | |
*/ | |
public static final short ELEMENT_NODE = 1; | |
/** | |
* The node is a <code>Text</code> node. | |
* | |
* @see #getType() | |
*/ | |
public static final short TEXT_NODE = XMLStreamConstants.CHARACTERS; | |
/** | |
* The node is a <code>CDATASection</code>. | |
* | |
* @see #getType() | |
*/ | |
public static final short CDATA_SECTION_NODE = XMLStreamConstants.CDATA; | |
/** | |
* The node is a <code>Comment</code>. | |
* | |
* @see #getType() | |
*/ | |
public static final short COMMENT_NODE = XMLStreamConstants.COMMENT; | |
/** | |
* This node is a <code>DTD</code>. | |
* | |
* @see #getType() | |
*/ | |
public static final short DTD_NODE = XMLStreamConstants.DTD; | |
/** | |
* This node is a <code>ProcessingInstruction</code>. | |
* | |
* @see #getType() | |
*/ | |
public static final short PI_NODE = XMLStreamConstants.PROCESSING_INSTRUCTION; | |
/** | |
* This node is an <code>Entity Reference</code>. | |
* | |
* @see #getType() | |
*/ | |
public static final short ENTITY_REFERENCE_NODE = XMLStreamConstants.ENTITY_REFERENCE; | |
/** | |
* This node is an <code>Entity Reference</code>. | |
* | |
* @see #getType() | |
*/ | |
public static final short SPACE_NODE = XMLStreamConstants.SPACE; | |
/** | |
* Returns the parent containing node. | |
* | |
* <p>Returns the parent container, which may be either an {@link OMDocument} or {@link OMElement}. | |
* | |
* @return The {@link OMContainer} of the node. | |
*/ | |
public OMContainer getParent(); | |
/** | |
* Returns the next sibling in document order. | |
* | |
* @return Returns the next sibling in document order. | |
*/ | |
public OMNode getNextOMSibling() throws OMException; | |
/** | |
* Indicates whether parser has parsed this information item completely or not. | |
* If some info are not available in the item, one has to check this attribute to make sure that, this | |
* item has been parsed completely or not. | |
* | |
* @return Returns boolean. | |
*/ | |
public boolean isComplete(); | |
/** | |
* Removes a node (and all of its children) from its containing parent. | |
* | |
* <p>Removes a node from its parent. Partially complete nodes will be completed before | |
* they are detached from the model. A node cannot be detached until its next sibling | |
* has been identified, so that the next sibling and parent can be updated appropriately. | |
* Please note that this will not handle the namespaces. For example, if there you have used a | |
* namespace within the detaching node and which is defined outside the detaching node, user has | |
* to handle it manually. | |
* </p> | |
* | |
* @throws OMException If a node is not complete, the detach can trigger further | |
* parsing, which may cause an exception. | |
*/ | |
public OMNode detach() throws OMException; | |
/** | |
* Discards a node. | |
* | |
* <p>Discard goes to the parser level and if the element is not completely built, then it will be | |
* completely skipped at the parser level.</p> | |
* | |
* @throws OMException | |
*/ | |
public void discard() throws OMException; | |
/** | |
* Inserts a new sibling after the current node. | |
* | |
* @param sibling The node that will be added after the current node. | |
* | |
* @throws OMException | |
*/ | |
public void insertSiblingAfter(OMNode sibling) throws OMException; | |
/** | |
* Inserts a sibling just before the current node. | |
* | |
* @param sibling The node that will be added before the current node. | |
* @throws OMException | |
*/ | |
public void insertSiblingBefore(OMNode sibling) throws OMException; | |
/** | |
* Returns the type of node. | |
* | |
* @return Returns one of {@link #ELEMENT_NODE}, {@link #TEXT_NODE}, {@link #CDATA_SECTION_NODE}, {@link #COMMENT_NODE}, | |
* {@link #DTD_NODE}, {@link #PI_NODE}, {@link #ENTITY_REFERENCE_NODE}, {@link #SPACE_NODE}, | |
* or {@link #TEXT_NODE}. | |
*/ | |
public int getType(); | |
/** | |
* Gets the previous sibling. | |
* | |
* @return Returns node. | |
*/ | |
public OMNode getPreviousOMSibling(); | |
/** | |
* Serializes the node with caching. | |
* | |
* @param xmlWriter | |
* @throws XMLStreamException | |
*/ | |
public void serialize(XMLStreamWriter xmlWriter) | |
throws XMLStreamException; | |
/** | |
* Serializes the node with caching. | |
* | |
* @param output | |
* @throws XMLStreamException | |
*/ | |
public void serialize(OutputStream output) | |
throws XMLStreamException; | |
/** | |
* Serializes the node with caching. | |
* | |
* @param writer | |
* @throws XMLStreamException | |
*/ | |
public void serialize(Writer writer) | |
throws XMLStreamException; | |
/** | |
* Serializes the node with caching. | |
* | |
* @param output | |
* @param format | |
* @throws XMLStreamException | |
*/ | |
public void serialize(OutputStream output, OMOutputFormat format) | |
throws XMLStreamException; | |
/** | |
* Serializes the node with caching. | |
* | |
* @param writer | |
* @param format | |
* @throws XMLStreamException | |
*/ | |
public void serialize(Writer writer, OMOutputFormat format) | |
throws XMLStreamException; | |
/** | |
* Serializes the node without caching. | |
* | |
* @param xmlWriter | |
* @throws XMLStreamException | |
*/ | |
public void serializeAndConsume(XMLStreamWriter xmlWriter) throws XMLStreamException; | |
/** | |
* Serializes the node without caching. | |
* | |
* @param output | |
* @throws XMLStreamException | |
*/ | |
public void serializeAndConsume(OutputStream output) throws XMLStreamException; | |
/** | |
* Serializes the node without caching. | |
* | |
* @param writer | |
* @throws XMLStreamException | |
*/ | |
public void serializeAndConsume(Writer writer) throws XMLStreamException; | |
/** | |
* Serializes the node without caching. | |
* | |
* @param output | |
* @param format | |
* @throws XMLStreamException | |
*/ | |
public void serializeAndConsume(OutputStream output, OMOutputFormat format) throws XMLStreamException; | |
/** | |
* Serializes the node without caching. | |
* | |
* @param writer | |
* @param format | |
* @throws XMLStreamException | |
*/ | |
public void serializeAndConsume(Writer writer, OMOutputFormat format) throws XMLStreamException; | |
/** | |
* Builds itself. | |
*/ | |
public void build(); | |
} |