Package org.apache.sis.io.wkt

Class Element

java.lang.Object
org.apache.sis.io.wkt.Element
final class Element extends Object
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 Details

    • NUMERIC

      private static final int NUMERIC
      Kind of value expected in the element. Value 0 means "not yet determined".
      See Also:

    • TEMPORAL

      private static final int TEMPORAL
      Kind of value expected in the element. Value 0 means "not yet determined".
      See Also:

    • TIME_KEYWORDS

      private static final String[] 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 offset
      Index of the character where this element starts in the WKT string to parse.
      See Also:

    • keywordIndex

      private byte keywordIndex
      Index of the keyword in the array given to the pullElement(int, String...) method. This is a workaround for the lack of multiple return values in Java.
      See Also:

    • keyword

      public final String keyword
      Keyword of the WKT element, for example "PrimeMeridian". Never null.

    • isEnumeration

      private final boolean isEnumeration
      true if the keyword was not followed by a pair of brackets (e.g. "north"). If true, then children shall be an empty list.

    • isFragment

      final boolean isFragment
      true if this element has been reconstituted from WKTFormat.fragments. In such case, all offset values are identical.

    • isRoot

      boolean isRoot
      Whether this element is the root of a tree of WKT elements. This field is not used by this Element class. It is provided for WKTDictionary convenience.

    • children

      private final List<Object> children
      An ordered sequence of Strings, Numbers and other Elements. 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

      private final Locale errorLocale
      The locale to be used for formatting an error message if the parsing fails, or null for the system default. This is not the locale for parting number or date values.
      Design note: the same reference is duplicated in every Element instances. We nevertheless copy it as a convenience for avoiding to make this argument appears in the pullFoo(…) 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 by StoredTree for recreating a tree of Elements from a previously saved snapshot.
      Parameters:
      keyword - keyword of the WKT element, e.g. "PrimeMeridian". Shall not be null.
      children - children of this element, or null 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 and isFragment is set to true.

    • Element

      Element(AbstractParser parser, String text, ParsePosition position) throws ParseException
      Constructs a new Element 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

      private static int regionMatches(String text, int index, String word)
      Increments the given index if and only if the word at that position is the given word, ignoring case. Otherwise returns the index unchanged.

    • parseFailed

      final ParseException parseFailed(Exception cause)
      Returns a ParseException with the specified cause. A localized string "Error in <keyword>" will be prepend to the message. The error index will be the starting index of this Element.
      Parameters:
      cause - the cause of the failure, or null if none.
      Returns:
      the exception to be thrown.

    • unparsableString

      private ParseException unparsableString(String text, ParsePosition position)
      Returns a ParseException with a "Unparsable string" message. The error message is built from the specified string starting at the specified position. The ParsePosition.getErrorIndex() property must be accurate before this method is invoked. The ParsePosition.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

      private ParseException missingCharacter(int c, int errorIndex, ParsePosition position)
      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

      final ParseException missingComponent(String key)
      Returns an exception saying that a sub-element is missing.
      Parameters:
      key - the name of the missing sub-element.

    • missingOrUnknownComponent

      final ParseException missingOrUnknownComponent(String expected)
      Returns a ParseException 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

      final ParseException illegalCS(org.opengis.referencing.cs.CoordinateSystem cs)
      Returns a ParseException for an illegal coordinate system.

      The given cs argument should never be null with Apache SIS implementation of CSFactory, but could be null with user supplied implementation. But it would be a CSFactory contract violation, so the user would get a NullPointerException 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

      public Object peekValue()
      Returns the next value (not a child element) without removing it.
      Returns:
      the next value, or null if none.

    • pullDate

      public Date pullDate(String key) throws ParseException
      Removes the next Date 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

      public double pullDouble(String key) throws ParseException
      Removes the next Number 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 a double.
      Throws:
      ParseException - if no more number is available.

    • pullInteger

      public int pullInteger(String key) throws ParseException
      Removes the next Number 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 an int.
      Throws:
      ParseException - if no more number is available, or the number is not an integer.

    • pullBoolean

      public boolean pullBoolean(String key) throws ParseException
      Removes the next Boolean 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 a boolean.
      Throws:
      ParseException - if no more boolean is available.

    • pullString

      public String pullString(String key) throws ParseException
      Removes the next String 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

      public Object pullObject(String key) throws ParseException
      Removes the next Object 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 (never null).
      Throws:
      ParseException - if no more object is available.

    • pullElement

      public Element pullElement(int mode, String... keys) throws ParseException
      Removes the next Element of the given name from the children and returns it. If the element was mandatory but is missing, then the first entry in the given keys 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:

      Parameters:
      mode - AbstractParser.FIRST, AbstractParser.OPTIONAL or AbstractParser.MANDATORY.
      keys - the element names (e.g. "PrimeMeridian").
      Returns:
      the next Element of the given names found among the children, or null if none.
      Throws:
      ParseException - if mode is MANDATORY and no element of the given names was found.

    • pullVoidElement

      public Element pullVoidElement(String key) throws ParseException
      Removes and returns the next Element 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

      public <T> T pullOptional(Class<T> type)
      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

      final Object[] getChildren()
      Returns a copy of children list, or null if this Element is an enumeration. This method is used only for creating a snapshot of this Element in StoredTree. The returned array may contain nested Element instances.

    • isEmpty

      public boolean isEmpty()
      Returns true 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 the pullElement(int, String...) method.

    • close

      final void close(Map<String,List<String>> ignoredElements) throws ParseException
      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 the ignoredElements 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

      public String toString()
      Formats this Element as a tree. This method is used for debugging purpose only.
      Overrides:
      toString in class Object

    • format

      @Debug private void format(StringBuilder buffer, int margin, String lineSeparator)
      Implementation of toString() to be invoked recursively.
      Parameters:
      buffer - where to format.
      margin - number of spaces to put in the left margin.