Package org.apache.sis.io.wkt
Class Element
java.lang.Object
org.apache.sis.io.wkt.Element
An element in a Well Know Text (WKT). An
Element
is made of String
,
Number
and other Element
. For example:
Each Element
object can contain an arbitrary number of other elements.
The result is a tree, which can be seen with toString()
for debugging purpose.
Elements can be pulled by their name and other children (numbers, dates, strings)
can be pulled in a first in, first out order.
Sharing repetitive information
Element
instances are mutable because AbstractParser
needs to remove elements from
the children
list as they are processed. If that parsing does not happen immediately,
then Element
content needs to be copied in a different structure (StoredTree
)
which is immutable and designed for reducing redundancies.- Since:
- 0.6
- Version:
- 1.1
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final Locale
The locale to be used for formatting an error message if the parsing fails, ornull
for the system default.private final boolean
true
if the keyword was not followed by a pair of brackets (e.g.(package private) final boolean
true
if this element has been reconstituted fromWKTFormat.fragments
.(package private) boolean
Whether this element is the root of a tree of WKT elements.final String
Keyword of the WKT element, for example"PrimeMeridian"
.private byte
Index of the keyword in the array given to thepullElement(int, String...)
method.private static final int
Kind of value expected in the element.(package private) final int
Index of the character where this element starts in the WKT string to parse.private static final int
Kind of value expected in the element.private static final String[]
Hard-coded list of elements in which to parse values as dates instead of numbers. -
Constructor Summary
ConstructorsConstructorDescriptionElement
(String keyword, LinkedList<Object> children, int offset, Locale errorLocale) Creates a new node for the given keyword and list of children.Element
(AbstractParser parser, String text, ParsePosition position) Constructs a newElement
by parsing the given WKT string starting at the given position.Constructs a root element as a modifiable wrapper around the given element. -
Method Summary
Modifier and TypeMethodDescription(package private) final void
Closes this element.private void
format
(StringBuilder buffer, int margin, String lineSeparator) Implementation oftoString()
to be invoked recursively.(package private) final Object[]
Returns a copy of children list, ornull
if thisElement
is an enumeration.(package private) final int
Returns the index of the keyword in the array given to thepullElement(int, String...)
method.(package private) final ParseException
illegalCS
(org.opengis.referencing.cs.CoordinateSystem cs) Returns aParseException
for an illegal coordinate system.boolean
isEmpty()
Returnstrue
if this element does not contains any remaining child.private ParseException
missingCharacter
(int c, int errorIndex, ParsePosition position) Returns an exception saying that a character is missing.(package private) final ParseException
missingComponent
(String key) Returns an exception saying that a sub-element is missing.(package private) final ParseException
missingOrUnknownComponent
(String expected) Returns aParseException
for a child keyword which is unknown.private int
Returns index of the character after the keyword in the WKT string to parse.(package private) final ParseException
parseFailed
(Exception cause) Returns aParseException
with the specified cause.Returns the next value (not a child element) without removing it.boolean
pullBoolean
(String key) Removes the nextBoolean
from the children and returns it.Removes the nextDate
from the children and returns it.double
pullDouble
(String key) Removes the nextNumber
from the children and returns it.pullElement
(int mode, String... keys) Removes the nextElement
of the given name from the children and returns it.int
pullInteger
(String key) Removes the nextNumber
from the children and returns it as an integer.pullObject
(String key) Removes the nextObject
from the children and returns it.<T> T
pullOptional
(Class<T> type) Removes the next object of the given type from the children and returns it, if presents.pullString
(String key) Removes the nextString
from the children and returns it.pullVoidElement
(String key) Removes and returns the nextElement
with no bracket.private static int
regionMatches
(String text, int index, String word) Increments the givenindex
if and only if the word at that position is the given word, ignoring case.toString()
Formats thisElement
as a tree.private ParseException
unparsableString
(String text, ParsePosition position) Returns aParseException
with a "Unparsable string" message.
-
Field Details
-
NUMERIC
private static final int NUMERICKind of value expected in the element. Value 0 means "not yet determined".- See Also:
-
TEMPORAL
private static final int TEMPORALKind of value expected in the element. Value 0 means "not yet determined".- See Also:
-
TIME_KEYWORDS
Hard-coded list of elements in which to parse values as dates instead of numbers. We may try to find a more generic approach in a future version. -
offset
final int offsetIndex of the character where this element starts in the WKT string to parse.- See Also:
-
keywordIndex
private byte keywordIndexIndex of the keyword in the array given to thepullElement(int, String...)
method. This is a workaround for the lack of multiple return values in Java.- See Also:
-
keyword
Keyword of the WKT element, for example"PrimeMeridian"
. Nevernull
. -
isEnumeration
private final boolean isEnumerationtrue
if the keyword was not followed by a pair of brackets (e.g. "north"). Iftrue
, thenchildren
shall be an empty list. -
isFragment
final boolean isFragmenttrue
if this element has been reconstituted fromWKTFormat.fragments
. In such case, alloffset
values are identical. -
isRoot
boolean isRootWhether this element is the root of a tree of WKT elements. This field is not used by thisElement
class. It is provided forWKTDictionary
convenience. -
children
An ordered sequence ofString
s,Number
s and otherElement
s. Access to this collection should be done using the iterator, not by random access. Parsing will remove elements (in any order) from this list as they are consumed.- See Also:
-
errorLocale
The locale to be used for formatting an error message if the parsing fails, ornull
for the system default. This is not the locale for parting number or date values.Design note: the same reference is duplicated in everyElement
instances. We nevertheless copy it as a convenience for avoiding to make this argument appears in thepullFoo(…)
methods.
-
-
Constructor Details
-
Element
Element(Element singleton) Constructs a root element as a modifiable wrapper around the given element. This wrapper is a convenience for branching on different codes depending on the keyword value. For example:- Parameters:
singleton
- the only child for this root.- See Also:
-
Element
Element(String keyword, LinkedList<Object> children, int offset, Locale errorLocale) Creates a new node for the given keyword and list of children. This is used byStoredTree
for recreating a tree ofElement
s from a previously saved snapshot.- Parameters:
keyword
- keyword of the WKT element, e.g."PrimeMeridian"
. Shall not benull
.children
- children of this element, ornull
if this element is an enumeration.offset
- index of the character where this element started in the WKT string. If negative, actual offset is~offset
andisFragment
is set totrue
.
-
Element
Element(AbstractParser parser, String text, ParsePosition position) throws ParseException Constructs a newElement
by parsing the given WKT string starting at the given position.- Parameters:
parser
- information about symbols (such as brackets) and formats to use.text
- the Well-Known Text (WKT) to parse.position
- on input, the position where to start parsing from. On output, the first character after the separator.- Throws:
ParseException
- if quotes, brackets or parenthesis are not balanced, or a date/number cannot be parsed, or a referenced WKT fragment (e.g."$FOO"
) cannot be found.
-
-
Method Details
-
regionMatches
Increments the givenindex
if and only if the word at that position is the given word, ignoring case. Otherwise returns the index unchanged. -
parseFailed
Returns aParseException
with the specified cause. A localized string"Error in <
will be prepend to the message. The error index will be the starting index of thiskeyword
>"Element
.- Parameters:
cause
- the cause of the failure, ornull
if none.- Returns:
- the exception to be thrown.
-
unparsableString
Returns aParseException
with a "Unparsable string" message. The error message is built from the specified string starting at the specified position. TheParsePosition.getErrorIndex()
property must be accurate before this method is invoked. TheParsePosition.getIndex()
property will be set by this method.- Parameters:
text
- the unparsable string.position
- the position in the string.- Returns:
- an exception with a formatted error message.
-
missingCharacter
Returns an exception saying that a character is missing.- Parameters:
c
- the missing character.errorIndex
- the error position.position
- the position to update with the error index.
-
missingComponent
Returns an exception saying that a sub-element is missing.- Parameters:
key
- the name of the missing sub-element.
-
missingOrUnknownComponent
Returns aParseException
for a child keyword which is unknown.- Parameters:
expected
- keyword of a typical element. Used only if this element contains no child element.- Returns:
- the exception to be thrown.
-
illegalCS
Returns aParseException
for an illegal coordinate system.The given
cs
argument should never be null with Apache SIS implementation ofCSFactory
, but could be null with user supplied implementation. But it would be aCSFactory
contract violation, so the user would get aNullPointerException
later. For making easier to trace the cause, we throw here an exception with a similar error message.- Parameters:
cs
- the illegal coordinate system.- Returns:
- the exception to be thrown.
-
offsetAfterKeyword
private int offsetAfterKeyword()Returns index of the character after the keyword in the WKT string to parse. -
peekValue
Returns the next value (not a child element) without removing it.- Returns:
- the next value, or
null
if none.
-
pullDate
Removes the nextDate
from the children and returns it.- Parameters:
key
- the parameter name. Used for formatting an error message if no date is found.- Returns:
- the next
Date
among the children. - Throws:
ParseException
- if no more date is available.
-
pullDouble
Removes the nextNumber
from the children and returns it.- Parameters:
key
- the parameter name. Used for formatting an error message if no number is found.- Returns:
- the next
Number
among the children as adouble
. - Throws:
ParseException
- if no more number is available.
-
pullInteger
Removes the nextNumber
from the children and returns it as an integer.- Parameters:
key
- the parameter name. Used for formatting an error message if no number is found.- Returns:
- the next
Number
among the children as anint
. - Throws:
ParseException
- if no more number is available, or the number is not an integer.
-
pullBoolean
Removes the nextBoolean
from the children and returns it.- Parameters:
key
- the parameter name. Used for formatting an error message if no boolean is found.- Returns:
- the next
Boolean
among the children as aboolean
. - Throws:
ParseException
- if no more boolean is available.
-
pullString
Removes the nextString
from the children and returns it.- Parameters:
key
- the parameter name. Used for formatting an error message if no number is found.- Returns:
- the next
String
among the children. - Throws:
ParseException
- if no more string is available.
-
pullObject
Removes the nextObject
from the children and returns it.- Parameters:
key
- the parameter name. Used for formatting an error message if no number is found.- Returns:
- the next
Object
among the children (nevernull
). - Throws:
ParseException
- if no more object is available.
-
pullElement
Removes the nextElement
of the given name from the children and returns it. If the element was mandatory but is missing, then the first entry in the givenkeys
array will be taken as the name of the missing element to report in the exception message.The given
mode
argument can be one of the following constants:AbstractParser.MANDATORY
throw an exception if no matching element is found.AbstractParser.OPTIONAL
returnnull
if no matching element is found.AbstractParser.FIRST
returnnull
if the first element (ignoring all others) does not match.
- Parameters:
mode
-AbstractParser.FIRST
,AbstractParser.OPTIONAL
orAbstractParser.MANDATORY
.keys
- the element names (e.g."PrimeMeridian"
).- Returns:
- the next
Element
of the given names found among the children, ornull
if none. - Throws:
ParseException
- ifmode
isMANDATORY
and no element of the given names was found.
-
pullVoidElement
Removes and returns the nextElement
with no bracket. The key is used only for only for formatting an error message.- Parameters:
key
- the parameter name. Used only for formatting an error message.- Returns:
- the next
Element
among the children, with no bracket. - Throws:
ParseException
- if no more void element is available.
-
pullOptional
Removes the next object of the given type from the children and returns it, if presents.- Parameters:
type
- the object type.- Returns:
- the next object among the children, or
null
if none.
-
getChildren
Returns a copy of children list, ornull
if thisElement
is an enumeration. This method is used only for creating a snapshot of thisElement
inStoredTree
. The returned array may contain nestedElement
instances. -
isEmpty
public boolean isEmpty()Returnstrue
if this element does not contains any remaining child.- Returns:
true
if there are no children remaining.
-
getKeywordIndex
final int getKeywordIndex()Returns the index of the keyword in the array given to thepullElement(int, String...)
method. -
close
Closes this element. This method verifies that there are no unprocessed values (dates, numbers, booleans or strings), but ignores inner elements as required by ISO 19162. This method adds the keywords of ignored elements in theignoredElements
map as below:- Keys: keyword of ignored elements. Note that a key may be null.
- Values: keywords of all elements containing an element identified by the above-cited key. This list is used for helping the users to locate the ignored elements.
- Parameters:
ignoredElements
- the collection where to declare ignored elements.- Throws:
ParseException
- if the children list still contains some unprocessed values.
-
toString
Formats thisElement
as a tree. This method is used for debugging purpose only. -
format
Implementation oftoString()
to be invoked recursively.- Parameters:
buffer
- where to format.margin
- number of spaces to put in the left margin.
-