Package org.locationtech.spatial4j.io
Class WKTReader
- java.lang.Object
-
- org.locationtech.spatial4j.io.WKTReader
-
- All Implemented Interfaces:
ShapeIO
,ShapeReader
- Direct Known Subclasses:
JtsWKTReaderShapeParser
,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
- POLYGON
- MULTIPOLYGON
- GEOMETRYCOLLECTION
- BUFFER (non-standard Spatial4j operation)
parse___Shape
methods further describe these shapes, or youMost users of this class will call just one method:
parse(String)
, orparseIfSupported(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 delegatingnewState(String)
.Note, instances of this base class are threadsafe.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
WKTReader.State
The parse state.
-
Field Summary
Fields Modifier and Type Field Description protected SpatialContext
ctx
protected ShapeFactory
shapeFactory
-
Constructor Summary
Constructors Constructor Description WKTReader(SpatialContext ctx, SpatialContextFactory factory)
This constructor is required bySpatialContextFactory.makeFormats(SpatialContext)
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description String
getFormatName()
protected WKTReader.State
newState(String wktString)
(internal) Creates a new State with the given String.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
parseMulitPolygonShape(WKTReader.State state)
Parses a MULTIPOLYGON shape from the raw string.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
parsePolygonShape(WKTReader.State state)
Parses a POLYGON 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 asshapeType
already consumed viaWKTReader.State.nextWord()
.protected ShapeFactory.PointsBuilder
point(WKTReader.State state, ShapeFactory.PointsBuilder pointsBuilder)
Reads a raw Point (AKA Coordinate) from the current position.protected <B extends ShapeFactory.PointsBuilder>
BpointList(WKTReader.State state, B pointsBuilder)
Reads a list of Points (AKA CoordinateSequence) from the current position.protected ShapeFactory.PolygonBuilder
polygon(WKTReader.State state, ShapeFactory.PolygonBuilder polygonBuilder)
Reads a polygonShape
read(Reader reader)
Read aShape
from the reader.Shape
read(Object value)
Shape
readIfSupported(Object value)
protected Shape
shape(WKTReader.State state)
Reads a shape from the current position, starting with the name of the shape.
-
-
-
Field Detail
-
ctx
protected final SpatialContext ctx
-
shapeFactory
protected final ShapeFactory shapeFactory
-
-
Constructor Detail
-
WKTReader
public WKTReader(SpatialContext ctx, SpatialContextFactory factory)
This constructor is required bySpatialContextFactory.makeFormats(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 definitionInvalidShapeException
-
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 aParseException
.- 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 definitionInvalidShapeException
-
newState
protected WKTReader.State newState(String wktString)
(internal) Creates a new State with the given String. It's only called byparseIfSupported(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 asshapeType
already consumed viaWKTReader.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
-
parsePointShape
protected Shape parsePointShape(WKTReader.State state) throws ParseException
Parses a POINT shape from the raw string.'(' coordinate ')'
- Throws:
ParseException
- See Also:
point(State, ShapeFactory.PointsBuilder)
-
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(State, ShapeFactory.PointsBuilder)
-
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(State, ShapeFactory.PointsBuilder)
-
parseMultiLineStringShape
protected Shape parseMultiLineStringShape(WKTReader.State state) throws ParseException
Parses a MULTILINESTRING shape from the raw string -- a collection of line strings.'(' coordinateSequence (',' coordinateSequence )* ')'
-
parsePolygonShape
protected Shape parsePolygonShape(WKTReader.State state) throws ParseException
Parses a POLYGON shape from the raw string. It might return aRectangle
if the polygon is one.coordinateSequenceList
- Throws:
ParseException
-
parseMulitPolygonShape
protected Shape parseMulitPolygonShape(WKTReader.State state) throws ParseException
Parses a MULTIPOLYGON shape from the raw string.'(' polygon (',' polygon )* ')'
- Throws:
ParseException
-
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 callsparseShapeByType(org.locationtech.spatial4j.io.WKTReader.State, String)
and throws an exception if the shape wasn't supported.- Throws:
ParseException
-
pointList
protected <B extends ShapeFactory.PointsBuilder> B pointList(WKTReader.State state, B pointsBuilder) throws ParseException
Reads a list of Points (AKA CoordinateSequence) from the current position.'(' coordinate (',' coordinate )* ')'
- Throws:
ParseException
- See Also:
point(State, ShapeFactory.PointsBuilder)
-
point
protected ShapeFactory.PointsBuilder point(WKTReader.State state, ShapeFactory.PointsBuilder pointsBuilder) 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
-
polygon
protected ShapeFactory.PolygonBuilder polygon(WKTReader.State state, ShapeFactory.PolygonBuilder polygonBuilder) throws ParseException
Reads a polygon- Throws:
ParseException
-
getFormatName
public String getFormatName()
- Specified by:
getFormatName
in interfaceShapeIO
- Returns:
- the format name
-
read
public Shape read(Reader reader) throws IOException, ParseException
Description copied from interface:ShapeReader
Read aShape
from the reader.- Specified by:
read
in interfaceShapeReader
- 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 interfaceShapeReader
- 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 interfaceShapeReader
- 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
-
-