Package org.apache.sis.io.wkt

Class StoredTree

java.lang.Object

org.apache.sis.io.wkt.StoredTree

All Implemented Interfaces:

Serializable

final class StoredTree
extends Object
implements Serializable

A tree of Elements saved for later use. StoredTrees are created in following situations:

• WKTFormat.addFragment(String, String) for defining shortcuts to be inserted into an arbitrary number of other WKT strings.
• WKTDictionary.addDefinitions(Stream) for preparing WKT definitions to be parsed only when first needed. While WKT trees are waiting, they may share references to same Node instances for reducing memory usage.

This class does not store Element instances directly because Elements are not easily shareable. Contrarily to Element design, StoredTree needs unmodifiable Element.children list and needs to store Element.offset values in separated arrays. Those changes make possible to have many StoredTree instances sharing the same Node instances in the common case where some WKT elements are repeated in many trees.

Since:

1.1

Version:

1.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	StoredTree.Deflater	A helper class for compressing a tree of Elements as a tree of StoredTree.Nodes.
private static final class	StoredTree.Inflater	A helper class for decompressing a tree of Elements from a tree of StoredTree.Nodes.
private static final class	StoredTree.Node	Unmodifiable copy of Element without contextual information such as Element.offset.

Field Summary

Fields

Modifier and Type	Field	Description
private final short[]	offsets	Indices in the WKT string where elements have been found.
private final StoredTree.Node	root	Root of a tree of Element snapshots.
private static final long	serialVersionUID	Indirectly for WKTFormat serialization compatibility.

Constructor Summary

Constructors

Constructor	Description
StoredTree(List<Element> trees, Map<Object,Object> sharedValues)	Creates a new StoredTree with a snapshot of given trees of elements.
StoredTree(Element tree, Map<Object,Object> sharedValues)	Creates a new StoredTree with a snapshot of given tree of elements.

Method Summary

Modifier and Type	Method	Description
(package private) final void	forEachValue(Consumer<Object> addTo)	Adds keywords and children to the given supplier.
(package private) final String	keyword()	Returns the keyword of the root element.
(package private) final void	peekIdentifiers(Object[] fullId)	Stores identifier information in the given array.
(package private) final void	toElements(AbstractParser parser, Collection<? super Element> addTo, int isFragment)	Recreates Element trees.
String	toString()	Returns the string representation of the first value of the root element, which is usually the element name.

Methods inherited from class java.lang.Object

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

Field Details

serialVersionUID

private static final long serialVersionUID

Indirectly for WKTFormat serialization compatibility.

See Also:

• Constant Field Values

root

private final StoredTree.Node root

Root of a tree of Element snapshots.

Multi-roots

There is exactly one root in the vast majority of cases. However, there is a situation where we need to allow more roots: when user wants to represent a coordinate system. A WKT 2 coordinate system looks like: While axes are conceptually parts of coordinate system, they are not declared inside the CS[…] element for historical reasons (for compatibility with WKT 1). For representing such "flattened tree", we need an array of roots. We do that by wrapping that array in a synthetic StoredTree.Node with null keyword() (an "anonymous node").

offsets

private final short[] offsets

Indices in the WKT string where elements have been found. If negative, the actual offset value is ~offset and Element.isFragment shall be set to true. This array shall not be modified because it may be shared by many StoredTrees.

See Also:

• StoredTree.Deflater.addOffset(Element)
• StoredTree.Inflater.nextOffset()

Constructor Details

StoredTree

StoredTree(Element tree,
 Map<Object,Object> sharedValues)

Creates a new StoredTree with a snapshot of given tree of elements.

Parameters:

tree - root of the tree of WKT elements.

sharedValues - pool to use for sharing unique instances of values.

StoredTree

StoredTree(List<Element> trees,
 Map<Object,Object> sharedValues)

Creates a new StoredTree with a snapshot of given trees of elements. This is for a corner case only; see "Multi roots" in root.

Parameters:

trees - roots of the trees of WKT elements.

sharedValues - pool to use for sharing unique instances of values.

Method Details

toElements

final void toElements(AbstractParser parser,
 Collection<? super Element> addTo,
 int isFragment)

Recreates Element trees. This method is the converse of the constructor. This method usually adds exactly one element to the given list, except for the "multi-roots" corner case documented in root.

Parameters:

parser - the parser which will be used for parsing the tree.

addTo - where to add the elements.

isFragment - non-zero if and only if Element.isFragment shall be true. In such case, this value must be ~Element.offset.

peekIdentifiers

final void peekIdentifiers(Object[] fullId)

Stores identifier information in the given array. This method locates the last "ID" (WKT 2) or "AUTHORITY" (WKT 1) node and optionally the "CITATION" sub-node. Values are copied in the given array, in that order!

1. Code space
2. Code
3. Version if present
4. Authority if present (skipped if the array length is less than 4)

If any of above values is missing, the corresponding array element is left unchanged. Callers should set all array elements to null before to invoke this method.

Parameters:

fullId - where to store code space, code, version, authority.

forEachValue

final void forEachValue(Consumer<Object> addTo)

Adds keywords and children to the given supplier. This is for testing purposes only.

See Also:

• WKTDictionary.forEachValue(Consumer)

keyword

final String keyword()

Returns the keyword of the root element.

toString

public String toString()

Returns the string representation of the first value of the root element, which is usually the element name. For example, in DATUM["WGS 84", …] this is "WGS 84". If there are no children then this method returns the keyword, which is usually an enumeration value (for example "NORTH"}).

Overrides:

toString in class Object