/* | |
* 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.axiom.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(); | |
/** | |
* Builds itself with the OMText binary content. AXIOM supports two levels | |
* of deffered building. First is deffered building of AXIOM using StAX. | |
* Second level is the deffered building of attachments. AXIOM reads in the | |
* attachements from the stream only when user asks by calling | |
* getDataHandler(). build() method builds the OM without the attachments. | |
* buildAll() builds the OM together with attachement data. This becomes | |
* handy when user wants to free the input stream. | |
*/ | |
public void buildWithAttachments(); | |
/** | |
* Returns the OMFactory that created this object | |
* | |
* @return | |
*/ | |
public OMFactory getOMFactory(); | |
} |