com.spatial4j.core.io

Class WKTReader

java.lang.Object

com.spatial4j.core.io.WKTReader

All Implemented Interfaces:

ShapeIO, ShapeReader

Direct Known Subclasses:

JtsWKTReader, WktShapeParser

public class WKTReader
extends 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
• 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	WKTReader.State The parse state.

Field Summary

Fields

Modifier and Type	Field and Description
protected SpatialContext	ctx

Fields inherited from interface com.spatial4j.core.io.ShapeIO

GeoJSON, LEGACY, POLY, WKT

Constructor Summary

Constructors

Constructor and Description
WKTReader(SpatialContext ctx, SpatialContextFactory factory) This constructor is required by com.spatial4j.core.context.SpatialContextFactory#makeWktShapeParser(com.spatial4j.core.context.SpatialContext) .

Method Summary

Modifier and Type	Method and Description
String	getFormatName()
protected WKTReader.State	newState(String wktString) (internal) Creates a new State with the given String.
protected double	normDist(double v) Called to normalize a value that isn't X or Y.
Shape	parse(String wktString) Parses the wktString, returning the defined Shape.
protected Shape	parseBufferShape(WKTReader.State state) Parses the BUFFER operation applied to a parsed shape.
protected Shape	parseEnvelopeShape(WKTReader.State state) Parses an ENVELOPE (aka Rectangle) shape from the raw string.
protected Shape	parseGeometryCollectionShape(WKTReader.State state) Parses a GEOMETRYCOLLECTION shape from the raw string.
Shape	parseIfSupported(String wktString) Parses the wktString, returning the defined Shape.
protected Shape	parseLineStringShape(WKTReader.State state) Parses a LINESTRING shape from the raw string -- an ordered sequence of points.
protected Shape	parseMultiLineStringShape(WKTReader.State state) Parses a MULTILINESTRING shape from the raw string -- a collection of line strings.
protected Shape	parseMultiPointShape(WKTReader.State state) Parses a MULTIPOINT shape from the raw string -- a collection of points.
protected Shape	parsePointShape(WKTReader.State state) Parses a POINT shape from the raw string.
protected Shape	parseShapeByType(WKTReader.State state, String shapeType) (internal) Parses the remainder of a shape definition following the shape's name given as shapeType already consumed via WKTReader.State.nextWord().
protected Point	point(WKTReader.State state) Reads a raw Point (AKA Coordinate) from the current position.
protected List<Point>	pointList(WKTReader.State state) Reads a list of Points (AKA CoordinateSequence) from the current position.
Shape	read(Object value)
Shape	read(Reader reader) Read a Shape from the reader.
Shape	readIfSupported(Object value)
protected Shape	shape(WKTReader.State state) Reads a shape from the current position, starting with the name of the shape.

Methods inherited from class java.lang.Object

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

Field Detail

ctx

protected final SpatialContext ctx

Constructor Detail

WKTReader

public WKTReader(SpatialContext ctx,
                 SpatialContextFactory factory)

This constructor is required by com.spatial4j.core.context.SpatialContextFactory#makeWktShapeParser(com.spatial4j.core.context.SpatialContext) .

Method Detail

parse

public Shape parse(String wktString)
            throws ParseException,
                   InvalidShapeException

Parses the wktString, returning the defined Shape.

Returns:

Non-null Shape defined in the String

Throws:

ParseException - Thrown if there is an error in the Shape definition

InvalidShapeException

parseIfSupported

public Shape parseIfSupported(String wktString)
                       throws 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:

ParseException - Thrown if there is an error in the Shape definition

InvalidShapeException

newState

protected WKTReader.State newState(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,
                                 String shapeType)
                          throws 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:

state -

shapeType - Non-Null string; could have mixed case. The first character is a letter.

Returns:

The shape or null if not supported / unknown.

Throws:

ParseException

parseBufferShape

protected Shape parseBufferShape(WKTReader.State state)
                          throws ParseException

Parses the BUFFER operation applied to a parsed shape.

   '(' shape ',' number ')'
 

Whereas 'number' is the distance to buffer the shape by.

Throws:

ParseException

normDist

protected double normDist(double v)

Called to normalize a value that isn't X or Y. X & Y or normalized via SpatialContext.normX(double) & normY.

parsePointShape

protected Shape parsePointShape(WKTReader.State state)
                         throws ParseException

Parses a POINT shape from the raw string.

   '(' coordinate ')'
 

Throws:

ParseException

See Also:

point(WKTReader.State)

parseMultiPointShape

protected Shape parseMultiPointShape(WKTReader.State state)
                              throws ParseException

Parses a MULTIPOINT shape from the raw string -- a collection of points.

   '(' coordinate (',' coordinate )* ')'
 

Furthermore, coordinate can optionally be wrapped in parenthesis.

Throws:

ParseException

See Also:

point(WKTReader.State)

parseEnvelopeShape

protected Shape parseEnvelopeShape(WKTReader.State state)
                            throws 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:

ParseException

parseLineStringShape

protected Shape parseLineStringShape(WKTReader.State state)
                              throws ParseException

Parses a LINESTRING shape from the raw string -- an ordered sequence of points.

 coordinateSequence
 

Throws:

ParseException

See Also:

pointList(WKTReader.State)

parseMultiLineStringShape

protected Shape parseMultiLineStringShape(WKTReader.State state)
                                   throws ParseException

Parses a MULTILINESTRING shape from the raw string -- a collection of line strings.

   '(' coordinateSequence (',' coordinateSequence )* ')'
 

Throws:

ParseException

See Also:

parseLineStringShape(com.spatial4j.core.io.WKTReader.State)

parseGeometryCollectionShape

protected Shape parseGeometryCollectionShape(WKTReader.State state)
                                      throws ParseException

Parses a GEOMETRYCOLLECTION shape from the raw string.

   '(' shape (',' shape )* ')'
 

Throws:

ParseException

shape

protected Shape shape(WKTReader.State state)
               throws ParseException

Reads a shape from the current position, starting with the name of the shape. It calls parseShapeByType(com.spatial4j.core.io.WKTReader.State, String) and throws an exception if the shape wasn't supported.

Throws:

ParseException

pointList

protected List<Point> pointList(WKTReader.State state)
                         throws ParseException

Reads a list of Points (AKA CoordinateSequence) from the current position.

   '(' coordinate (',' coordinate )* ')'
 

Throws:

ParseException

See Also:

point(WKTReader.State)

point

protected Point point(WKTReader.State state)
               throws ParseException

Reads a raw Point (AKA Coordinate) from the current position. Only the first 2 numbers are used. The values are normalized.

   number number number*
 

Throws:

ParseException

getFormatName

public String getFormatName()

Specified by:

getFormatName in interface ShapeIO

Returns:

the format name

read

public Shape read(Reader reader)
           throws IOException,
                  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:

IOException

ParseException

read

public Shape read(Object value)
           throws IOException,
                  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:

IOException

ParseException

InvalidShapeException

readIfSupported

public Shape readIfSupported(Object value)
                      throws InvalidShapeException

Specified by:

readIfSupported in interface ShapeReader

Parameters:

value - -- the input value, could be a String or other object

Returns:

a shape or null, if the input was un readable. This will throw InvalidShapeException when we could read a shape, but it was invalid

Throws:

InvalidShapeException