Top Description Inners Fields Constructors Methods
org.jdom2.util

public final Class NamespaceStack

extends Object
implements Iterable<Namespace>
Class Inheritance
All Implemented Interfaces
java.lang.Iterable
Imports
java.util.ArrayList, .Arrays, .Collections, .Comparator, .Iterator, .List, .NoSuchElementException, org.jdom2.Attribute, .Element, .Namespace, org.jdom2.internal.ArrayCopy
A high-performance stack for processing those Namespaces that are introduced or are in-scope at a point in an Element hierarchy.

This stack implements the 'Namespace Rules' which XML uses, where a Namespace 'redefines' an existing Namespace if they share the same prefix. This class is intended to provide a high-performance mechanism for calculating the Namespace scope for an Element, and identifying what Namespaces an Element introduces in to the scope. This is not a validation tool.

This class implements Iterable which means it can be used in the context of a for-each type loop: 

  NamespaceStack namespacestack = new NamespaceStack();
  for (Namespace ns : namespacestack) {
     ...
  }
The Iteration in the above example will return those Namespaces which are in-scope for the current level of the stack. The Namespace order will follow the JDOM 'standard'. The first namespace will be the Element's Namespace. The subsequent Namespaces will be the other in-scope namespaces in alphabetical order by the Namespace prefix.

NamespaceStack does not validate the push()/pop() cycles. It does not ensure that the pop() is for the same element that was previously pushed. Further, it does not check to make sure that the pushed() Element is the natural child of the previously pushed() Element.

Author
Rolf Lear

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
NamespaceStack.BackwardWalker

Simple read-only iterator that walks an array of Namespace in reverse.

private static class
NamespaceStack.EmptyIterable

Convenience class that makes very fast work for an empty Namespace array.

private static class
NamespaceStack.ForwardWalker

Simple read-only iterator that walks an array of Namespace.

private static class
NamespaceStack.NamespaceIterable

Simple Iterable instance that produces either Forward or Backward read-only iterators of the Namespaces

Field Summary

Modifier and TypeField and Description
private Namespace[][]
added

The namespaces added to the scope at each depth

private static final Namespace[]
DEFAULTSEED

private int
depth

The current depth

private static final Namespace[]
EMPTY

A simple empty Namespace Array to avoid redundant empty instances

private static final Iterable<Namespace>
EMPTYITER

A simple Iterable instance that is always empty.

private static final List<Namespace>
EMPTYLIST

private static final Comparator<Namespace>
NSCOMP

A comparator that sorts Namespaces by their prefix.

private Namespace[][]
scope

The entire scope at each depth

Constructor Summary

AccessConstructor and Description
public
NamespaceStack()

Create a NamespaceWalker ready to use as a stack.

public
NamespaceStack(Namespace[]
The namespaces to set as the top level of the stack.
seed)

Create a NamespaceWalker ready to use as a stack.

Method Summary

Modifier and TypeMethod and Description
public Iterable<Namespace>

Returns:

A read-only Iterable containing added Namespaces (may be empty);
addedForward()

Return an Iterable containing all the Namespaces introduced to the current-level's scope.

public Iterable<Namespace>

Returns:

A read-only Iterable containing added Namespaces (may be empty);
addedReverse()

Return an Iterable containing all the Namespaces introduced to the current-level's scope but in reverse order to addedForward().

private static final int

Returns:

the 'insertion point' - This return value follows the same convention as the standard Java BinarySearch methods (see the JavaDoc for Arrays.binarySearch(). In summary, if the value exists then the return value is the index of the existing value. If the value was not found, then the return value will be negative, and the place where the missing value should be inserted, can be determined by adding 1, and converting back to positive (or converting to positive, and subtracting 1).
binarySearch(final Namespace[]
The Namespaces to search.
data, int
The left side of the range to search INCLUSIVE
left, int
The right side of the range to search EXCLUSIVE
right, final Namespace
The Namespace to search for.
key)

Lots of reasons for having our own binarySearch.

private static final Namespace[]

Returns:

The revised version of 'in-scope' if the scope has changed. If there is no modification then the same input scope will be returned.
checkNamespace(List<Namespace>
Where to add the namespace if it is 'new'
store, Namespace
The Namespace to check
namespace, Namespace[]
The array of Namespaces that are currently in-scope.
scope)

Inspect the scope array to see whether the namespace Namespace is 'new' or not.

public Namespace[]

Returns:

All bound prefixes for the specified URI, or an empty array if the URI is not bound.
getAllNamespacesForURI(final String
The URI to get the first prefix for (null is treated the same as "").
uri)

Get all prefixes in the current scope that are bound to the specified URI.

public Namespace

Returns:

The first bound Namespace for the specified URI, or null if the URI is not bound.
getFirstNamespaceForURI(final String
The URI to get the first prefix for (null is treated the same as "").
uri)

Get the first Namespace in the current scope that is bound to the specified URI.

public Namespace

Returns:

The Namespace with the specified prefix, or null if the prefix is not in scope.
getNamespaceForPrefix(final String
The prefix to get the namespace for (null is treated the same as "").
prefix)

Get the Namespace in the current scope with the specified prefix.

public Namespace

Returns:

the previous binding for the specified prefix, or null if the prefix was not previously bound, or was not changed in this level of the stack.
getRebound(final String
The prefix to check for re-binding
prefix)

If the specified prefix was bound in the previous bind level, and has been rebound to a different URI in the current level, then return the Namespace the the prefix was bound to before.

public Namespace[]

Returns:

a copy of the current scope.
getScope()

Return a new array instance representing the current scope.

public boolean

Returns:

true if the current scope contains that Namespace.
isInScope(Namespace
The Namespace to check
ns)

Inspect the current scope and return true if the specified namespace is in scope.

public Iterator<Namespace>

Returns:

A read-only Iterator containing added Namespaces (may be empty);
iterator()

Implements java.lang.Iterable.iterator.

Get all the Namespaces in-scope at the current level of the stack.
public void
pop()

Restore stack to the level prior to the current one.

public void
push(Element
The element at the new level of the stack.
element)

Create a new in-scope level for the Stack based on an Element.

public void
push(Attribute
The attribute to contribute to the namespace scope.
att)

Create a new in-scope level for the Stack based on an Attribute.

public void
push(Iterable<Namespace>
The Iterable format for the Namespaces.
namespaces)

Create a new in-scope level for the Stack based on an arbitrary set of Namespaces.

public void
push(Namespace...
The array of Namespaces.
namespaces)

Create a new in-scope level for the Stack based on an arbitrary set of Namespaces.

private final void
pushStack(final Namespace mns, Namespace[] newscope, final List<Namespace> toadd)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

addedback to summary
private Namespace[][] added

The namespaces added to the scope at each depth

DEFAULTSEEDback to summary
private static final Namespace[] DEFAULTSEED
depthback to summary
private int depth

The current depth

EMPTYback to summary
private static final Namespace[] EMPTY

A simple empty Namespace Array to avoid redundant empty instances

EMPTYITERback to summary
private static final Iterable<Namespace> EMPTYITER

A simple Iterable instance that is always empty. Saves some memory

EMPTYLISTback to summary
private static final List<Namespace> EMPTYLIST
NSCOMPback to summary
private static final Comparator<Namespace> NSCOMP

A comparator that sorts Namespaces by their prefix.

scopeback to summary
private Namespace[][] scope

The entire scope at each depth

Constructor Detail

NamespaceStackback to summary
public NamespaceStack()

Create a NamespaceWalker ready to use as a stack.

See Also
for comprehensive notes.
NamespaceStackback to summary
public NamespaceStack(Namespace[] seed)

Create a NamespaceWalker ready to use as a stack.

Parameters
seed:Namespace[]

The namespaces to set as the top level of the stack.

See Also
for comprehensive notes.

Method Detail

addedForwardback to summary
public Iterable<Namespace> addedForward()

Return an Iterable containing all the Namespaces introduced to the current-level's scope.

Returns:Iterable<Namespace>

A read-only Iterable containing added Namespaces (may be empty);

See Also
for the details on the data order.
addedReverseback to summary
public Iterable<Namespace> addedReverse()

Return an Iterable containing all the Namespaces introduced to the current-level's scope but in reverse order to addedForward().

Returns:Iterable<Namespace>

A read-only Iterable containing added Namespaces (may be empty);

See Also
for the details on the data order.
binarySearchback to summary
private static final int binarySearch(final Namespace[] data, int left, int right, final Namespace key)

Lots of reasons for having our own binarySearch.

  • We can make it specific for Namespaces (using == search).
  • There is a bug in IBM's AIX JVM in all Java's prior to (including): IBM J9 VM (build 2.4, J2RE 1.6.0 IBM J9 2.4 AIX ppc-32 jvmap3260-20081105_25433 (JIT enabled, AOT enabled)) where it returns '-1' for all instances where 'from == to' instead of returning '-from -1'. See this description for how it is broken, and pre-checking to make sure that left < right for each test is a pain.
  • Ahh, actually, we will never encounter the bug, because we always have a larger-than-1 scope array.... see comment inside code...
  • It's not that complicated, really.
Parameters
data:Namespace[]

The Namespaces to search.

left:int

The left side of the range to search INCLUSIVE

right:int

The right side of the range to search EXCLUSIVE

key:Namespace

The Namespace to search for.

Returns:int

the 'insertion point' - This return value follows the same convention as the standard Java BinarySearch methods (see the JavaDoc for Arrays.binarySearch(). In summary, if the value exists then the return value is the index of the existing value. If the value was not found, then the return value will be negative, and the place where the missing value should be inserted, can be determined by adding 1, and converting back to positive (or converting to positive, and subtracting 1).

checkNamespaceback to summary
private static final Namespace[] checkNamespace(List<Namespace> store, Namespace namespace, Namespace[] scope)

Inspect the scope array to see whether the namespace Namespace is 'new' or not. If it is 'new' then it is added to the store List.

Parameters
store:List<Namespace>

Where to add the namespace if it is 'new'

namespace:Namespace

The Namespace to check

scope:Namespace[]

The array of Namespaces that are currently in-scope.

Returns:Namespace[]

The revised version of 'in-scope' if the scope has changed. If there is no modification then the same input scope will be returned.

getAllNamespacesForURIback to summary
public Namespace[] getAllNamespacesForURI(final String uri)

Get all prefixes in the current scope that are bound to the specified URI.

Parameters
uri:String

The URI to get the first prefix for (null is treated the same as "").

Returns:Namespace[]

All bound prefixes for the specified URI, or an empty array if the URI is not bound.

Since
JDOM 2.1.0
getFirstNamespaceForURIback to summary
public Namespace getFirstNamespaceForURI(final String uri)

Get the first Namespace in the current scope that is bound to the specified URI.

Parameters
uri:String

The URI to get the first prefix for (null is treated the same as "").

Returns:Namespace

The first bound Namespace for the specified URI, or null if the URI is not bound.

Since
JDOM 2.1.0
getNamespaceForPrefixback to summary
public Namespace getNamespaceForPrefix(final String prefix)

Get the Namespace in the current scope with the specified prefix.

Parameters
prefix:String

The prefix to get the namespace for (null is treated the same as "").

Returns:Namespace

The Namespace with the specified prefix, or null if the prefix is not in scope.

Since
JDOM 2.1.0
getReboundback to summary
public Namespace getRebound(final String prefix)

If the specified prefix was bound in the previous bind level, and has been rebound to a different URI in the current level, then return the Namespace the the prefix was bound to before.

Parameters
prefix:String

The prefix to check for re-binding

Returns:Namespace

the previous binding for the specified prefix, or null if the prefix was not previously bound, or was not changed in this level of the stack.

Since
JDOM 2.1.0
getScopeback to summary
public Namespace[] getScope()

Return a new array instance representing the current scope. Modifying the returned array will not affect this scope.

Returns:Namespace[]

a copy of the current scope.

isInScopeback to summary
public boolean isInScope(Namespace ns)

Inspect the current scope and return true if the specified namespace is in scope.

Parameters
ns:Namespace

The Namespace to check

Returns:boolean

true if the current scope contains that Namespace.

iteratorback to summary
public Iterator<Namespace> iterator()

Implements java.lang.Iterable.iterator.

Get all the Namespaces in-scope at the current level of the stack.

Returns:Iterator<Namespace>

A read-only Iterator containing added Namespaces (may be empty);

Annotations
@Override
See Also
for the details on the data order.
popback to summary
public void pop()

Restore stack to the level prior to the current one. The various Iterator methods will thus return the data at the previous level.

pushback to summary
public void push(Element element)

Create a new in-scope level for the Stack based on an Element.
The Namespaces associated with the input Element are used to modify the 'in-scope' Namespaces in this NamespaceStack.
The following 'rules' will be applied:

  • Namespaces used in the input Element that were not part of the previous scope will be added to the new scope level in the stack.
  • If a new Namespace is added to the scope, but the previous scope already had a namespace with the same prefix, then that previous namespace is removed from the new scope (the new Namespace replaces the previous namespace with the same prefix).
  • The order of the in-scope Namespaces will always be: first the Namespace of the input Element followed by all other in-scope Namespaces sorted alphabetically by prefix.
  • The new in-scope Namespace values will be available in this class's iterator() method (which is available as part of this class's Iterable implementation.
  • The namespaces added to the scope by the input Element will be available in the addedForward() Iterable. The order of the added Namespaces follows the same rules as above: first the Element Namespace (only if that Namespace is actually added) followed by the other added namespaces in alphabetical-by-prefix order.
  • The same added namespaces are also available in reverse order in the addedReverse() Iterable.
Parameters
element:Element

The element at the new level of the stack.

pushback to summary
public void push(Attribute att)

Create a new in-scope level for the Stack based on an Attribute.

Parameters
att:Attribute

The attribute to contribute to the namespace scope.

pushback to summary
public void push(Iterable<Namespace> namespaces)

Create a new in-scope level for the Stack based on an arbitrary set of Namespaces.

Parameters
namespaces:Iterable<Namespace>

The Iterable format for the Namespaces.

pushback to summary
public void push(Namespace... namespaces)

Create a new in-scope level for the Stack based on an arbitrary set of Namespaces. The first Namespace in the list will be considered the 'primary' namespace for this scope and will be sorted to the front. If no namespaces are supplied then the 'current' scope will be duplicated (including sort order) as the new scope.

Parameters
namespaces:Namespace[]

The array of Namespaces.

pushStackback to summary
private final void pushStack(final Namespace mns, Namespace[] newscope, final List<Namespace> toadd)
org.jdom2.util back to summary

private final Class NamespaceStack.BackwardWalker

extends Object
implements Iterator<Namespace>
Class Inheritance
All Implemented Interfaces
java.util.Iterator
Simple read-only iterator that walks an array of Namespace in reverse.
Author
rolf

Field Summary

Modifier and TypeField and Description
pack-priv int
cursor

private final Namespace[]
namespaces

Constructor Summary

AccessConstructor and Description
public
BackwardWalker(Namespace[] namespaces)

Method Summary

Modifier and TypeMethod and Description
public boolean
hasNext()

Implements java.util.Iterator.hasNext.

Returns true if the iteration has more elements.
public Namespace
next()

Implements java.util.Iterator.next.

Returns the next element in the iteration.
public void
remove()

Overrides default java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation).
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

cursorback to summary
pack-priv int cursor
namespacesback to summary
private final Namespace[] namespaces

Constructor Detail

BackwardWalkerback to summary
public BackwardWalker(Namespace[] namespaces)

Method Detail

hasNextback to summary
public boolean hasNext()

Implements java.util.Iterator.hasNext.

Doc from java.util.Iterator.hasNext.

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Returns:boolean

true if the iteration has more elements

Annotations
@Override
nextback to summary
public Namespace next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:Namespace

the next element in the iteration

Annotations
@Override
removeback to summary
public void remove()

Overrides default java.util.Iterator.remove.

Doc from java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.

Annotations
@Override
org.jdom2.util back to summary

private final Class NamespaceStack.EmptyIterable

extends Object
implements Iterable<Namespace>, Iterator<Namespace>
Class Inheritance
All Implemented Interfaces
java.util.Iterator, java.lang.Iterable
Convenience class that makes very fast work for an empty Namespace array. It doubles up as both Iterator and Interable.
Author
rolf

Constructor Summary

AccessConstructor and Description
private
EmptyIterable()

Method Summary

Modifier and TypeMethod and Description
public boolean
hasNext()

Implements java.util.Iterator.hasNext.

Returns true if the iteration has more elements.
public Iterator<Namespace>
iterator()

Implements java.lang.Iterable.iterator.

Returns an iterator over elements of type T.
public Namespace
next()

Implements java.util.Iterator.next.

Returns the next element in the iteration.
public void
remove()

Overrides default java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation).
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

EmptyIterableback to summary
private EmptyIterable()

Method Detail

hasNextback to summary
public boolean hasNext()

Implements java.util.Iterator.hasNext.

Doc from java.util.Iterator.hasNext.

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Returns:boolean

true if the iteration has more elements

Annotations
@Override
iteratorback to summary
public Iterator<Namespace> iterator()

Implements java.lang.Iterable.iterator.

Doc from java.lang.Iterable.iterator.

Returns an iterator over elements of type T.

Returns:Iterator<Namespace>

an Iterator.

Annotations
@Override
nextback to summary
public Namespace next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:Namespace

the next element in the iteration

Annotations
@Override
removeback to summary
public void remove()

Overrides default java.util.Iterator.remove.

Doc from java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.

Annotations
@Override
org.jdom2.util back to summary

private final Class NamespaceStack.ForwardWalker

extends Object
implements Iterator<Namespace>
Class Inheritance
All Implemented Interfaces
java.util.Iterator
Simple read-only iterator that walks an array of Namespace.
Author
rolf

Field Summary

Modifier and TypeField and Description
pack-priv int
cursor

private final Namespace[]
namespaces

Constructor Summary

AccessConstructor and Description
public
ForwardWalker(Namespace[] namespaces)

Method Summary

Modifier and TypeMethod and Description
public boolean
hasNext()

Implements java.util.Iterator.hasNext.

Returns true if the iteration has more elements.
public Namespace
next()

Implements java.util.Iterator.next.

Returns the next element in the iteration.
public void
remove()

Overrides default java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation).
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

cursorback to summary
pack-priv int cursor
namespacesback to summary
private final Namespace[] namespaces

Constructor Detail

ForwardWalkerback to summary
public ForwardWalker(Namespace[] namespaces)

Method Detail

hasNextback to summary
public boolean hasNext()

Implements java.util.Iterator.hasNext.

Doc from java.util.Iterator.hasNext.

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Returns:boolean

true if the iteration has more elements

Annotations
@Override
nextback to summary
public Namespace next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:Namespace

the next element in the iteration

Annotations
@Override
removeback to summary
public void remove()

Overrides default java.util.Iterator.remove.

Doc from java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.

Annotations
@Override
org.jdom2.util back to summary

private final Class NamespaceStack.NamespaceIterable

extends Object
implements Iterable<Namespace>
Class Inheritance
All Implemented Interfaces
java.lang.Iterable
Simple Iterable instance that produces either Forward or Backward read-only iterators of the Namespaces
Author
rolf

Field Summary

Modifier and TypeField and Description
private final boolean
forward

private final Namespace[]
namespaces

Constructor Summary

AccessConstructor and Description
public
NamespaceIterable(Namespace[] data, boolean forward)

Method Summary

Modifier and TypeMethod and Description
public Iterator<Namespace>
iterator()

Implements java.lang.Iterable.iterator.

Returns an iterator over elements of type T.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

forwardback to summary
private final boolean forward
namespacesback to summary
private final Namespace[] namespaces

Constructor Detail

NamespaceIterableback to summary
public NamespaceIterable(Namespace[] data, boolean forward)

Method Detail

iteratorback to summary
public Iterator<Namespace> iterator()

Implements java.lang.Iterable.iterator.

Doc from java.lang.Iterable.iterator.

Returns an iterator over elements of type T.

Returns:Iterator<Namespace>

an Iterator.

Annotations
@Override