com.sibvisions.util.xml
Class XmlNode

java.lang.Object
  com.sibvisions.util.xml.XmlNode

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public final class XmlNode
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

The XmlNode encapsulates the information of a xml tag. A node can be a comment, tag or xml. The xml type is the first node of a xml file. The xml node contains all other sub xml nodes.

See Also:

Serialized Form

Field Summary

static java.lang.String	NAME_COMMENT Constant value for the name of comment nodes.
static java.lang.String	NAME_DOCTYPE Constant value the name of the doctype node (<?
static java.lang.String	NAME_TEXTPART Constant value for the name of comment nodes.
static java.lang.String	NAME_XMLDECLARATION Constant value the name of the declaration node (<?
static short	TYPE_ATTRIBUTE Constant value for the type of attributes.
static short	TYPE_CDATA Constant value for the type of standard nodes.
static short	TYPE_COMMENT Constant value for the type of comment nodes.
static short	TYPE_DECLARATION Constant value for the type of declaration elements.
static short	TYPE_DOCTYPE Constant value for the doctype.
static short	TYPE_TEXT Constant value for the type of standard nodes.
static short	TYPE_TEXTPART Constant value for the type of standard nodes.

Constructor Summary

XmlNode(short pType, java.lang.String pName)
Creates a new instance of XmlNode without a parent.

XmlNode(short pType, java.lang.String pName, java.lang.String pValue)
Creates a new instance of XmlNode without a parent.

XmlNode(short pType, java.lang.String pName, java.lang.String pValue, XmlNode pParentNode)
Creates a new instance of XmlNode.

XmlNode(short pType, java.lang.String pName, XmlNode pParentNode)
Creates a new instance of XmlNode with a parent.

XmlNode(java.lang.String pName)
Creates a new instance of XmlNode without a parent.

Method Summary

void	add(XmlNode pNode) Adds a XmlNode as a known sub node, at the end of the known sub nodes list.
void	addAll(java.util.Collection<XmlNode> pNodes) Adds all the nodes as a known sub node, at the end of the known sub nodes list.
void	clearSubNodes() Clears the list of known sub elements.
java.lang.Object	clone()
static XmlNode	createDoctype(java.lang.String pName, java.lang.String pPublicId, java.lang.String pSystemId) Creates the xml doctype tag <!
void	createXml(java.io.OutputStream pOut, int pIndent, boolean pInsertNewLines) Create the xml structure based on the current node.
static XmlNode	createXmlDeclaration() Creates the xml declaration tag <?
XmlNode	get(int pIndex) Gets the node from the given index.
int	getColumnNumber() Gets the column number behind the start-tag tag.
XmlNode	getFirstTextNode() Gets the first text node.
int	getLineNumber() Gets the line number of the tag occurence.
java.lang.String	getName() Gets the node name.
XmlNode	getNode(java.lang.String pNodePath) Gets a specific (sub) XmlNode based on the current XmlNode.
int	getNodeCount(java.lang.String pNodePath) Count the elements of a node list.
java.util.List<XmlNode>	getNodes() Gets the list of sub XmlNode elements.
java.util.List<XmlNode>	getNodes(short pType) Gets the list of sub XmlNode elements of the given type.
java.util.List<XmlNode>	getNodes(java.lang.String pNodePath) Gets a list of XmlNodes based on the current XmlNode.
java.lang.String	getNodeValue(java.lang.String pNodePath) Gets the value of a specific (sub) XmlNode based on the current XmlNode.
XmlNode	getParent() Gets the parent XmlNode.
java.util.List<XmlNode>	getSubNodes() Deprecated. since 2.6 use getNodes() instead.
short	getType() Gets the node type.
java.lang.String	getValue() Gets the node value.
static java.lang.String	getXmlValue(java.lang.String pValue) Returns the given value as XML value.
int	indexOf(java.lang.String pNodePath, java.lang.String pValue) Returns the index of the first occurrence of the specified node with the given value, or -1 if this node does not contain the specified node with the given value.
int	indexOf(java.lang.String pNodePath, java.lang.String pValue, int pStartPos) Returns the index of the first occurrence of the specified node with the given value, or -1 if this node does not contain the specified node with the given value.
void	insert(int pPosition, XmlNode pNode) Inserts a XmlNode as a known sub node at a defined position, in the sub node list.
void	insertAll(int pIndex, java.util.Collection<XmlNode> pNodes) Adds all the nodes as a known sub node, at the end of the known sub nodes list.
XmlNode	insertNode(java.lang.String pNodePath, java.lang.Object pValue) Inserts a specific XmlNode at a defined position based on the current XmlNode.
XmlNode	remove(int pIndex) Remove a sub XmlNode from the known sub nodes.
boolean	remove(XmlNode xmnSub) Remove a sub XmlNode from the known sub nodes.
XmlNode	removeNode(java.lang.String pNodePath) Removes a specific (sub) XmlNode based on the current XmlNode.
XmlNode	setNode(java.lang.String pNodePath, java.lang.Object pValue) Sets a specific (sub) XmlNode based on the current XmlNode.
void	setNodes(java.util.List<XmlNode> pNodes) Sets the list of sub XmlNode elements.
void	setSubNodes(java.util.List<XmlNode> pSubNodes) Deprecated. since 2.6 use setNodes(List) instead.
void	setValue(java.lang.String pValue) Sets the node value.
int	size() Returns the number of sub elements.
int	size(short pType) Returns the number of sub elements of the defined type.
java.lang.String	toString()
java.lang.String	toString(boolean pInsertNewLines) Returns the string representation of this node.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TYPE_DECLARATION

public static final short TYPE_DECLARATION

Constant value for the type of declaration elements.

See Also:

Constant Field Values

TYPE_DOCTYPE

public static final short TYPE_DOCTYPE

Constant value for the doctype.

See Also:

Constant Field Values

TYPE_COMMENT

public static final short TYPE_COMMENT

Constant value for the type of comment nodes.

See Also:

Constant Field Values

TYPE_TEXT

public static final short TYPE_TEXT

Constant value for the type of standard nodes.

See Also:

Constant Field Values

TYPE_ATTRIBUTE

public static final short TYPE_ATTRIBUTE

Constant value for the type of attributes.

See Also:

Constant Field Values

TYPE_TEXTPART

public static final short TYPE_TEXTPART

Constant value for the type of standard nodes.

See Also:

Constant Field Values

TYPE_CDATA

public static final short TYPE_CDATA

Constant value for the type of standard nodes.

See Also:

Constant Field Values

NAME_COMMENT

public static final java.lang.String NAME_COMMENT

Constant value for the name of comment nodes.

See Also:

Constant Field Values

NAME_TEXTPART

public static final java.lang.String NAME_TEXTPART

Constant value for the name of comment nodes.

See Also:

Constant Field Values

NAME_XMLDECLARATION

public static final java.lang.String NAME_XMLDECLARATION

Constant value the name of the declaration node (<?xml?>).

See Also:

Constant Field Values

NAME_DOCTYPE

public static final java.lang.String NAME_DOCTYPE

Constant value the name of the doctype node (<?xml?>).

See Also:

Constant Field Values

Constructor Detail

XmlNode

public XmlNode(java.lang.String pName)

Creates a new instance of XmlNode without a parent. The node type is TYPE_TEXT.

Parameters:

pName - name of the node

XmlNode

public XmlNode(short pType,
               java.lang.String pName)

Creates a new instance of XmlNode without a parent.

Parameters:

pType - node type

pName - name of the node

XmlNode

public XmlNode(short pType,
               java.lang.String pName,
               java.lang.String pValue)

Creates a new instance of XmlNode without a parent.

Parameters:

pType - node type

pValue - value of the node

pName - name of the node

XmlNode

public XmlNode(short pType,
               java.lang.String pName,
               XmlNode pParentNode)

Creates a new instance of XmlNode with a parent.

Parameters:

pType - node type

pName - name of the node

pParentNode - parent XmlNode or null

XmlNode

public XmlNode(short pType,
               java.lang.String pName,
               java.lang.String pValue,
               XmlNode pParentNode)

Creates a new instance of XmlNode.

Parameters:

pType - node type

pName - name of the node

pValue - value of the node

pParentNode - parent XmlNode or null

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

get

public XmlNode get(int pIndex)

Gets the node from the given index.

Parameters:

pIndex - the index.

Returns:

the node.

getFirstTextNode

public XmlNode getFirstTextNode()

Gets the first text node. In case of declaration node, this is the root node, or null, if it does not exist.

Returns:

the first text node (root node).

add

public void add(XmlNode pNode)

Adds a XmlNode as a known sub node, at the end of the known sub nodes list.

Parameters:

pNode - instance of the sub node

insert

public void insert(int pPosition,
                   XmlNode pNode)

Inserts a XmlNode as a known sub node at a defined position, in the sub node list.

Parameters:

pPosition - position at which the specified element is to be inserted

pNode - instance of the sub node

addAll

public void addAll(java.util.Collection<XmlNode> pNodes)

Adds all the nodes as a known sub node, at the end of the known sub nodes list.

Parameters:

pNodes - the list of nodes

insertAll

public void insertAll(int pIndex,
                      java.util.Collection<XmlNode> pNodes)

Adds all the nodes as a known sub node, at the end of the known sub nodes list.

Parameters:

pIndex - the index where to insert

pNodes - the list of nodes

getSubNodes

@Deprecated
public java.util.List<XmlNode> getSubNodes()

Deprecated. since 2.6 use getNodes() instead.

Gets the list of sub XmlNode elements. null if there are no sub nodes.

Returns:

list of sub elements

setSubNodes

@Deprecated
public void setSubNodes(java.util.List<XmlNode> pSubNodes)

Deprecated. since 2.6 use setNodes(List) instead.

Sets the list of sub XmlNode elements.

Parameters:

pSubNodes - list of sub elements

setNodes

public void setNodes(java.util.List<XmlNode> pNodes)

Sets the list of sub XmlNode elements. if the given list is an ArrayUtil, it is not cloned and used directly. This is for memory and performance reasons.

Parameters:

pNodes - list of sub elements

getNodes

public java.util.List<XmlNode> getNodes()

Gets the list of sub XmlNode elements. The result is an empty or unmodifiable list of sub nodes. This is for memory and performance reasons using big xml files.

Returns:

list of sub elements

getNodes

public java.util.List<XmlNode> getNodes(short pType)

Gets the list of sub XmlNode elements of the given type. The result is an empty list, if no sub nodes with the type exists.

Parameters:

pType - the type

Returns:

list of sub elements

remove

public boolean remove(XmlNode xmnSub)

Remove a sub XmlNode from the known sub nodes.

Parameters:

xmnSub - instance of the sub node

Returns:

true if the node was removed otherwise false

remove

public XmlNode remove(int pIndex)

Remove a sub XmlNode from the known sub nodes.

Parameters:

pIndex - the index

Returns:

the removed XmlNode

clearSubNodes

public void clearSubNodes()

Clears the list of known sub elements.

getParent

public XmlNode getParent()

Gets the parent XmlNode.

Returns:

parent XmlNode or null if the node has no parent

getType

public short getType()

Gets the node type.

Returns:

type of the node (TYPE_ATTRIBUTE, TYPE_COMMENT, TYPE_TEXT, TYPE_CDATA, TYPE_DECLARATION), TYPE_DOCTYPE)

getName

public java.lang.String getName()

Gets the node name.

Returns:

the node name

setValue

public void setValue(java.lang.String pValue)

Sets the node value.

Parameters:

pValue - node value

getValue

public java.lang.String getValue()

Gets the node value.

Returns:

node value

getXmlValue

public static java.lang.String getXmlValue(java.lang.String pValue)

Returns the given value as XML value.

Parameters:

pValue - the value

Returns:

the value as XML value

getNode

public XmlNode getNode(java.lang.String pNodePath)

Gets a specific (sub) XmlNode based on the current XmlNode. To get a special element of a node list, use brackets to define the element position e.g. /document/nodes(2)

Parameters:

pNodePath - Node path e.g. /document/singlenode

Returns:

null if the XmlNode is not present or the position is invalid, otherwise the XmlNode

Throws:

java.lang.IllegalArgumentException - if the path contains an incomplete or an invalid index

java.lang.IndexOutOfBoundsException - if the path contains an index which is smaller or larger than the allowed length

getNodeValue

public java.lang.String getNodeValue(java.lang.String pNodePath)

Gets the value of a specific (sub) XmlNode based on the current XmlNode. To get a special element of a node list, use brackets to define the element position e.g. /document/nodes(2)

Parameters:

pNodePath - Node path e.g. /document/singlenode

Returns:

null if the XmlNode is not present or the position is invalid, otherwise the value of the XmlNode

Throws:

java.lang.IllegalArgumentException - if the path contains an incomplete or an invalid index

java.lang.IndexOutOfBoundsException - if the path contains an index which is smaller or larger than the allowed length

getNodes

public java.util.List<XmlNode> getNodes(java.lang.String pNodePath)

Gets a list of XmlNodes based on the current XmlNode. If you define a special list element, you will get a list with only one element instead of all list elements.

Parameters:

pNodePath - Node path e.g. /document/nodelist or null to get all sub nodes

Returns:

null if the XmlNode is not present or the position is invalid, otherwise the list with XmlNodes

Throws:

java.lang.IllegalArgumentException - if the path contains an incomplete or an invalid index

java.lang.IndexOutOfBoundsException - if the path contains an index which is smaller or larger than the allowed length

See Also:

getNodes()

getNodeCount

public int getNodeCount(java.lang.String pNodePath)

Count the elements of a node list.

Parameters:

pNodePath - Node path e.g. /document/nodelist

Returns:

0 if the list is empty or the element does not exists, otherwise the element count

Throws:

java.lang.IllegalArgumentException - if the path contains an incomplete or an invalid index

java.lang.IndexOutOfBoundsException - if the path contains an index which is smaller or larger than the allowed length

size

public int size()

Returns the number of sub elements. The size() includes all element types (comment, attribute, ...).

Returns:

the number of sub elements

size

public int size(short pType)

Returns the number of sub elements of the defined type.

Parameters:

pType - type of sub elements to count

Returns:

the number of sub elements

removeNode

public XmlNode removeNode(java.lang.String pNodePath)

Removes a specific (sub) XmlNode based on the current XmlNode.

Parameters:

pNodePath - Node path e.g. /document/singlenode

Returns:

null if the XmlNode is not present or the position is invalid, otherwise the removed XmlNode

Throws:

java.lang.IllegalArgumentException - if the path contains an incomplete or an invalid index

java.lang.IndexOutOfBoundsException - if the path contains an index which is smaller or larger than the allowed length

See Also:

getNode(String)

setNode

public XmlNode setNode(java.lang.String pNodePath,
                       java.lang.Object pValue)

Sets a specific (sub) XmlNode based on the current XmlNode. If the hierarchy is not present, this method will create the necessary elements.

Parameters:

pNodePath - Node path e.g. /document/singlenode

pValue - the pValue can be an instance of XmlNode or any other object. If the pValue is not an instance of XmlNode then the node value will be set to pValue.toString(). Otherwise, if pValue is an instance of XmlNode, the pValue will be used as replacement for the specified node (the name of the node will be used instead of the name defined in the path). The node value will be set to null if pValue == null.

Returns:

null if the XmlNode is not present or the position is invalid, otherwise the new XmlNode

Throws:

java.lang.IllegalArgumentException - if the path contains an incomplete or an invalid index

java.lang.IndexOutOfBoundsException - if the path contains an index which is smaller or larger than the allowed length

insertNode

public XmlNode insertNode(java.lang.String pNodePath,
                          java.lang.Object pValue)

Inserts a specific XmlNode at a defined position based on the current XmlNode. If the hierarchy is not present, this method will create the necessary elements.

Parameters:

pNodePath - Node path with or without position e.g. /document/singlenode(2). The pValue will be inserted before the found node or after the last occurence of the pNodePath, if the position is size() + 1 or not defined.

pValue - the value can be an instance of XmlNode or any other object. If pValue is not an instance of XmlNode, the node value will be pValue.toString(). If it is an instance of XmlNode then the pValue will be used as node (the name of the node will be used instead of the name defined in the path). The node value will be set to null if pValue == null.

Returns:

null if the position, if needed, is invalid or pValue is null, otherwise the inserted XmlNode

Throws:

java.lang.IllegalArgumentException - if the path contains an incomplete or an invalid index

java.lang.IndexOutOfBoundsException - if the path contains an index which is smaller or larger than the allowed length

createXml

public void createXml(java.io.OutputStream pOut,
                      int pIndent,
                      boolean pInsertNewLines)
               throws java.io.IOException

Create the xml structure based on the current node.

Parameters:

pOut - stream for writing the xml structure

pIndent - indentation for sub nodes

pInsertNewLines - true to insert new lines

Throws:

java.io.IOException - if the output operation to pOut fails or the encoding UTF-8 is not usable

createXmlDeclaration

public static XmlNode createXmlDeclaration()

Creates the xml declaration tag <?xml version=\"1.0\" encoding=\"utf-8\">.

Returns:

xml declaration node

createDoctype

public static XmlNode createDoctype(java.lang.String pName,
                                    java.lang.String pPublicId,
                                    java.lang.String pSystemId)

Creates the xml doctype tag <!DOCTYPE name PUBLIC \"publicId\" \"systemId\">.

Parameters:

pName - the doctype name

pPublicId - the public id

pSystemId - the system id

Returns:

xml doctype node

getLineNumber

public int getLineNumber()

Gets the line number of the tag occurence.

Returns:

the line number

getColumnNumber

public int getColumnNumber()

Gets the column number behind the start-tag tag.

Returns:

the column number

indexOf

public int indexOf(java.lang.String pNodePath,
                   java.lang.String pValue)

Returns the index of the first occurrence of the specified node with the given value, or -1 if this node does not contain the specified node with the given value.

Parameters:

pNodePath - the node path

pValue - the search value

Returns:

the position or -1 if the node was not found

Throws:

java.lang.IndexOutOfBoundsException - if the start position is invalid

indexOf

public int indexOf(java.lang.String pNodePath,
                   java.lang.String pValue,
                   int pStartPos)

Returns the index of the first occurrence of the specified node with the given value, or -1 if this node does not contain the specified node with the given value.

Parameters:

pNodePath - the node path

pValue - the search value

pStartPos - the start position of the search

Returns:

the position or -1 if the node was not found

Throws:

java.lang.IndexOutOfBoundsException - if the start position is invalid

toString

public java.lang.String toString(boolean pInsertNewLines)

Returns the string representation of this node.

Parameters:

pInsertNewLines - true to insert new lines

Returns:

the string representation of this node