public class TLcd2DBoundsIndexedModel extends ALcdModel implements ILcd2DBoundsIndexedModel, ILcdIntegerIndexedModel, Serializable
ILcd2DBoundsIndexedModel that is also an
ILcdIntegerIndexedModel.
This model stores its elements in a spatial index, based on the bounds of the
elements. All elements contained in this model should therefore implement
ILcdBounded or expose it.
Users should notify this model whenever the bounds of an
element in the model are changed, to allow the model to update its index.
This can be done by means of the elementChanged(Object, int) method.
All elements are additionally stored in a linear index, allowing fast integer- based queries.
If it is unclear which model to use, this model is a good first choice that
has a good overall performance without using too much resources or adding
too much complexity to the application. The package
documentation provides a detailed overview of all model implementations that
are available in this package, and their usage.
The current implementation creates a spatial index based on an R-tree if no initial bounds are specified, or on a BSP-tree if initial bounds are specified. The R-tree is generally slower to build and to modify, but it is slightly faster to query and more memory-efficient.
Although the BSP-tree requires initial bounds, it automatically grows when an element is added outside these bounds. This is achieved by unfolding the bounding rectangle of the tree until the element is contained in it. This unfolding may lead to bounds that are significantly larger than the minimal bounds. Choosing proper initial bounds therefore helps achieving a good performance for accessing the model.
This class is thread-safe for read-only access of its elements.
For read-write access, external locking must be used, typically on the model
itself. The utility class TLcdLockUtil provides convenient methods
readLock(Object),
readUnlock(Object),
writeLock(Object), and
writeUnlock(Object) to do so.
Before LuciadLightspeed version 7.0, the methods for adding, updating, removing, and
accessing elements were synchronized. The current implementation no longer
performs this internal synchronization, mainly for allowing concurrent
read-only access and therefore better performance in multi-threaded
applications. Note that internal synchronization on its own was not
sufficient for safe concurrent reading and writing (e.g. due to the
elements() method, which returns an enumeration).
If internal synchronization is required for backward compatibility, one can
set the static compatibility flag with setSynchronized(boolean), or
one can define the system property
com.luciad.model.TLcd2DBoundsIndexedModel.synchronized
when starting up the Java Virtual Machine, typically as follows:
java -Dcom.luciad.model.TLcd2DBoundsIndexedModel.synchronized ....Internal synchronization will then be performed, as in previous versions.
ILcdModel.QueryfModelEventSupportFIRE_LATER, FIRE_NOW, NO_EVENT| Constructor and Description |
|---|
TLcd2DBoundsIndexedModel()
Constructs a new, empty
TLcd2DBoundsIndexedModel with a default TLcdModelDescriptor. |
TLcd2DBoundsIndexedModel(ILcdBounds aBounds)
Constructs a new empty
TLcd2DBoundsIndexedModel with a default TLcdModelDescriptor. |
TLcd2DBoundsIndexedModel(ILcdModelReference aModelReference,
ILcdModelDescriptor aModelDescriptor)
Constructs a new, empty
TLcd2DBoundsIndexedModel, initialized with the specified model
reference and model descriptor. |
| Modifier and Type | Method and Description |
|---|---|
void |
addElement(Object aElement,
int aEventMode)
Adds the specified element to this model.
|
void |
allElementsChanged(int aFireEventMode)
Notifies this model that all elements have changed.
|
int |
applyOnInteract2DBounds(ILcdBounds aBounds,
boolean aStrictOverlap,
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 aStrictOverlap,
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.
|
boolean |
canAddElement(Object aElement)
This implementation returns
true if and only if all of the following criteria are met:
The specified element implements or exposes ILcdBounded.
If an addition filter is set, filter.accept(aElement) returns true.
|
boolean |
canRemoveElement(Object aElement)
This implementation returns
true if and only if all of the following criteria are met:
The specified element implements or exposes ILcdBounded.
If a removal filter is set, filter.accept(aElement) returns true.
|
boolean |
contains(Object aElement)
Returns
true if the specified element is contained in this model, false otherwise. |
Object |
elementAt(int aIndex)
Returns the element at the specified index.
|
void |
elementChanged(Object aElement,
int aFireEventMode)
Notifies this model that the specified element has changed.
|
Enumeration |
elements()
Returns an enumeration over all elements of this model.
|
void |
elementsChanged(Vector aElements,
int aFireEventMode)
Notifies this model that the elements in the specified vector have changed.
|
ILcdFilter |
getAddElementFilter()
Returns the filter that is used to control which elements are accepted for addition to this model.
|
ILcdBounds |
getBounds()
Returns the
ILcdBounds by which the geometry of this ILcdBounded object
is bounded. |
ILcdFilter |
getRemoveElementFilter()
Returns the filter that is used to control which elements are accepted for removal from this model.
|
int |
indexOf(Object aElement)
Returns the index of the first occurrence of the specified element in the model, or -1 if this model does not
contain the element.
|
static boolean |
isSynchronized()
Returns whether accessing elements is synchronized.
|
void |
removeAllElements(int aEventMode)
Removes all elements from this model.
|
void |
removeElement(Object aElement,
int aEventMode)
Removes the specified element from this model.
|
void |
setAddElementFilter(ILcdFilter aFilter)
Sets the filter that is used to control which elements are accepted for addition to this model.
|
void |
setRemoveElementFilter(ILcdFilter aFilter)
Sets the filter that is used to control which elements are accepted for removal from this model.
|
static void |
setSynchronized(boolean aSynchronized)
Specifies whether accessing elements should be synchronized, for backward
compatibility.
|
int |
size()
Returns the number of elements in this model.
|
addElements, addModelListener, allElementsRemoved, dispose, elementAdded, elementRemoved, elementsAdded, elementsRemoved, fireCollectedModelChanges, getModelDescriptor, getModelEncoder, getModelMetadata, getModelReference, initializeTransientValues, isClassTraceOn, isTraceOn, removeElements, removeModelListener, setClassTraceOn, setModelDescriptor, setModelDisposer, setModelEncoder, setModelMetadataFunction, setModelReference, setTraceOnclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitqueryaddElements, addModelListener, all, dispose, filter, fireCollectedModelChanges, getModelDescriptor, getModelEncoder, getModelMetadata, getModelReference, removeElements, removeModelListenerclosepublic TLcd2DBoundsIndexedModel()
TLcd2DBoundsIndexedModel with a default TLcdModelDescriptor.public TLcd2DBoundsIndexedModel(ILcdModelReference aModelReference, ILcdModelDescriptor aModelDescriptor)
TLcd2DBoundsIndexedModel, initialized with the specified model
reference and model descriptor.aModelReference - the model reference describing the coordinate system used in this model.aModelDescriptor - the model descriptor providing meta information about this model.public TLcd2DBoundsIndexedModel(ILcdBounds aBounds)
TLcd2DBoundsIndexedModel with a default TLcdModelDescriptor.aBounds - the initial bounds for the spatial indexing scheme of the model.
They should ideally encompass all the elements the user plans to add
to the model, although this model will extend its bounds when required,
by 'unfolding' the rectangle in the appropriate direction, i.e. by doubling
the size of the bounds. The bounds of the entire model space are a safe bet,
although they will be less efficient when the model is much smaller.public static void setSynchronized(boolean aSynchronized)
false.public static boolean isSynchronized()
public void setAddElementFilter(ILcdFilter aFilter)
canAddElement(Object) method, to decide whether an element can be added to
this model or not. The filter should not explicitly check whether a specified element is ILcdBounded,
this check will always be performed by the canAddElement method. If no filter is set, only the
instanceof ILcdBounded test will be performed. By default, no filter is set.aFilter - the filter to be used to control which elements are accepted for addition to this model.canAddElement(Object),
getAddElementFilter()public ILcdFilter getAddElementFilter()
canAddElement(Object),
setAddElementFilter(com.luciad.util.ILcdFilter)public void setRemoveElementFilter(ILcdFilter aFilter)
canRemoveElement(Object) method, to decide whether an element can be removed
from this model or not. The filter should not explicitly check whether a specified element is
ILcdBounded, this check will always be performed by the canRemoveElement method. If no
filter is set, only the instanceof ILcdBounded test will be performed. By default, no filter is set.aFilter - the filter to be used to control which elements are accepted for removal from this model.canRemoveElement(Object),
getRemoveElementFilter()public ILcdFilter getRemoveElementFilter()
canRemoveElement(Object),
setRemoveElementFilter(com.luciad.util.ILcdFilter)public boolean canAddElement(Object aElement)
This implementation returns true if and only if all of the following criteria are met:
ILcdBounded.filter.accept(aElement) returns true.canAddElement in interface ILcdModelcanAddElement in class ALcdModelaElement - the Object to be checked.public void addElement(Object aElement, int aEventMode)
Models that support this operation may place limitations on what elements may be added to this model. For example,
implementations that are based on a spatial indexing structure will require that elements implement
ILcdBounded.
When adding an element, the user should make sure that canAddElement(aElement) holds, and that the
element's geometry is expressed in the same model reference as this model. It is generally undefined what happens
if an invalid element is added.
Implementations of this interface should clearly specify in their documentation any restrictions on what elements
may be added. Although it is unspecified what happens if the preconditions are not met, implementations are
encouraged to throw meaningful exceptions (for example, NullPointerException, IllegalArgumentException,
ClassCastException, UnsupportedOperationException), whenever possible.
This implementation always throws an UnsupportedOperationException.
This implementation calls ALcdModel.elementAdded(Object, int) after the element has been added, to send a
model change event to this model's listeners.
addElement in interface ILcdModeladdElement in class ALcdModelaElement - the element to be added to this model.aEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.ILcdModel.canAddElement(Object)public boolean canRemoveElement(Object aElement)
This implementation returns true if and only if all of the following criteria are met:
ILcdBounded.filter.accept(aElement) returns true.canRemoveElement in interface ILcdModelcanRemoveElement in class ALcdModelaElement - the element to be verified.true if the specified element can be removed from this model, false otherwise.public void removeElement(Object aElement, int aEventMode)
Although it is unspecified what happens if the preconditions are not met, implementations are encouraged to
throw meaningful exceptions (for example, NullPointerException, IllegalArgumentException, ClassCastException,
UnsupportedOperationException), whenever possible.
This implementation always throws an UnsupportedOperationException.
This implementation calls ALcdModel.elementRemoved(Object, int) after the element has been removed, to
sent a model change event to this model's listeners.
removeElement in interface ILcdModelremoveElement in class ALcdModelaElement - the element to be removed from this model.aEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.ILcdModel.canRemoveElement(Object)public void removeAllElements(int aEventMode)
If an element cannot be removed, this method will return at the first failure. Succeeding elements won't be removed.
Although it is unspecified what happens if the preconditions are not met, implementations are encouraged to
throw meaningful exceptions (for example, NullPointerException, IllegalArgumentException, ClassCastException,
UnsupportedOperationException), whenever possible.
This implementation iterates over all elements in the model, and calls
removeElement(Object, int) for each element to be removed, using event mode NO_EVENT if the
specified event mode is NO_EVENT, FIRE_LATER otherwise.
If the specified event mode is FIRE_NOW, fireCollectedModelChanges() is called afterwards.
This implementation calls ALcdModel.allElementsRemoved(int) after the elements have been removed, to sent a model
change event to this model's listeners.
removeAllElements in interface ILcdModelremoveAllElements in class ALcdModelaEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.public void elementsChanged(Vector aElements, int aFireEventMode)
ALcdModelThis implementation calls TLcdModelChangedEventSupport#elementsChanged(java.util.Vector, int).
elementsChanged in interface ILcdModelelementsChanged in class ALcdModelaElements - the vector of elements that have changed.aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.public void allElementsChanged(int aFireEventMode)
ALcdModelThis implementation calls TLcdModelChangedEventSupport#allElementsChanged(int).
allElementsChanged in class ALcdModelaFireEventMode - the mode for sending out the model change event. This can be one of
FIRE_NOW, FIRE_LATER or
NO_EVENT. In case of FIRE_NOW mode,
only one event will be fired, containing all changes.public void elementChanged(Object aElement, int aFireEventMode)
ALcdModel
This implementation calls TLcdModelChangedEventSupport#elementChanged(Object, int).
elementChanged in interface ILcdModelelementChanged in class ALcdModelaElement - the element that has changed.aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.public boolean contains(Object aElement)
true if the specified element is contained in this model, false otherwise.aElement - the element to be tested.true if the specified element is contained in this model, false otherwise.public int size()
ILcdIntegerIndexedModelsize in interface ILcdIntegerIndexedModelpublic Enumeration elements()
ILcdModelpublic Object elementAt(int aIndex)
ILcdIntegerIndexedModelelementAt in interface ILcdIntegerIndexedModelaIndex - an index into this ILcdModel.public int indexOf(Object aElement)
ILcdIntegerIndexedModeli for which this.elementAt(i).equals(aElement).indexOf in interface ILcdIntegerIndexedModelaElement - the element to search for.public ILcdBounds getBounds()
ILcdBoundedILcdBounds by which the geometry of this ILcdBounded object
is bounded.
If the geometry does not allow retrieving valid bounds (for example a polyline with 0 points)
the return value is unspecified.
It is highly recommended to return an undefined bounds.
You can create undefined bounds using the default constructors
of TLcdLonLatBounds
or TLcdXYBounds.
getBounds in interface ILcdBoundedILcdBounds by which the geometry of this ILcdBounded object
is bounded.public int applyOnInteract2DBounds(ILcdBounds aBounds, boolean aStrictOverlap, ILcdFunction aFunctionToApply, double aPrecisionX, double aPrecisionY)
false.
This implementation delegates to applyOnInteract2DBounds(com.luciad.shape.ILcdBounds, boolean, com.luciad.util.ILcdFunction, double, double, double, double, boolean)
using the same parameters, using 0.0 as a value for aMinSizeX and aMinSizeY
and false for aIncludePoints.
applyOnInteract2DBounds in interface ILcd2DBoundsIndexedModelaBounds - the rectangle to test overlap with.aStrictOverlap - 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.public int applyOnInteract2DBounds(ILcdBounds aBounds, boolean aStrictOverlap, ILcdFunction aFunctionToApply, double aPrecisionX, double aPrecisionY, double aMinSizeX, double aMinSizeY, boolean aIncludePoints)
ILcd2DBoundsInteractablefalse for an element it was applied on.applyOnInteract2DBounds in interface ILcd2DBoundsIndexedModelapplyOnInteract2DBounds in interface ILcd2DBoundsInteractableaBounds - the rectangle to test overlap with.aStrictOverlap - 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.