public class TLcdDatabaseModel extends ALcdModel implements ILcd2DBoundsIndexedModel
ILcd2DBoundsIndexedModel
. The elements in the
model can be retrieved sequentially or based on a query, and they
can be added, changed, and deleted.
The model elements are ILcdShape
objects. Typical database
models contain the following elements:
ILcdPoint
,
ILcdPolypoint
,
ILcdPolyline
,
ILcdPolygon
,
ILcdComplexPolygon
,
ILcdArc
,
ILcdBounds
,
ILcdCircle
, and
ILcdShapeList
.
The elements are retrieved from the database as they are needed. The entire database will therefor not be loaded when the user is only working on a small part of it. The connection to the database has to remain available while the model is being accessed.
The model can be changed by adding, changing, or deleting elements. The
updates are only effectively written to the database when the
commit()
method is executed. Changes are discarded when the
rollback()
method is executed. You can see if there are any uncommitted changes
through the isDirty()
method.
The database is best not changed by other database users, as the
TLcdDatabaseModel
will not be aware of these changes.
The database may become inconsistent if the same geometry is altered by
different users at the same time. If the database is changed by another user
anyway, calling the clearCache()
method will clear the object's
caches, so that it will be synchronized with the database.
ILcdShape
,
Serialized FormILcdModel.Query
fModelEventSupport
FIRE_LATER, FIRE_NOW, NO_EVENT
Modifier and Type | Method and Description |
---|---|
void |
addElement(Object aObject,
int aFireEventMode)
Adds the specified element to this model.
|
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 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.
|
boolean |
canAddElement(Object aObject)
Returns
true if the specified element can be added to this model, false otherwise. |
boolean |
canRemoveElement(Object aObject)
Returns
true if the specified element can be removed from this model, false otherwise. |
void |
clearCache()
Drops all changes made since the previous commit/rollback and clears any
cached elements, so all requested elements will be reloaded from the
database.
|
void |
commit()
Makes all changes made since the previous commit/rollback permanent.
|
void |
dispose()
Closes the descriptor of this
TLcdDatabaseModel , thus releasing
the JDBC system resources that it is using. |
void |
elementChanged(Object aObject,
int aFireEventMode)
Notifies this model that the specified element has changed.
|
ILcdAutoCloseableEnumeration |
elements()
Returns an enumeration over all elements of this model.
|
ILcdAutoCloseableEnumeration |
elements(Enumeration aKeyEnumeration)
Retrieves the geometries with the given keys.
|
boolean |
getAutoCommit()
Gets the current auto-commit state.
|
ILcdBounds |
getBounds()
Returns the
ILcdBounds by which the geometry of this ILcdBounded object
is bounded. |
int |
getMaxCacheSize() |
static boolean |
isClassTraceOn()
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
boolean |
isDirty()
Indicates whether this model contains any uncommitted changes.
|
boolean |
isTraceOn()
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
void |
refresh()
Re-retrieves all cached elements (domain objects) from the database and retrieves elements that have been added to the database.
|
void |
removeAllElements(int aFireEventMode)
Removes all elements from this model.
|
void |
removeElement(Object aObject,
int aFireEventMode)
Removes the specified element from this model.
|
void |
rollback()
Drops all changes made since the previous commit/rollback and clears any cached elements, so
all requested elements will be reloaded from the database.
|
static void |
setClassTraceOn(boolean aClassTraceOn)
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
void |
setMaxCacheSize(int aMaxCacheSize) |
void |
setModelDescriptor(ILcdModelDescriptor aModelDescriptor)
Sets the model descriptor providing meta information about this model and its elements.
|
String |
toString() |
addElements, addModelListener, allElementsChanged, allElementsRemoved, elementAdded, elementRemoved, elementsAdded, elementsChanged, elementsRemoved, fireCollectedModelChanges, getModelDescriptor, getModelEncoder, getModelMetadata, getModelReference, initializeTransientValues, removeElements, removeModelListener, setModelDisposer, setModelEncoder, setModelMetadataFunction, setModelReference, setTraceOn
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
query
addElements, addModelListener, all, elementsChanged, filter, fireCollectedModelChanges, getModelDescriptor, getModelEncoder, getModelMetadata, getModelReference, removeElements, removeModelListener
close
public static void setClassTraceOn(boolean aClassTraceOn)
true
then all log messages are recorded, otherwise only
the informative, warning and error messages are recorded.aClassTraceOn
- if true then all log messages are recorded,
otherwise only the informative, warning and error messages are recorded.public static boolean isClassTraceOn()
true
if tracing is enabled for this class.public boolean isTraceOn()
true
if tracing is enabled for this class.public void setModelDescriptor(ILcdModelDescriptor aModelDescriptor)
ALcdModel
setModelDescriptor
in class ALcdModel
aModelDescriptor
- a data descriptor for this model. Must be a
ILcdDatabaseModelDescriptor
.ALcdModel.getModelDescriptor()
public void setMaxCacheSize(int aMaxCacheSize)
public int getMaxCacheSize()
public boolean getAutoCommit()
public boolean isDirty()
true
if there are uncommitted changes, false
otherwise.commit()
,
rollback()
public void commit() throws IOException
try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.writeLock(model)) {
model.commit();
}
IOException
- if the elements can't be retrieved due to
some database error.isDirty()
public void rollback()
ALcdModel.allElementsChanged(int)
:
try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.writeLock(model)) {
model.rollback();
model.allElementsChanged(FIRE_LATER);
} finally {
model.fireCollectedModelChanges();
}
public void clearCache()
ALcdModel.allElementsChanged(int)
:
try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.writeLock(model)) {
model.clearCache();
model.allElementsChanged(FIRE_LATER);
} finally {
model.fireCollectedModelChanges();
}
rollback()
public void refresh()
The cached elements themselves are changed in-place: their instances are kept.
Notes:
try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.writeLock(model)) { model.refresh(); } finally { model.fireCollectedModelChanges(); }
Limitation: this method is not implemented for Informix, DB2 and SpatiaLite databases.
public ILcdAutoCloseableEnumeration elements(Enumeration aKeyEnumeration) throws IOException
aKeyEnumeration
- the Enumeration
of the keys of objects
to retrieve.ILcdAutoCloseableEnumeration
of objects with the given keys.IOException
public boolean canAddElement(Object aObject)
ALcdModel
true
if the specified element can be added to this model, false
otherwise.
Note that this method generally does not validate whether the specified element is expressed in the same model reference as this model. It is the responsibility of the user of this model to make sure this precondition is fulfilled when an element is added to this model.
This implementation always returns false
.
canAddElement
in interface ILcdModel
canAddElement
in class ALcdModel
aObject
- the element to be verified.true
if the specified element can be added to this model, false
otherwise.public boolean canRemoveElement(Object aObject)
ALcdModel
true
if the specified element can be removed from this model, false
otherwise.
Note that this method generally does not check whether the specified element is actually contained in this model.
This implementation always returns false
.
canRemoveElement
in interface ILcdModel
canRemoveElement
in class ALcdModel
aObject
- the element to be verified.true
if the specified element can be removed from this model, false
otherwise.public void addElement(Object aObject, int aFireEventMode) throws IllegalStateException
ALcdModel
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
.
addElement
in interface ILcdModel
addElement
in class ALcdModel
aObject
- the element to be added to this model.aFireEventMode
- the mode for sending out the model change event. This can be FIRE_LATER
or NO_EVENT
.IllegalStateException
- if the element can't be added due to
some database error.ILcdModel.canAddElement(Object)
public void elementChanged(Object aObject, int aFireEventMode) throws IllegalStateException
ALcdModel
This implementation calls TLcdModelChangedEventSupport#elementChanged(Object, int)
.
elementChanged
in interface ILcdModel
elementChanged
in class ALcdModel
aObject
- the element that has changed.aFireEventMode
- the mode for sending out the model change event. This can be FIRE_LATER
or NO_EVENT
.IllegalStateException
- if the element can't be changed due to
some database error.public void removeElement(Object aObject, int aFireEventMode) throws IllegalStateException
ALcdModel
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
.
removeElement
in interface ILcdModel
removeElement
in class ALcdModel
aObject
- the element to be removed from this model.aFireEventMode
- the mode for sending out the model change event. This can be FIRE_LATER
or NO_EVENT
.IllegalStateException
- if the element can't be removed due to
some database error.ILcdModel.canRemoveElement(Object)
public void removeAllElements(int aFireEventMode) throws IllegalStateException
ALcdModel
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.
removeAllElements
in interface ILcdModel
removeAllElements
in class ALcdModel
aFireEventMode
- the mode for sending out the model change event. This can be FIRE_LATER
or NO_EVENT
.IllegalStateException
- if the elements can't be removed due to
some database error.public ILcdAutoCloseableEnumeration elements() throws IllegalStateException
ILcdModel
elements
in interface ILcdModel
IllegalStateException
- if the elements can't be retrieved due to
some database error.public ILcdBounds getBounds()
ILcdBounded
ILcdBounds
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 ILcdBounded
ILcdBounds
by which the geometry of this ILcdBounded
object
is bounded.public int applyOnInteract2DBounds(ILcdBounds aBounds, boolean aStrictOverlap, ILcdFunction aFunctionToApply, double aPrecisionX, double aPrecisionY) throws IllegalStateException
ILcd2DBoundsIndexedModel
false
.applyOnInteract2DBounds
in interface ILcd2DBoundsIndexedModel
aBounds
- 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.IllegalStateException
public int applyOnInteract2DBounds(ILcdBounds aBounds, boolean aStrictInteract, ILcdFunction aFunctionToApply, double aPrecisionX, double aPrecisionY, double aMinSizeX, double aMinSizeY, boolean aIncludePoints) throws IllegalStateException
ILcd2DBoundsInteractable
false
for an element it was applied on.applyOnInteract2DBounds
in interface ILcd2DBoundsIndexedModel
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.IllegalStateException
- if the elements can't be retrieved due to
some database error.public void dispose()
TLcdDatabaseModel
, thus releasing
the JDBC system resources that it is using.dispose
in interface ILcdModel
dispose
in interface ILcdDisposable
dispose
in class ALcdModel
ALcdModel.setModelDisposer(Consumer)