Package org.apache.sis.io.wkt

Class AbstractParser

java.lang.Object
org.apache.sis.io.wkt.AbstractParser
All Implemented Interfaces:
Parser
Direct Known Subclasses:
MathTransformParser
abstract class AbstractParser extends Object implements Parser
Parses Well Known Text (WKT). Parsers are the converse of Formatter. Like the latter, a parser is constructed with a given set of symbols. Parsers also need a set of factories to be used for instantiating the parsed objects.

In current version, parsers are not intended to be subclassed outside this package.

Parsers are not synchronized. It is recommended to create separate parser instances for each thread. If many threads access the same parser instance concurrently, it must be synchronized externally.

Since:
0.6
Version:
1.1

  • Field Details

    • FIRST

      static final int FIRST
      A mode for the Element.pullElement(int, String...) method meaning that only the first element should be checked. If the name of the first element does not match one of the specified names, then pullElement(…) returns null.
      See Also:

    • OPTIONAL

      static final int OPTIONAL
      A mode for the Element.pullElement(int, String...) method meaning that the requested element is optional but not necessarily first. If no element has a name matching one of the requested names, then pullElement(…) returns null.
      See Also:

    • MANDATORY

      static final int MANDATORY
      A mode for the Element.pullElement(int, String...) method meaning that an exception shall be thrown if no element has a name matching one of the requested names.
      See Also:

    • errorLocale

      final Locale errorLocale
      The locale for formatting error messages if parsing fails, or null for system default. This is not the locale for parsing number or date values. The locale for numbers and dates is contained in symbols.

    • symbols

      final Symbols symbols
      The symbols to use for parsing WKT.

    • exponentSymbol

      private final String exponentSymbol
      The symbol for scientific notation, or null if none. This is usually "E" (note the upper case), but could also be something like "×10^".

    • numberFormat

      private final NumberFormat numberFormat
      The object to use for parsing numbers.

    • dateFormat

      private DateFormat dateFormat
      The object to use for parsing dates, created when first needed.

    • unitFormat

      private UnitFormat unitFormat
      The object to use for parsing unit symbols, created when first needed.

    • fragments

      final Map<String,StoredTree> fragments
      Reference to the WKTFormat.fragments map, or an empty map if none. Shall be used in read-only mode; never write through this reference.
      See Also:

    • ignoredElements

      final Map<String,List<String>> ignoredElements
      Keyword of unknown elements. The ISO 19162 specification requires that we ignore unknown elements, but we will nevertheless report them as warnings. The meaning of this map is:
      • 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.
      Content of this map is not discarded immediately after parsing. It is kept for some time because Warnings will copy its content only when first needed.
      See Also:

    • warnings

      private Warnings warnings
      The warning (other than ignoredElements) that occurred during the parsing. Created when first needed and reset to null when a new parsing start. Warnings are reported when getAndClearWarnings(Object) is invoked.

  • Constructor Details

    • AbstractParser

      AbstractParser(Symbols symbols, Map<String,StoredTree> fragments, NumberFormat numberFormat, DateFormat dateFormat, UnitFormat unitFormat, Locale errorLocale)
      Constructs a parser using the specified set of symbols.
      Parameters:
      symbols - the set of symbols to use.
      fragments - reference to the WKTFormat.fragments map, or an empty map if none.
      numberFormat - the number format provided by WKTFormat, or null for a default format.
      dateFormat - the date format provided by WKTFormat, or null for a default format.
      unitFormat - the unit format provided by WKTFormat, or null for a default format.
      errorLocale - the locale for error messages (not for parsing), or null for the system default.

  • Method Details

    • getPublicFacade

      abstract String getPublicFacade()
      Returns the name of the class providing the publicly-accessible createFromWKT(String) method. This information is used for logging purposes only. Values can be:
      • "org.apache.sis.io.wkt.WKTFormat"
      • "org.apache.sis.referencing.factory.GeodeticObjectFactory"
      • "org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory"

    • getFacadeMethod

      String getFacadeMethod()
      Returns the name of the method invoked from getPublicFacade(). This information is used for logging purposes only. Another possible value is "parse".

    • log

      final void log(LogRecord record)
      Logs the given record for a warning that occurred during parsing. This is used when we cannot use the warning methods, or when the information is not worth to report as a warning.

    • createFromWKT

      public final Object createFromWKT(String wkt) throws org.opengis.util.FactoryException
      Creates the object from a WKT string and logs the warnings if any. This method is for implementation of createFromWKT(String) method in SIS factories only. Callers should ensure that wkt is non-null and non-empty (this method does not verify).
      Specified by:
      createFromWKT in interface Parser
      Parameters:
      wkt - object encoded in Well-Known Text format (version 1 or 2).
      Returns:
      the result of parsing the given text.
      Throws:
      org.opengis.util.FactoryException - if the object creation failed.
      See Also:

    • createFromWKT

      Object createFromWKT(String text, ParsePosition position) throws ParseException
      Parses a Well-Know Text from specified position as a geodetic object. Caller should invoke getAndClearWarnings(Object) in a finally block after this method and should decide what to do with remaining character at the end of the string.

      If this method is invoked from WKTFormat, then WKTFormat.clear() should be invoked before this method for making sure that no Warnings instance is referencing ignoredElements.

      Parameters:
      text - the Well-Known Text (WKT) to parse.
      position - index of the first character to parse (on input) or after last parsed character (on output).
      Returns:
      the parsed object.
      Throws:
      ParseException - if the string cannot be parsed.

    • endOfFragmentName

      static int endOfFragmentName(String text, int position)
      Returns the index after the end of the fragment name starting at the given index. Current implementation assumes that the fragment name is a Unicode identifier, except for the first character which is not required to be an identifier start.

    • textToTree

      final Element textToTree(String wkt, ParsePosition position) throws ParseException
      Parses the Well Know Text from specified position as a tree of Elements. This tree can be given to buildFromTree(Element) for producing a geodetic object.
      Parameters:
      wkt - the Well-Known Text to be parsed.
      position - before parsing, provides index of the first character to parse in the wkt string. After parsing completion, provides index after the last character parsed.
      Returns:
      the parsed object as a tree of Elements.
      Throws:
      ParseException - if the string cannot be parsed.
      See Also:

    • buildFromTree

      abstract Object buildFromTree(Element element) throws ParseException
      Parses the next element in the specified Well Know Text (WKT) tree. Subclasses will typically get the name of the first element and delegate to a specialized method such as parseAxis(…), parseEllipsoid(…), parseTimeDatum(…), etc.

      Callers should clear ignoredElements before to invoke this method. Cleaning warnings can be done for safety but should not be necessary.

      Parameters:
      element - the element to be parsed.
      Returns:
      the parsed object.
      Throws:
      ParseException - if the element cannot be parsed.

    • parseNumber

      final Number parseNumber(String text, ParsePosition position)
      Parses the number at the given position. This is a helper method for Element only.

    • parseDate

      final Date parseDate(String text, ParsePosition position)
      Parses the date at the given position. This is a helper method for Element only.

      The WKT 2 format expects dates formatted according the ISO 9075-2 standard.

    • parseUnit

      final javax.measure.Unit<?> parseUnit(String text) throws javax.measure.format.ParserException
      Parses the given unit name or symbol. Contrarily to other parseFoo() methods, this method has no ParsePosition and expects the given string to be the full unit symbol.
      Throws:
      javax.measure.format.ParserException

    • warning

      final void warning(Element parent, Element element, org.opengis.util.InternationalString message, Exception ex)
      Reports a non-fatal warning that occurred while parsing a WKT.
      Parameters:
      parent - the parent element, or null if unknown.
      element - the element that we cannot parse, or null if unknown.
      message - the message. Can be null only if ex is non-null.
      ex - the non-fatal exception that occurred while parsing the element, or null.

    • warning

      final void warning(Element parent, String element, org.opengis.util.InternationalString message, Exception ex)
      Reports a non-fatal warning that occurred while parsing a WKT.
      Parameters:
      parent - the parent element, or null if unknown.
      element - the name of the element that we cannot parse, or null if unknown.
      message - the message. Can be null only if ex is non-null.
      ex - the non-fatal exception that occurred while parsing the element, or null.

    • getAndClearWarnings

      final Warnings getAndClearWarnings(Object result)
      Returns the warnings, or null if none. This method clears the warnings after the call.

      The returned object is valid only until a new parsing starts. If a longer lifetime is desired, then the caller must invokes Warnings.publish().

      Parameters:
      result - the object that resulted from the parsing operation, or null.
      Returns:
      the warnings, or null if none.