Class WKTReader

  • All Implemented Interfaces:
    ShapeIO, ShapeReader
    Direct Known Subclasses:
    JtsWKTReaderShapeParser, WktShapeParser

    public class WKTReader
    extends java.lang.Object
    implements ShapeReader
    An extensible parser for Well Known Text (WKT). The shapes supported by this class are:
    • POINT
    • MULTIPOINT
    • ENVELOPE (strictly isn't WKT but is defined by OGC's Common Query Language (CQL))
    • LINESTRING
    • MULTILINESTRING
    • POLYGON
    • MULTIPOLYGON
    • GEOMETRYCOLLECTION
    • BUFFER (non-standard Spatial4j operation)
    'EMPTY' is supported. Specifying 'Z', 'M', or any other dimensionality in the WKT is effectively ignored. Thus, you can specify any number of numbers in the coordinate points but only the first two take effect. The javadocs for the parse___Shape methods further describe these shapes, or you

    Most users of this class will call just one method: parse(String), or parseIfSupported(String) to not fail if it isn't parse-able.

    To support more shapes, extend this class and override parseShapeByType(WKTReader.State, String). It's also possible to delegate to a WKTParser by also delegating newState(String).

    Note, instances of this base class are threadsafe.

    • Method Detail

      • parse

        public Shape parse​(java.lang.String wktString)
                    throws java.text.ParseException,
                           InvalidShapeException
        Parses the wktString, returning the defined Shape.
        Returns:
        Non-null Shape defined in the String
        Throws:
        java.text.ParseException - Thrown if there is an error in the Shape definition
        InvalidShapeException
      • parseIfSupported

        public Shape parseIfSupported​(java.lang.String wktString)
                               throws java.text.ParseException,
                                      InvalidShapeException
        Parses the wktString, returning the defined Shape. If it can't because the shape name is unknown or an empty or blank string was passed, then it returns null. If the WKT starts with a supported shape but contains an inner unsupported shape then it will result in a ParseException.
        Parameters:
        wktString - non-null, can be empty or have surrounding whitespace
        Returns:
        Shape, null if unknown / unsupported shape.
        Throws:
        java.text.ParseException - Thrown if there is an error in the Shape definition
        InvalidShapeException
      • newState

        protected WKTReader.State newState​(java.lang.String wktString)
        (internal) Creates a new State with the given String. It's only called by parseIfSupported(String). This is an extension point for subclassing.
      • parseShapeByType

        protected Shape parseShapeByType​(WKTReader.State state,
                                         java.lang.String shapeType)
                                  throws java.text.ParseException
        (internal) Parses the remainder of a shape definition following the shape's name given as shapeType already consumed via WKTReader.State.nextWord(). If it's able to parse the shape, WKTReader.State.offset should be advanced beyond it (e.g. to the ',' or ')' or EOF in general). The default implementation checks the name against some predefined names and calls corresponding parse methods to handle the rest. Overriding this method is an excellent extension point for additional shape types. Or, use this class by delegation to this method.

        When writing a parse method that reacts to a specific shape type, remember to handle the dimension and EMPTY token via WKTReader.State.nextIfEmptyAndSkipZM().

        Parameters:
        shapeType - Non-Null string; could have mixed case. The first character is a letter.
        Returns:
        The shape or null if not supported / unknown.
        Throws:
        java.text.ParseException
      • parseBufferShape

        protected Shape parseBufferShape​(WKTReader.State state)
                                  throws java.text.ParseException
        Parses the BUFFER operation applied to a parsed shape.
           '(' shape ',' number ')'
         
        Whereas 'number' is the distance to buffer the shape by.
        Throws:
        java.text.ParseException
      • parseMultiPointShape

        protected Shape parseMultiPointShape​(WKTReader.State state)
                                      throws java.text.ParseException
        Parses a MULTIPOINT shape from the raw string -- a collection of points.
           '(' coordinate (',' coordinate )* ')'
         
        Furthermore, coordinate can optionally be wrapped in parenthesis.
        Throws:
        java.text.ParseException
        See Also:
        point(State, ShapeFactory.PointsBuilder)
      • parseEnvelopeShape

        protected Shape parseEnvelopeShape​(WKTReader.State state)
                                    throws java.text.ParseException
        Parses an ENVELOPE (aka Rectangle) shape from the raw string. The values are normalized.

        Source: OGC "Catalogue Services Specification", the "CQL" (Common Query Language) sub-spec. Note the inconsistent order of the min & max values between x & y!

           '(' x1 ',' x2 ',' y2 ',' y1 ')'
         
        Throws:
        java.text.ParseException
      • parsePolygonShape

        protected Shape parsePolygonShape​(WKTReader.State state)
                                   throws java.text.ParseException
        Parses a POLYGON shape from the raw string. It might return a Rectangle if the polygon is one.
         coordinateSequenceList
         
        Throws:
        java.text.ParseException
      • parseMulitPolygonShape

        protected Shape parseMulitPolygonShape​(WKTReader.State state)
                                        throws java.text.ParseException
        Parses a MULTIPOLYGON shape from the raw string.
           '(' polygon (',' polygon )* ')'
         
        Throws:
        java.text.ParseException
      • parseGeometryCollectionShape

        protected Shape parseGeometryCollectionShape​(WKTReader.State state)
                                              throws java.text.ParseException
        Parses a GEOMETRYCOLLECTION shape from the raw string.
           '(' shape (',' shape )* ')'
         
        Throws:
        java.text.ParseException
      • getFormatName

        public java.lang.String getFormatName()
        Specified by:
        getFormatName in interface ShapeIO
        Returns:
        the format name
      • readString

        static java.lang.String readString​(java.io.Reader reader)
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • read

        public Shape read​(java.io.Reader reader)
                   throws java.io.IOException,
                          java.text.ParseException
        Description copied from interface: ShapeReader
        Read a Shape from the reader.
        Specified by:
        read in interface ShapeReader
        Parameters:
        reader - -- the input. Note, it will not be closed by this function
        Returns:
        a valid Shape (never null)
        Throws:
        java.io.IOException
        java.text.ParseException
      • read

        public Shape read​(java.lang.Object value)
                   throws java.io.IOException,
                          java.text.ParseException,
                          InvalidShapeException
        Specified by:
        read in interface ShapeReader
        Parameters:
        value - -- the input value, could be a String or other object
        Returns:
        a shape valid shape (not null)
        Throws:
        java.io.IOException
        java.text.ParseException
        InvalidShapeException