public interface ILcd2DBoundsIndexedModel extends ILcdModel, ILcdBounded, ILcd2DBoundsInteractable
ILcdModel
whose elements can be retrieved via a spatial index, using 2D rectangular bounds.
A callback function is used to pass the results of the queries to the user of this interface.
The model itself is ILcdBounded
; its bounds will at least contain the geometries of its
elements, but may be larger.
Performance of operations that require model access may depend heavily on whether a model can be spatially queried. It is therefore advised to use model implementations that implement this interface whenever possible.
Implementations of this interface that use the ILcdBounded
property of the
model's elements to store and retrieve the elements in a spatial index should take care when implementing the
ILcdModel.elementChanged(Object, int)
method: the bounds of an element will already have changed at the moment
the elementChanged
method is called, and can thus not be used to retrieve the element in the index!
ILcdModel.Query
FIRE_LATER, FIRE_NOW, NO_EVENT
Modifier and Type | Method and Description |
---|---|
int |
applyOnInteract2DBounds(ILcdBounds aBounds,
boolean aStrictInteract,
ILcdFunction aFunctionToApply,
double aPrecisionX,
double aPrecisionY)
Applies the specified function to all the model elements of which the 2D bounds overlap with the specified bounds.
|
int |
applyOnInteract2DBounds(ILcdBounds aBounds,
boolean aStrictInteract,
ILcdFunction aFunctionToApply,
double aPrecisionX,
double aPrecisionY,
double aMinSizeX,
double aMinSizeY,
boolean aIncludePoints)
Applies the specified function to all the elements of which the 2D bounds overlap with the specified bounds.
|
default <T> Stream<T> |
query(ILcdModel.Query aQuery)
Provides a
Stream of all elements in this model that match the given query. |
addElement, addElements, addModelListener, all, canAddElement, canRemoveElement, dispose, elementChanged, elements, elementsChanged, filter, fireCollectedModelChanges, getModelDescriptor, getModelEncoder, getModelMetadata, getModelReference, removeAllElements, removeElement, removeElements, removeModelListener
close
getBounds
int applyOnInteract2DBounds(ILcdBounds aBounds, boolean aStrictInteract, ILcdFunction aFunctionToApply, double aPrecisionX, double aPrecisionY)
false
.aBounds
- the rectangle to test overlap with.aStrictInteract
- if false
, the spatial search may return more elements than the ones strictly
overlapping; if true
, the search only returns the elements that are
overlapping. The latter mode is more precise, but it may be slower.aFunctionToApply
- the function to apply on each element that overlaps with the given bounds.
The return value of the specified function is used as a stop criterion: the spatial query is interrupted
if the function returns false
.aPrecisionX
- the precision required in the x dimension, expressed in model units.
For example, for a cartesian grid system expressed in meters, the values
should be expressed in meters as well, for a geodetic coordinate system the accuracy
values should be expressed in degrees.
The precision is useful in combination with multi-leveled data (multiple representations of the same object, but with varying accuracy), so that the most appropriate accuracy level can be used. 0 means best possible accuracy, but it might trigger lazy-loaded implementations to load lots of data.
aPrecisionY
- the precision required in the y dimension, expressed in model units.ILcdFunction
has been applied.NullPointerException
- if the specified bounds or the specified function are null
.int applyOnInteract2DBounds(ILcdBounds aBounds, boolean aStrictInteract, ILcdFunction aFunctionToApply, double aPrecisionX, double aPrecisionY, double aMinSizeX, double aMinSizeY, boolean aIncludePoints)
ILcd2DBoundsInteractable
false
for an element it was applied on.applyOnInteract2DBounds
in interface ILcd2DBoundsInteractable
aBounds
- the rectangle to test overlap with.aStrictInteract
- if false
, the spatial search may return more elements than the ones strictly
overlapping; if true
, the search only returns the elements that are
overlapping. The latter mode is more precise, but it may be slower.aFunctionToApply
- the function to apply on each element that overlaps with the given bounds.aPrecisionX
- the precision required in the x dimension, expressed in model units.
For example, for a cartesian grid system expressed in meters, the values
should be expressed in meters as well, for a geodetic coordinate system the accuracy
values should be expressed in degrees.
The precision is useful in combination with multi-leveled data (multiple representations of the same object, but with varying accuracy), so that the most appropriate accuracy level can be used. 0 means best possible accuracy, but it might trigger lazy-loaded implementations to load lots of data.
aPrecisionY
- the precision required in the y dimension, expressed in model units.aMinSizeX
- the minimal element size in the x dimension (as in
ILcdBounds.getWidth()
), expressed in model units.
Elements that are smaller than this size will be skipped. This may, for example, be
useful when improving the efficiency of painting elements by skipping elements
that are smaller than some threshold (e.g. one pixel, converted to model units).aMinSizeY
- the minimal element size in the y dimension (as in
ILcdBounds.getHeight()
), expressed in model units.aIncludePoints
- if true
, zero-sized elements (points) are considered as well, even though they
might be smaller than the minimum size.ILcdFunction
has been applied.default <T> Stream<T> query(ILcdModel.Query aQuery)
Stream
of all elements in this model that match the given query.
If the query condition contains a spatial component (either bounding-box test
,
or a spatial operator) applyOnInteracts2DBounds
is
used first to narrow down the set of relevant objects. The rest of the conditions are then evaluated on that subset.
If the query condition contains a minimum object size
aspect,
that minimum size is passed as arguments to the applyOnInteract2DBounds
call.
Stream
of all elements in this model that match the given query.
The query aspects are applied in this specific order, regardless of the order used to create the query:
filter
is applied first (if any).sorting
is applied second (if any).limit
is applied last (if any).condition
and sort-by
must never change after creation.
Examples:
query
(all
());query
(filter
(new TLcdOGCBBoxOperator(...)));query
(filter
(eq(property("name"), literal("Leuven")));query
(all
().sorted
(comparing(property("population"), DESC));query
(all
().limit
(150));query
(filter
(and(bboxCondition, ogcCondition)).sorted
(sortByPopulation).limit
(120));
A stream
is closeable
, and it depends on the implementation whether the stream
has to be closed or not.
You should use this template to ensure proper model locking and stream closing:
try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.readLock(model);
Stream elements = model.query(all())) {
elements.forEach(System.err::println);
}
Model implementations:
By default, this method will invoke elements()
, loop over all elements and apply the filter, sorting and limit.
For ILcd2DBoundsIndexedModel
, this method will invoke applyOnInteract2DBounds()
if the condition contains a spatial component (either a bounding-box operator, or a spatial operator), and apply the rest of the filter on those elements.
Model implementers can override this method to apply the query more efficiently on their back-end format.
For example, if your back-end is a service or database that accepts certain queries, you can override this method and
transform the condition into a query on that service.
You can inspect the condition using instanceof
on the various condition classes.
query
in interface ILcdModel
aQuery
- The query, cannot be null
. Pass ILcdModel.all()
if you want all elements.TLcdOGCFilterFactory to easily create conditions
,
TLcdOGCSortBy "comparing" and "thenComparing" factory methods to easily create sorting orders