Package com.luciad.format.database

Class TLcdDatabaseModel

java.lang.Object
com.luciad.model.ALcdModel
com.luciad.format.database.TLcdDatabaseModel
All Implemented Interfaces:
ILcd2DBoundsIndexedModel, ILcd2DBoundsInteractable, ILcdModel, ILcdBounded, ILcdDisposable, Serializable, AutoCloseable
public class TLcdDatabaseModel extends ALcdModel implements ILcd2DBoundsIndexedModel
This class presents the contents of a database table containing geometries, as an 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.

See Also:

  • Method Details

    • setClassTraceOn

      public static void setClassTraceOn(boolean aClassTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for all instances of this class. If the argument is true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.
      Parameters:
      aClassTraceOn - if true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

    • isClassTraceOn

      public static boolean isClassTraceOn()
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Returns true if tracing is enabled for this class.
      Returns:
      true if tracing is enabled for this class, false otherwise.

    • isTraceOn

      public boolean isTraceOn()
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Returns true if tracing is enabled for this class.
      Overrides:
      isTraceOn in class ALcdModel
      Returns:
      true if tracing is enabled for this class, false otherwise.

    • setModelDescriptor

      public void setModelDescriptor(ILcdModelDescriptor aModelDescriptor)
      Description copied from class: ALcdModel
      Sets the model descriptor providing meta information about this model and its elements.
      Overrides:
      setModelDescriptor in class ALcdModel
      Parameters:
      aModelDescriptor - a data descriptor for this model. Must be a ILcdDatabaseModelDescriptor.
      See Also:

    • setMaxCacheSize

      public void setMaxCacheSize(int aMaxCacheSize)

    • getMaxCacheSize

      public int getMaxCacheSize()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getAutoCommit

      public boolean getAutoCommit()
      Gets the current auto-commit state.
      Returns:
      the current state of auto-commit mode.

    • isDirty

      public boolean isDirty()
      Indicates whether this model contains any uncommitted changes.
      Returns:
      true if there are uncommitted changes, false otherwise.
      See Also:

    • commit

      public void commit() throws IOException
      Makes all changes made since the previous commit/rollback permanent.

      This method doesn't fire change events, because the model itself contains all changes.
      You still have to take a write lock though: 

      
   try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.writeLock(model)) {
       model.commit();
   }
      Throws:
      IOException - if the elements can't be retrieved due to some database error.
      See Also:

    • rollback

      public 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.

      For most databases (Postgresql, Oracle, MSSQL, GeoPackage), this method keeps domain object instances, and they are filled with new data from the server on the next model query.

      For some databases however (Informix, DB2), this method also throws away domain object instances, so you will receive new instances for the elements that were in cache. This may cause flickering on the screen, or layer selection loss.

      This method doesn't actively fire change events for potentially changed objects.
      The changes are only visible on the next model query, you can trigger a model query using ALcdModel.allElementsChanged(int): 

      
   try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.writeLock(model)) {
       model.rollback();
       model.allElementsChanged(FIRE_LATER);
   } finally {
       model.fireCollectedModelChanges();
   }
      See Also:

    • clearCache

      public 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.

      For most databases (Postgresql, Oracle, MSSQL, GeoPackage), this method keeps domain object instances, and they are filled with new data from the server on the next model query.

      For some databases however (Informix, DB2), this method also throws away domain object instances, so you will receive new instances for the elements that were in cache. This may cause flickering on the screen, or layer selection loss.

      This method doesn't actively fire change events for potentially changed objects.
      The changes are only visible on the next model query, you can trigger a model query using ALcdModel.allElementsChanged(int): 

      
   try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.writeLock(model)) {
       model.clearCache();
       model.allElementsChanged(FIRE_LATER);
   } finally {
       model.fireCollectedModelChanges();
   }
      See Also:

    • refresh

      public void refresh()
      Re-retrieves all cached elements (domain objects) from the database and retrieves elements that have been added to the database.

      The cached elements themselves are changed in-place: their instances are kept.

      • Prepares model change events for elements that have changed on the database.
      • Prepares model remove events for elements that were removed on the database.
      • Picks up elements that have been added to the database. Note that if the bounds were set in the database properties only elements that lie within those bounds will be picked up.

      Notes:

      • This method does not take a write lock and fires events.
      • Make sure to invoke it from the EDT, take the proper lock and fire collected model changes afterwards.

         try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.writeLock(model)) {
       model.refresh();
   } finally {
       model.fireCollectedModelChanges();
   }

      Limitation: this method is not implemented for Informix, DB2 and SpatiaLite databases.

      Since:
      2020.1

    • elements

      public ILcdAutoCloseableEnumeration elements(Enumeration aKeyEnumeration) throws IOException
      Retrieves the geometries with the given keys.
      Parameters:
      aKeyEnumeration - the Enumeration of the keys of objects to retrieve.
      Returns:
      an ILcdAutoCloseableEnumeration of objects with the given keys.
      Throws:
      IOException

    • canAddElement

      public boolean canAddElement(Object aObject)
      Description copied from class: ALcdModel
      Returns 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.

      Specified by:
      canAddElement in interface ILcdModel
      Overrides:
      canAddElement in class ALcdModel
      Parameters:
      aObject - the element to be verified.
      Returns:
      true if the specified element can be added to this model, false otherwise.

    • canRemoveElement

      public boolean canRemoveElement(Object aObject)
      Description copied from class: ALcdModel
      Returns 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.

      Specified by:
      canRemoveElement in interface ILcdModel
      Overrides:
      canRemoveElement in class ALcdModel
      Parameters:
      aObject - the element to be verified.
      Returns:
      true if the specified element can be removed from this model, false otherwise.

    • addElement

      public void addElement(Object aObject, int aFireEventMode) throws IllegalStateException
      Description copied from class: ALcdModel
      Adds the specified element to this model.

      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.

      Specified by:
      addElement in interface ILcdModel
      Overrides:
      addElement in class ALcdModel
      Parameters:
      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.
      Throws:
      IllegalStateException - if the element can't be added due to some database error.
      See Also:

    • elementChanged

      public void elementChanged(Object aObject, int aFireEventMode) throws IllegalStateException
      Description copied from class: ALcdModel
      Notifies this model that the specified element has changed.

      This implementation calls TLcdModelChangedEventSupport#elementChanged(Object, int).

      Specified by:
      elementChanged in interface ILcdModel
      Overrides:
      elementChanged in class ALcdModel
      Parameters:
      aObject - the element that has changed.
      aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.
      Throws:
      IllegalStateException - if the element can't be changed due to some database error.

    • removeElement

      public void removeElement(Object aObject, int aFireEventMode) throws IllegalStateException
      Description copied from class: ALcdModel
      Removes the specified element from this model. If the specified element is not contained in this model, this method has no effect.

      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.

      Specified by:
      removeElement in interface ILcdModel
      Overrides:
      removeElement in class ALcdModel
      Parameters:
      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.
      Throws:
      IllegalStateException - if the element can't be removed due to some database error.
      See Also:

    • removeAllElements

      public void removeAllElements(int aFireEventMode) throws IllegalStateException
      Description copied from class: ALcdModel
      Removes all elements from this model.

      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.

      Specified by:
      removeAllElements in interface ILcdModel
      Overrides:
      removeAllElements in class ALcdModel
      Parameters:
      aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.
      Throws:
      IllegalStateException - if the elements can't be removed due to some database error.

    • elements

      public ILcdAutoCloseableEnumeration elements() throws IllegalStateException
      Description copied from interface: ILcdModel
      Returns an enumeration over all elements of this model. The order in which the elements are enumerated is unspecified by default.
      Specified by:
      elements in interface ILcdModel
      Returns:
      an enumeration over all elements of this model.
      Throws:
      IllegalStateException - if the elements can't be retrieved due to some database error.

    • getBounds

      public ILcdBounds getBounds()
      Description copied from interface: ILcdBounded
      Returns the 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.

      Specified by:
      getBounds in interface ILcdBounded
      Returns:
      the ILcdBounds by which the geometry of this ILcdBounded object is bounded.

    • applyOnInteract2DBounds

      public int applyOnInteract2DBounds(ILcdBounds aBounds, boolean aStrictOverlap, ILcdFunction aFunctionToApply, double aPrecisionX, double aPrecisionY) throws IllegalStateException
      Description copied from interface: ILcd2DBoundsIndexedModel
      Applies the specified function to all the model elements of which the 2D bounds overlap with the specified bounds. By default, the order in which the function is applied on the elements is unspecified and depends on the implementation.

      The return value of the specified function is used as a stop criterion: the spatial query is interrupted if the function returns false.

      Specified by:
      applyOnInteract2DBounds in interface ILcd2DBoundsIndexedModel
      Parameters:
      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.
      Returns:
      the number of elements to which the ILcdFunction has been applied.
      Throws:
      IllegalStateException

    • applyOnInteract2DBounds

      public int applyOnInteract2DBounds(ILcdBounds aBounds, boolean aStrictInteract, ILcdFunction aFunctionToApply, double aPrecisionX, double aPrecisionY, double aMinSizeX, double aMinSizeY, boolean aIncludePoints) throws IllegalStateException
      Description copied from interface: ILcd2DBoundsInteractable
      Applies the specified function to all the elements of which the 2D bounds overlap with the specified bounds. The order in which the function is applied on the elements is unspecified and depends on the implementation.

      Only elements that have at least the specified minimal size in the x dimension or in the y dimension are considered. This can be useful for quickly eliminating elements that are too small to be visible in a view, for instance. If required, an exception can be made for point elements, which have a size of 0 by 0. They can be forced to be considered, even though they would always be rejected as being too small for any sizes larger than 0.

      The return value of the specified function is used as a stop criterion: the spatial query will be interrupted as soon as the function returns false for an element it was applied on.

      Specified by:
      applyOnInteract2DBounds in interface ILcd2DBoundsIndexedModel
      Specified by:
      applyOnInteract2DBounds in interface ILcd2DBoundsInteractable
      Parameters:
      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.
      Returns:
      the number of elements to which the ILcdFunction has been applied.
      Throws:
      IllegalStateException - if the elements can't be retrieved due to some database error.

    • dispose

      public void dispose()
      Closes the descriptor of this TLcdDatabaseModel, thus releasing the JDBC system resources that it is using.
      Specified by:
      dispose in interface ILcdDisposable
      Specified by:
      dispose in interface ILcdModel
      Overrides:
      dispose in class ALcdModel
      See Also: