org.apache.axiom.om.OMNode Maven / Gradle / Ivy
/*
* 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.
*
*
* This tree model for XML captures the idea of deferring the construction of
* child nodes until they are needed. The isComplete 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.
*
*
*
* 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 OMNode.
*
*/
public interface OMNode {
/**
* The node is an Element.
*
* @see #getType()
*/
public static final short ELEMENT_NODE = 1;
/**
* The node is a Text node.
*
* @see #getType()
*/
public static final short TEXT_NODE = XMLStreamConstants.CHARACTERS;
/**
* The node is a CDATASection.
*
* @see #getType()
*/
public static final short CDATA_SECTION_NODE = XMLStreamConstants.CDATA;
/**
* The node is a Comment.
*
* @see #getType()
*/
public static final short COMMENT_NODE = XMLStreamConstants.COMMENT;
/**
* This node is a DTD.
*
* @see #getType()
*/
public static final short DTD_NODE = XMLStreamConstants.DTD;
/**
* This node is a ProcessingInstruction.
*
* @see #getType()
*/
public static final short PI_NODE = XMLStreamConstants.PROCESSING_INSTRUCTION;
/**
* This node is an Entity Reference.
*
* @see #getType()
*/
public static final short ENTITY_REFERENCE_NODE = XMLStreamConstants.ENTITY_REFERENCE;
/**
* This node is an Entity Reference.
*
* @see #getType()
*/
public static final short SPACE_NODE = XMLStreamConstants.SPACE;
/**
* Returns the parent containing node.
*
*
* 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.
*
*
* 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.
*
*
* @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.
*
*
* Discard goes to the parser level and if the element is not completely
* built, then it will be completely skipped at the parser level.
*
*
* @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
*/
public OMFactory getOMFactory();
}