Skip to content

Commit

Permalink
Enhance javadocs of ShapeFactory impacted code.
Browse files Browse the repository at this point in the history
  • Loading branch information
@dsmiley
dsmiley committed Jan 28, 2016
1 parent 514c50d commit f907f63
Show file tree
Hide file tree
Showing 3 changed files with 39 additions and 38 deletions.
16 changes: 14 additions & 2 deletions src/main/java/com/spatial4j/core/context/SpatialContext.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,13 @@
import com.spatial4j.core.io.WKTReader;
import com.spatial4j.core.shape.*;
import com.spatial4j.core.shape.impl.RectangleImpl;
import com.spatial4j.core.shape.impl.ShapeFactoryImpl;

import java.text.ParseException;
import java.util.List;

/**
* This is a facade to most of Spatial4j, holding things like {@link DistanceCalculator},
* {@link ShapeFactoryImpl},
* {@link ShapeFactory},
* {@link com.spatial4j.core.io.ShapeIO}.
* <p/>
* If you want a typical geodetic context, just reference {@link #GEO}. Otherwise,
Expand Down Expand Up @@ -149,6 +148,7 @@ public Rectangle getWorldBounds() {

/** If true then {@link #normX(double)} will wrap longitudes outside of the standard
* geodetic boundary into it. Example: 181 will become -179. */
@Deprecated
public boolean isNormWrapLongitude() {
return shapeFactory.isNormWrapLongitude();
}
Expand All @@ -162,32 +162,38 @@ public boolean isGeo() {

/** Normalize the 'x' dimension. Might reduce precision or wrap it to be within the bounds. This
* is called by {@link com.spatial4j.core.io.WKTReader} before creating a shape. */
@Deprecated
public double normX(double x) {
return shapeFactory.normX(x);
}

/** Normalize the 'y' dimension. Might reduce precision or wrap it to be within the bounds. This
* is called by {@link com.spatial4j.core.io.WKTReader} before creating a shape. */
@Deprecated
public double normY(double y) { return shapeFactory.normY(y); }

/** Ensure fits in {@link #getWorldBounds()}. It's called by any shape factory method that
* gets an 'x' dimension. */
@Deprecated
public void verifyX(double x) {
shapeFactory.verifyX(x);
}

/** Ensure fits in {@link #getWorldBounds()}. It's called by any shape factory method that
* gets a 'y' dimension. */
@Deprecated
public void verifyY(double y) {
shapeFactory.verifyY(y);
}

/** Construct a point. */
@Deprecated
public Point makePoint(double x, double y) {
return shapeFactory.pointXY(x, y);
}

/** Construct a rectangle. */
@Deprecated
public Rectangle makeRectangle(Point lowerLeft, Point upperRight) {
return shapeFactory.rect(lowerLeft, upperRight);
}
Expand All @@ -197,34 +203,40 @@ public Rectangle makeRectangle(Point lowerLeft, Point upperRight) {
* then potentially adjust its sign to ensure the rectangle does not cross the
* dateline.
*/
@Deprecated
public Rectangle makeRectangle(double minX, double maxX, double minY, double maxY) {
return shapeFactory.rect(minX, maxX, minY, maxY);
}

/** Construct a circle. The units of "distance" should be the same as x & y. */
@Deprecated
public Circle makeCircle(double x, double y, double distance) {
return shapeFactory.circle(x, y, distance);
}

/** Construct a circle. The units of "distance" should be the same as x & y. */
@Deprecated
public Circle makeCircle(Point point, double distance) {
return shapeFactory.circle(point, distance);
}

/** Constructs a line string. It's an ordered sequence of connected vertexes. There
* is no official shape/interface for it yet so we just return Shape. */
@Deprecated
public Shape makeLineString(List<Point> points) {
return shapeFactory.lineString(points, 0);
}

/** Constructs a buffered line string. It's an ordered sequence of connected vertexes,
* with a buffer distance along the line in all directions. There
* is no official shape/interface for it so we just return Shape. */
@Deprecated
public Shape makeBufferedLineString(List<Point> points, double buf) {
return shapeFactory.lineString(points, buf);
}

/** Construct a ShapeCollection, analogous to an OGC GeometryCollection. */
@Deprecated
public <S extends Shape> ShapeCollection<S> makeCollection(List<S> coll) {
return shapeFactory.multiShape(coll);
}
Expand Down
55 changes: 22 additions & 33 deletions src/main/java/com/spatial4j/core/shape/ShapeFactory.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

/**
* A factory for {@link Shape}s.
* Stateless and Threadsafe, except for any returned builders.
* Stateless and thread-safe, except for any returned builders.
*/
public interface ShapeFactory {

Expand All @@ -24,7 +24,7 @@ public interface ShapeFactory {
* geodetic boundary into it. Example: 181 will become -179. */
boolean isNormWrapLongitude();

// nocommit annoying that a ShapeReader must remember to call norm* methods. Perhaps
// TODO annoying that a ShapeReader must remember to call norm* methods. Perhaps
// there should be another shapeFactory impl for shape reading? :-/ Or not.

/** Normalize the 'x' dimension. Might reduce precision or wrap it to be within the bounds. This
Expand All @@ -39,9 +39,9 @@ public interface ShapeFactory {
double normZ(double z);

/**
* Called to normalize a value that isn't X or Y. X & Y or normalized via
* {@link com.spatial4j.core.context.SpatialContext#normX(double)} & normY. This
* is called by a {@link com.spatial4j.core.io.WKTReader} before creating a shape.
* Called to normalize a value that isn't X or Y or Z. X & Y & Z are normalized via
* {@link com.spatial4j.core.context.SpatialContext#normX(double)} & normY & normZ. This
* is called by a {@link com.spatial4j.core.io.ShapeReader} before creating a shape.
*/
double normDist(double d);

Expand All @@ -67,7 +67,8 @@ public interface ShapeFactory {
Rectangle rect(Point lowerLeft, Point upperRight);

/**
* Construct a rectangle. If just one longitude is on the dateline (+/- 180)
* Construct a rectangle. If just one longitude is on the dateline (+/- 180) and if
* {@link SpatialContext#isGeo()}
* then potentially adjust its sign to ensure the rectangle does not cross the
* dateline.
*/
Expand All @@ -82,10 +83,11 @@ public interface ShapeFactory {
/** Constructs a line string with a possible buffer. It's an ordered sequence of connected vertexes,
* with a buffer distance along the line in all directions. There
* is no official shape/interface for it so we just return Shape. */
@Deprecated
@Deprecated // use a builder
Shape lineString(List<Point> points, double buf);

/** Construct a ShapeCollection, analogous to an OGC GeometryCollection. */
@Deprecated // use a builder
<S extends Shape> ShapeCollection<S> multiShape(List<S> coll);

// BUILDERS:
Expand All @@ -104,10 +106,13 @@ public interface ShapeFactory {
*/
<T extends Shape> MultiShapeBuilder<T> multiShape(Class<T> shapeClass);

/** (Builder) Constructs a MultiPoint. */
MultiPointBuilder multiPoint();

/** (Builder) Constructs a MultiLineString, or possibly the result of that buffered. */
MultiLineStringBuilder multiLineString();

/** (Builder) Constructs a MultiPolygon. */
MultiPolygonBuilder multiPolygon();

// misc:
Expand All @@ -118,11 +123,15 @@ public interface ShapeFactory {
// TODO need BufferedLineString shape
// TODO need ShapeCollection to be typed

/** Builds a point and returns the generic specified type (usually whatever "this" is). */
interface PointsBuilder<T> {
/** @see ShapeFactory#pointXY(double, double) */
T pointXY(double x, double y);
/** @see ShapeFactory#pointXYZ(double, double, double) */
T pointXYZ(double x, double y, double z);
}

/** @see #lineString() */
interface LineStringBuilder extends PointsBuilder<LineStringBuilder> {
// TODO add dimensionality hint method?

Expand All @@ -131,15 +140,15 @@ interface LineStringBuilder extends PointsBuilder<LineStringBuilder> {
Shape build();
}

/** @see #polygon() */
interface PolygonBuilder extends PointsBuilder<PolygonBuilder> {
// TODO add dimensionality hint method?

/** Starts a new hole. You must add at least 4 points; furthermore the first and last must be the same.
* And don't forget to call {@link HoleBuilder#endHole()}! */
HoleBuilder hole();

/** Builds the polygon and renders this builder instance invalid.
*/
/** Builds the polygon and renders this builder instance invalid. */
Shape build();// never a Rect

Shape buildOrRect();
Expand All @@ -152,6 +161,7 @@ interface HoleBuilder extends PointsBuilder<HoleBuilder> {

// TODO add dimensionality hint method to the multi* builders?

/** @see #multiShape(Class) */
interface MultiShapeBuilder<T extends Shape> {
// TODO add dimensionality hint method?

Expand All @@ -161,11 +171,13 @@ interface MultiShapeBuilder<T extends Shape> {
Shape build();
}

/** @see #multiPoint() */
interface MultiPointBuilder extends PointsBuilder<MultiPointBuilder> {

Shape build(); // TODO MultiShape<Point>
}

/** @see #multiLineString() */
interface MultiLineStringBuilder {

LineStringBuilder lineString();
Expand All @@ -175,6 +187,7 @@ interface MultiLineStringBuilder {
Shape build(); // TODO MultiShape<LineString>
}

/** @see #multiPolygon() */
interface MultiPolygonBuilder {

PolygonBuilder polygon();
Expand All @@ -183,28 +196,4 @@ interface MultiPolygonBuilder {

Shape build(); // TODO MultiShape<Polygon>
}

/*
// TODO should normWrapLongitude, normX, normY, verifyX, verifyY be here too?
// TODO use make* style?
Point pointXY(double x, double y);
Point pointXYZ(double x, double y, double z);
Rectangle rect(Point lowerLeft, Point upperRight);
Rectangle rect(double minX, double maxX, double minY, double maxY);
Circle circle(double x, double y, double distance);
Circle circle(Point point, double distance);
LineStringBuilder lineString();
LineStringBuilder bufferedLineString(double distance);
PolygonBuilder polygon();
<T extends Shape> MultiShapeBuilder<T> multiShape(Class<T> shapeClass);
*/
}
6 changes: 3 additions & 3 deletions src/main/java/com/spatial4j/core/shape/jts/JtsShapeFactory.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -410,14 +410,14 @@ public Shape build() {

@Override
public <T extends Shape> MultiShapeBuilder<T> multiShape(Class<T> shapeClass) {
// TODO: once we have typed shapes for Polygons & LineStrings, this logic could move to the superclass
// (not JTS specific) and the multi* builders could take a Shape
if (!useJtsMulti()) {
return super.multiShape(shapeClass);
}
return new JtsMultiShapeBuilder<>();
}

// TODO: once we have typed shapes for Polygons & LineStrings, this logic could move to the superclass
// (not JTS specific) and the multi* builders could take a Shape
private class JtsMultiShapeBuilder<T extends Shape> extends GeneralShapeMultiShapeBuilder<T> {
@Override
public Shape build() {
Expand Down Expand Up @@ -456,7 +456,7 @@ public Shape build() {
* If given a {@link LineString} and if {@link JtsSpatialContext#useJtsLineString()} is true then
* then the geometry's parts are exposed to call {@link SpatialContext#makeLineString(List)}.
*/
// TODO nocommit NEED TO DECIDE ON makeShapeFromGeometry being called always (consistent but sometimes not needed?)
// TODO should this be called always (consistent but sometimes not needed?)
// v.s. only from a ShapeReader (pre-ShapeFactory behavior)
public Shape makeShapeFromGeometry(Geometry geom) {
if (geom instanceof GeometryCollection) {
Expand Down

0 comments on commit f907f63

Please sign in to comment.