org.staxnav
Interface StaxNavigator<N>

Type Parameters:

N - the name type

public interface StaxNavigator<N>

Version:

$Revision$

Author:

Alain Defrance

Method Summary

N	child() Attempts to navigate to the first child found and return its name.
boolean	child(N name) Attempts to navigate to the first child having the specified name.
int	descendant(N name) Attempts to navigate to the first descendant with the specified name.
boolean	find(N name) Attempts to navigate to an element following the current one when it has the specified name.
StaxNavigator<N>	fork() Creates a navigator scoped around the currently navigated element.
StaxNavigator<N>	fork(Axis axis) Creates a navigator scoped around the currently navigated element.
java.lang.Iterable<StaxNavigator<N>>	fork(Axis axis, N name) Returns an iterable of stax navigator that is built according to the rules: The current element is added if it matches the specified name. Subsequent elements are found thanks to the provided axis.
java.lang.Iterable<StaxNavigator<N>>	fork(N name) Returns an iterable of stax navigator that is built according to the rules: The current element is added if it matches the specified name. Subsequent elements are found thanks to the sibling(Object) method.
java.lang.String	getAttribute(javax.xml.namespace.QName name) Returns an attribute of the current element or null if such attribute does not exist.
java.lang.String	getAttribute(java.lang.String name) Returns an attribute of the current element or null if such attribute does not exist.
java.util.Map<java.lang.String,java.lang.String>	getAttributes() Returns all attributes of the current element or null when the no valid node is being navigated.
java.lang.String	getContent() Returns the current navigated element textual content.
int	getDepth() Returns the current navigated element depth.
java.lang.String	getLocalName() Returns the string representation of the local xml element.
javax.xml.stream.Location	getLocation() Returns the location of the start tag of the currently navigated element.
N	getName() Returns the current navigated element name.
java.lang.String	getNamespaceByPrefix(java.lang.String prefix) Returns a namespace URI by its prefix or return null if it is not bound.
Naming<N>	getNaming() Returns the naming used for this navigator.
javax.xml.namespace.QName	getQName() Returns the qname of the current xml element.
java.util.Map<javax.xml.namespace.QName,java.lang.String>	getQualifiedAttributes() Returns all attributes of the current element or null when the no valid node is being navigated.
boolean	getTrimContent() Returns the trim content configuration.
N	navigate(Axis axis) Navigates to the next element according to the axis argument and returns its name or null if the end of the stream is reached.
boolean	navigate(Axis axis, N name) Attempt to navigate to the next element according to the axis argument having the specified name.
N	next() Navigates to the next element and returns its name or null if the end of the stream is reached.
boolean	next(N name) Attempt to navigate to the next element having the specified name.
N	next(java.util.Set<N> names) Attempts to navigate to the next element when it belongs to the set of specified names.
<V> V	parseContent(ValueType<V> valueType) Parses the content of the currently navigated element and return the parsed value.
void	setTrimContent(boolean trimContent) Configures the content trimming when getContent() method is invoked.
N	sibling() Attempt to navigate to the next sibling and return its name.
boolean	sibling(N name) Attempts to navigate to the next sibling having the specified name.

Method Detail

getName

N getName()
          throws StaxNavException

Returns the current navigated element name.

Returns:

the element name

Throws:

StaxNavException - any StaxNavException

getNaming

Naming<N> getNaming()

Returns the naming used for this navigator.

Returns:

the naming object used for the navigator.

getLocalName

java.lang.String getLocalName()
                              throws StaxNavException

Returns the string representation of the local xml element.

Returns:

name of xml element

Throws:

StaxNavException - any StaxNavException

getQName

javax.xml.namespace.QName getQName()
                                   throws StaxNavException

Returns the qname of the current xml element.

Returns:

Throws:

StaxNavException

getLocation

javax.xml.stream.Location getLocation()
                                      throws StaxNavException

Returns the location of the start tag of the currently navigated element.

Returns:

the element location

Throws:

StaxNavException - any StaxNavException

getDepth

int getDepth()
             throws StaxNavException

Returns the current navigated element depth.

Returns:

the element level

Throws:

StaxNavException - any StaxNavException

getContent

java.lang.String getContent()
                            throws StaxNavException

Returns the current navigated element textual content. Note that this method is only valid when an element content is not mixed, if an element has a mixed content then this method will return null instead.

Returns:

the element text content

Throws:

StaxNavException - any StaxNavException

setTrimContent

void setTrimContent(boolean trimContent)

Configures the content trimming when getContent() method is invoked.

Parameters:

trimContent - true to trim content

getTrimContent

boolean getTrimContent()

Returns the trim content configuration.

Returns:

the trim content value

parseContent

<V> V parseContent(ValueType<V> valueType)
               throws java.lang.IllegalStateException,
                      java.lang.NullPointerException,
                      StaxNavException,
                      TypeConversionException

Parses the content of the currently navigated element and return the parsed value.

Type Parameters:

V - the generic type of the value

Parameters:

valueType - the content value type

Returns:

the parsed content value

Throws:

java.lang.IllegalStateException - if the current element does not point to a content

java.lang.NullPointerException - if the value type argument is null

StaxNavException - any StaxNavException

TypeConversionException - when the a type conversion error occured

fork

StaxNavigator<N> fork()
                      throws StaxNavException

Creates a navigator scoped around the currently navigated element. The returned navigator will uses the current element as navigation root and the navigation scope is the set of descendants of its root. The forked navigator will use the same configuration than the navigator from which it was forked. The current navigation state will not be affected.

Returns:

a forked navigator

Throws:

StaxNavException - any StaxNavException

fork

StaxNavigator<N> fork(Axis axis)
                      throws java.lang.NullPointerException

Creates a navigator scoped around the currently navigated element. The returned navigator will uses the current element as navigation root and the navigation scope is the set of descendants of its root. The forked navigator will use the same configuration than the navigator from which it was forked. The current navigation state will be moved according to the axis argument value when a valid element is found otherwise it will not change.

Parameters:

axis - the axis

Returns:

a forked navigator

Throws:

java.lang.NullPointerException - if the axis argument is null

fork

java.lang.Iterable<StaxNavigator<N>> fork(N name)
                                          throws java.lang.NullPointerException

Returns an iterable of stax navigator that is built according to the rules:

• The current element is added if it matches the specified name.
• Subsequent elements are found thanks to the sibling(Object) method.

Parameters:

name - the name of the root elements of the forked navigator

Returns:

an iterable of the forks

Throws:

java.lang.NullPointerException - if the name argument is null

fork

java.lang.Iterable<StaxNavigator<N>> fork(Axis axis,
                                          N name)
                                          throws java.lang.NullPointerException

Returns an iterable of stax navigator that is built according to the rules:

• The current element is added if it matches the specified name.
• Subsequent elements are found thanks to the provided axis.

Parameters:

axis - the axis of navigation for the forks

name - the name of the root elements of the forked navigator

Returns:

an iterable of the forks

Throws:

java.lang.NullPointerException - if the name argument is null

find

boolean find(N name)
             throws StaxNavException

Attempts to navigate to an element following the current one when it has the specified name. If the navigation occurs, the navigator now points to that element and the method returns true. Otherwise no navigation happens and the method returns false.

Parameters:

name - the element name to find

Returns:

true if the desired element is reached

Throws:

StaxNavException - any StaxNavException

navigate

N navigate(Axis axis)
           throws StaxNavException

Navigates to the next element according to the axis argument and returns its name or null if the end of the stream is reached.

Parameters:

axis - the navigation axis

Returns:

the element name

Throws:

StaxNavException - any StaxNavException

navigate

boolean navigate(Axis axis,
                 N name)
                 throws StaxNavException

Attempt to navigate to the next element according to the axis argument having the specified name. If the navigation occurs, the navigator now points to that element and the method returns true. Otherwise no navigation happens and the method returns false.

Parameters:

axis - the navigation axis

name - the desired element name

Returns:

true if the desired element is reached

Throws:

java.lang.NullPointerException - if the specified name is null

StaxNavException - any StaxNavException

next

N next()
       throws StaxNavException

Navigates to the next element and returns its name or null if the end of the stream is reached.

Returns:

the element name

Throws:

StaxNavException - any StaxNavException

next

boolean next(N name)
             throws java.lang.NullPointerException,
                    StaxNavException

Attempt to navigate to the next element having the specified name. If the navigation occurs, the navigator now points to that element and the method returns true. Otherwise no navigation happens and the method returns false.

Parameters:

name - the desired element name

Returns:

true if the desired element is reached

Throws:

java.lang.NullPointerException - if the specified name is null

StaxNavException - any StaxNavException

next

N next(java.util.Set<N> names)
       throws java.lang.NullPointerException,
              StaxNavException

Attempts to navigate to the next element when it belongs to the set of specified names. If the navigation occurs, the navigator now points to that element and the method returns the element that was navigated to. Otherwise no navigation happens and the method return null.

Parameters:

names - the set of desired element names

Returns:

the matched name

Throws:

java.lang.NullPointerException - if the names argument is null

StaxNavException - any StaxNavException

child

N child()
        throws StaxNavException

Attempts to navigate to the first child found and return its name. If no such child exists then null is returned.

Returns:

the child name

Throws:

StaxNavException - any StaxNavException

child

boolean child(N name)
              throws java.lang.NullPointerException,
                     StaxNavException

Attempts to navigate to the first child having the specified name. If the navigation occurs, the navigator now points to that element and the method returns true. Otherwise no navigation happens and the method returns false.

Parameters:

name - the child name

Returns:

true if the desired element is reached

Throws:

java.lang.NullPointerException - if the name argument is null

StaxNavException - any StaxNavException

sibling

N sibling()
          throws StaxNavException

Attempt to navigate to the next sibling and return its name. If no such sibling exists then null is returned.

Returns:

the next sibling name

Throws:

StaxNavException - any StaxNavException

sibling

boolean sibling(N name)
                throws java.lang.NullPointerException,
                       StaxNavException

Attempts to navigate to the next sibling having the specified name. If the navigation occurs, the navigator now points to that element and the method returns true. Otherwise no navigation happens and the method returns false.

Parameters:

name - the next sibling name

Returns:

true if the desired element is reached

Throws:

java.lang.NullPointerException - if the name argument is null

StaxNavException - any StaxNavException

getAttribute

java.lang.String getAttribute(java.lang.String name)
                              throws java.lang.NullPointerException,
                                     StaxNavException

Returns an attribute of the current element or null if such attribute does not exist.

Parameters:

name - the attribute name

Returns:

the attribute value

Throws:

java.lang.NullPointerException - if the name argument is null

StaxNavException - any StaxNavException

getAttribute

java.lang.String getAttribute(javax.xml.namespace.QName name)
                              throws java.lang.NullPointerException,
                                     StaxNavException

Returns an attribute of the current element or null if such attribute does not exist.

Parameters:

name - the attribute name

Returns:

the attribute value

Throws:

java.lang.NullPointerException - if the name argument is null

StaxNavException - any StaxNavException

getAttributes

java.util.Map<java.lang.String,java.lang.String> getAttributes()
                                                               throws StaxNavException

Returns all attributes of the current element or null when the no valid node is being navigated.

Returns:

all attributes

Throws:

StaxNavException - any StaxNavException

getQualifiedAttributes

java.util.Map<javax.xml.namespace.QName,java.lang.String> getQualifiedAttributes()
                                                                                 throws StaxNavException

Returns all attributes of the current element or null when the no valid node is being navigated.

Returns:

all attributes

Throws:

StaxNavException - any StaxNavException

getNamespaceByPrefix

java.lang.String getNamespaceByPrefix(java.lang.String prefix)
                                      throws java.lang.NullPointerException,
                                             StaxNavException

Returns a namespace URI by its prefix or return null if it is not bound.

Parameters:

prefix - the prefix

Returns:

the corresponding namespace URI

Throws:

java.lang.NullPointerException - if the prefix is null

StaxNavException - any StaxNavException

descendant

int descendant(N name)
               throws java.lang.NullPointerException,
                      StaxNavException

Attempts to navigate to the first descendant with the specified name. The returned value should be interpreted as:

• a negative value means that no navigation occurred
• any other value is the difference of depth between the two elements

Parameters:

name - the descendant name

Returns:

the

Throws:

java.lang.NullPointerException - if the name is null

StaxNavException - any StaxNavException