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
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 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 -
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionWKTReader
(SpatialContext ctx, SpatialContextFactory factory) This constructor is required bySpatialContextFactory.makeFormats(SpatialContext)
. -
Method Summary
Modifier and TypeMethodDescriptionprotected WKTReader.State
(internal) Creates a new State with the given String.Parses the wktString, returning the defined Shape.protected Shape
parseBufferShape
(WKTReader.State state) Parses the BUFFER operation applied to a parsed shape.protected Shape
Parses an ENVELOPE (aka Rectangle) shape from the raw string.protected Shape
Parses a GEOMETRYCOLLECTION shape from the raw string.parseIfSupported
(String wktString) Parses the wktString, returning the defined Shape.protected Shape
Parses a LINESTRING shape from the raw string -- an ordered sequence of points.protected Shape
Parses a MULTIPOLYGON shape from the raw string.protected Shape
Parses a MULTILINESTRING shape from the raw string -- a collection of line strings.protected Shape
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 polygonRead aShape
from the reader.readIfSupported
(Object value) (package private) static String
readString
(Reader reader) protected Shape
shape
(WKTReader.State state) Reads a shape from the current position, starting with the name of the shape.
-
Field Details
-
ctx
-
shapeFactory
-
-
Constructor Details
-
WKTReader
This constructor is required bySpatialContextFactory.makeFormats(SpatialContext)
.
-
-
Method Details
-
parse
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
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
(internal) Creates a new State with the given String. It's only called byparseIfSupported(String)
. This is an extension point for subclassing. -
parseShapeByType
(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:
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
Parses the BUFFER operation applied to a parsed shape.'(' shape ',' number ')'
Whereas 'number' is the distance to buffer the shape by.- Throws:
ParseException
-
parsePointShape
Parses a POINT shape from the raw string.'(' coordinate ')'
- Throws:
ParseException
- See Also:
-
parseMultiPointShape
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:
-
parseEnvelopeShape
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
Parses a LINESTRING shape from the raw string -- an ordered sequence of points.coordinateSequence
- Throws:
ParseException
- See Also:
-
parseMultiLineStringShape
Parses a MULTILINESTRING shape from the raw string -- a collection of line strings.'(' coordinateSequence (',' coordinateSequence )* ')'
- Throws:
ParseException
- See Also:
-
parsePolygonShape
Parses a POLYGON shape from the raw string. It might return aRectangle
if the polygon is one.coordinateSequenceList
- Throws:
ParseException
-
parseMulitPolygonShape
Parses a MULTIPOLYGON shape from the raw string.'(' polygon (',' polygon )* ')'
- Throws:
ParseException
-
parseGeometryCollectionShape
Parses a GEOMETRYCOLLECTION shape from the raw string.'(' shape (',' shape )* ')'
- Throws:
ParseException
-
shape
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
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
- Specified by:
getFormatName
in interfaceShapeIO
- Returns:
- the format name
-
readString
- Throws:
IOException
-
read
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
- 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
- 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
-