Module com.esri.arcgisruntime

Package com.esri.arcgisruntime.geometry

Class GeometryBuilder

java.lang.Object

com.esri.arcgisruntime.geometry.GeometryBuilder

Direct Known Subclasses:

EnvelopeBuilder, MultipartBuilder, MultipointBuilder, PointBuilder

public abstract class GeometryBuilder
extends Object

Geometry builders allow you to create and modify geometries incrementally.

This is the base class for a range of geometry builders, such as a PointBuilder, PolylineBuilder and PolygonBuilder. Each GeometryType has a corresponding type of builder. You can create and modify polygons with PolygonBuilder, envelopes with the EnvelopeBuilder, and so on. Use a geometry builder in editing workflows where you need to build up or edit geometry one vertex at a time, for example, when you need to add or edit a vertex from a custom streaming GIS data source. You can either create an empty geometry builder and build up the shape of a Geometry, or you can create a geometry builder with an existing Geometry and modify it.

When you construct the builder, you can explicitly set its SpatialReference or you can construct the builder with a geometry and the builder will adopt the Geometry.getSpatialReference(). Once set, the SpatialReference cannot be changed. The SpatialReference of any geometry or coordinates added to the builder must be compatible with the SpatialReference of the builder, as they will not be reprojected. The SpatialReference of a geometry added to the builder can be null, in which case the object is assumed to have the same SpatialReference as the builder it is added to.

There are other ways to create and edit geometries. If you know all the geometry coordinates up front, then you can use geometry constructors, such as Polygon, to create the geometry. If you are going to create a new geometry as a result of a topological operation, such as the buffer operation, then explore the GeometryEngine. If you want your app users to interactively create or edit geometries in the user interface then use the GeometryEditor.

Since:

100.0.0

See Also:

• Geometry
• GeometryEditor

Method Summary

Modifier and Type	Method	Description
static GeometryBuilder	create(Geometry geometry)	Creates a geometry builder with the specified geometry as a starting point for further modification.
static GeometryBuilder	create(GeometryType geometryType, SpatialReference spatialReference)	Creates an empty geometry builder which builds geometries of the specified GeometryType.
GeometryBuilderType	getBuilderType()	Deprecated, for removal: This API element is subject to removal in a future version. since 200.1.0, use instanceof to determine the GeometryBuilder type
Envelope	getExtent()	Gets the extent of the geometry being constructed in the geometry builder.
SpatialReference	getSpatialReference()	The spatial reference for the geometry.
boolean	hasCurves()	True if the geometry builder currently contains any curve segments, false otherwise.
boolean	hasM()	True if the geometry builder supports geometries with m values, false otherwise.
boolean	hasZ()	True if the geometry builder supports geometries with z values, false otherwise.
boolean	isEmpty()	True if no coordinates have been added to this geometry builder, false otherwise.
boolean	isSketchValid()	True if the geometry builder contains sufficient points to show a valid graphical sketch, false otherwise.
void	replaceGeometry(Geometry geometry)	Replaces the geometry currently stored in the geometry builder with the new geometry.
abstract Geometry	toGeometry()	Returns a new Geometry based on the current state of this builder.

Methods inherited from class java.lang.Object

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

Method Details

create

public static GeometryBuilder create(Geometry geometry)

Creates a geometry builder with the specified geometry as a starting point for further modification.

Geometries with curves are supported.

Parameters:

geometry - the geometry to use as the starting point for further modifications

Returns:

the new geometry builder

Throws:

IllegalArgumentException - if geometry is null

Since:

100.1.0

See Also:

• hasCurves()

create

public static GeometryBuilder create(GeometryType geometryType,
 SpatialReference spatialReference)

Creates an empty geometry builder which builds geometries of the specified GeometryType.

Parameters:

geometryType - the builder's geometry type

spatialReference - the builder's spatial reference; may be null

Returns:

the new geometry builder

Throws:

IllegalArgumentException - if geometryType is null

Since:

100.1.0

getSpatialReference

public SpatialReference getSpatialReference()

The spatial reference for the geometry.

Once set, the SpatialReference of the geometry builder cannot be changed. Ensure that all objects added to the builder have a compatible SpatialReference.

Returns:

the spatial reference of this instance

Since:

100.0.0

See Also:

• hasCurves()

getExtent

public Envelope getExtent()

Gets the extent of the geometry being constructed in the geometry builder.

Returns:

the current extent of the geometry being constructed

Since:

100.0.0

hasCurves

public boolean hasCurves()

True if the geometry builder currently contains any curve segments, false otherwise.

ArcGIS software supports polygon and polyline geometries that contain curve segments (where Segment.isCurve() is true, sometimes known as true curves or nonlinear segments). Curves may be present in certain types of data, such as Mobile Map Packages (MMPKs), or geometry JSON.

You can use curves in a MultipartBuilder. New segment types, such as CubicBezierSegment and EllipticArcSegment, represent types of curve that can be added to polygon and polyline geometries.

Returns:

true if this GeometryBuilder contains curved segments; false otherwise

Since:

100.12.0

See Also:

• Part.hasCurves()
• Geometry.hasCurves()
• Segment.isCurve()

getBuilderType

@Deprecated(since="200.1.0",
            forRemoval=true)
public GeometryBuilderType getBuilderType()

Deprecated, for removal: This API element is subject to removal in a future version.

since 200.1.0, use instanceof to determine the GeometryBuilder type

Gets the subtype of this builder instance. This indicates which type of geometries the builder can create; each type of builder creates a single GeometryType.

Returns:

the builder subtype

Since:

100.0.0

hasZ

public boolean hasZ()

True if the geometry builder supports geometries with z values, false otherwise.

Z values are generally used as a z coordinate, indicating height or elevation. NaN is a valid z value. If true, z values are stored for each vertex of the constructed Geometry. Geometries with z values are created by using setters or constructors that take a z value as a parameter.

Returns:

true if this builder contains z values, false otherwise

Since:

100.0.0

See Also:

• Geometry.hasZ()

hasM

public boolean hasM()

True if the geometry builder supports geometries with m values, false otherwise.

M values are often referred to as measures, and are used in linear referencing workflows on linear datasets. NaN is a valid m value. If true, m values are stored for each vertex of the constructed Geometry. Geometries with m values are created by using setters or constructors that take an m value as a parameter.

Returns:

true if this builder has m values, false otherwise

Since:

100.0.0

See Also:

• Geometry.hasM()

isEmpty

public boolean isEmpty()

True if no coordinates have been added to this geometry builder, false otherwise.

An empty geometry builder may have a valid SpatialReference, even without coordinates.

Returns:

true if no coordinates have been added to this instance, false otherwise

Since:

100.0.0

See Also:

• Geometry.isEmpty()

isSketchValid

public boolean isSketchValid()

True if the geometry builder contains sufficient points to show a valid graphical sketch, false otherwise.

This can be used as an initial lightweight check to see if the current state of a builder produces a non-empty geometry. For example, it may be used to enable or disable functionality in an editing user interface. The exact requirements vary depending on the type of geometry produced by the builder:

• A PointBuilder must contain non-NaN x,y coordinates
• A MultipointBuilder must contain at least one valid Point
• An EnvelopeBuilder must contain non-NaN minimum and maximum x,y coordinates
• A PolylineBuilder must contain at least one Part. Each Part it contains must have:
  • At least two valid points, or
  • At least one Segment where Segment.isCurve() is true
• A PolygonBuilder must contain at least one Part. Each Part it contains must have:
  • At least three valid points, or
  • At least one Segment where Segment.curveProperty() is true

Note that this is not equivalent to topological simplicity, which is enforced by GeometryEngine.simplify(Geometry) and checked using GeometryEngine.isSimple(Geometry). Geometries must be topologically simple to be successfully saved in a geodatabase or used in some service operations.

It does not check the spatial reference and returns false if an error occurs.

Returns:

true if toGeometry() would return a geometry that is a valid sketch, false otherwise

Since:

100.0.0

replaceGeometry

public void replaceGeometry(Geometry geometry)

Replaces the geometry currently stored in the geometry builder with the new geometry.

This method can be used as an alternative to creating a new builder from an existing geometry. Note that this does not update the spatial reference of the builder and the builder geometry is cleared if the geometry is null. Geometries with curves are supported.

Parameters:

geometry - the new geometry to replace the existing geometry with

Since:

100.0.0

toGeometry

public abstract Geometry toGeometry()

Returns a new Geometry based on the current state of this builder. This method can be called as many times as required for any specific instance; it does not affect the state of the builder, and returns a new Geometry each time.

Returns:

a new geometry this geometry builder is constructing or modifying. This is passed to geometry functions.

Since:

100.0.0