sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] branch geoapi-4.0 updated: Javadoc.
Date Wed, 05 Feb 2020 12:03:45 GMT
This is an automated email from the ASF dual-hosted git repository.

desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git


The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
     new dc3f688  Javadoc.
dc3f688 is described below

commit dc3f6884c2efc2330c96b6db64555fd3dcb7386c
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Wed Feb 5 13:01:49 2020 +0100

    Javadoc.
---
 .../java/org/apache/sis/internal/map/MapItem.java  |  5 +-
 .../org/apache/sis/internal/map/MapLayers.java     | 63 ++++++++++++----------
 .../org/apache/sis/internal/map/Presentation.java  | 10 ++--
 3 files changed, 46 insertions(+), 32 deletions(-)

diff --git a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
index b432dcd..09cdeae 100644
--- a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
+++ b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
@@ -29,7 +29,7 @@ import org.apache.sis.util.ArraysExt;
 
 
 /**
- * Parent class of all map elements.
+ * Parent class of all elements having a graphical representation on the map.
  * This base class does not make any assumption about how this {@code MapItem} will be rendered;
  * the actual feature or coverage data, together with styling information, are provided by
subclasses.
  * A {@code MapItem} contains the following properties:
@@ -45,6 +45,9 @@ import org.apache.sis.util.ArraysExt;
  * <h2>Synchronization</h2>
  * {@code MapItem} instances are not thread-safe. Synchronization, if desired, is caller
responsibility.
  *
+ * @todo Consider renaming as {@code Graphic} for emphasis that this is a graphical representation
of something.
+ *       This would be consistent with legacy GO-1 specification (even if retired, it still
have worthy material).
+ *
  * @author  Johann Sorel (Geomatys)
  * @version 1.1
  * @since   1.1
diff --git a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayers.java b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayers.java
index 0f218e1..c39f3c7 100644
--- a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayers.java
+++ b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayers.java
@@ -21,46 +21,53 @@ import java.util.List;
 import java.util.Objects;
 import org.opengis.geometry.Envelope;
 import org.opengis.referencing.crs.CoordinateReferenceSystem;
+import org.apache.sis.storage.DataSet;
 
 
 /**
- * A collection of layers.
- * Layers are used to regroup similar layers under a same node.
+ * A group of graphic elements to display together.
+ * {@code MapLayers} can be used for grouping related layers under a same node.
  * This allows global actions, like {@linkplain #setVisible(boolean) hiding}
  * background layers in one call.
  *
- * A map context which is the name given to the root map item node contains
- * all layers to display (given by the {@link #getComponents() group components})
- * and defines the {@linkplain #getAreaOfInterest() area of interest} which should be zoomed
by default
- * when the map is rendered.
+ * <p>A {@code MapLayers} is often (but not necessarily) the root node of the tree
of all graphic elements to
+ * draw on the map. Those elements are typically {@link MapLayer} instances, but more generic
{@link MapItem}
+ * instances are also accepted. Those elements are listed by {@link #getComponents()} in
<var>z</var> order.
+ * In addition, {@code MapLayers} defines the {@linkplain #getAreaOfInterest() area of interest}
+ * which should be zoomed by default when the map is rendered.</p>
  *
- * <p>
- * NOTE: this class is a first draft subject to modifications.
- * TODO : components events
- * </p>
+ * @todo Despite its name, this class is not a container of {@link MapLayer}s since it accepts
more generic objects.
+ *       Consider renaming as {@code Group} or {@code GraphicAggregate}.
  *
  * @author  Johann Sorel (Geomatys)
- * @version 2.0
- * @since   2.0
+ * @version 1.1
+ * @since   1.1
  * @module
  */
 public class MapLayers extends MapItem {
-
-    /** Identifies a change in the map context area of interest. */
+    /**
+     * The {@value} property name, used for notifications about changes in area of interest.
+     * Associated values are instances of {@link Envelope}.
+     *
+     * @see #getAreaOfInterest()
+     * @see #setAreaOfInterest(Envelope)
+     */
     public static final String AREAOFINTEREST_PROPERTY = "areaOfInterest";
 
     /**
-     * The components in this group.
+     * The components in this group, or an empty list if none.
+     *
+     * @todo Should be an observable list with event sent when an element is added/removed/modified.
      */
     private final List<MapItem> components;
 
     /**
-     * The area of interest.
+     * The area of interest, or {@code null} is unspecified.
      */
     private Envelope areaOfInterest;
 
     /**
-     * Creates an initially empty map layers.
+     * Creates an initially empty group of graphic elements.
      */
     public MapLayers() {
         components = new ArrayList<>();
@@ -83,8 +90,8 @@ public class MapLayers extends MapItem {
     }
 
     /**
-     * Returns the map area to show by default. This is not necessarily the
-     * {@linkplain org.apache.sis.storage.DataSet#getEnvelope() envelope of data}
+     * Returns the map area to show by default.
+     * This is not necessarily the {@linkplain DataSet#getEnvelope() envelope of data}
      * since one may want to zoom in a different spatiotemporal area.
      *
      * <p>The {@linkplain org.apache.sis.geometry.GeneralEnvelope#getCoordinateReferenceSystem()
envelope CRS}
@@ -94,7 +101,7 @@ public class MapLayers extends MapItem {
      *
      * @return map area to show by default, or {@code null} is unspecified.
      *
-     * @see org.apache.sis.storage.DataSet#getEnvelope()
+     * @see DataSet#getEnvelope()
      */
     public Envelope getAreaOfInterest() {
         return areaOfInterest;
@@ -102,16 +109,16 @@ public class MapLayers extends MapItem {
 
     /**
      * Sets the map area to show by default.
-     * The given envelope is not necessarily related to the data contained in the map context.
-     * It may be wider, small and in a different {@link CoordinateReferenceSystem}.
+     * The given envelope is not necessarily related to the data contained in this group.
+     * It may be wider, or smaller, and in a different {@link CoordinateReferenceSystem}.
      *
-     * @param  aoi  new map area to show by default, or {@code null} is unspecified.
+     * @param  newValue  new map area to show by default, or {@code null} is unspecified.
      */
-    public void setAreaOfInterest(Envelope aoi) {
-        if (!Objects.equals(areaOfInterest, aoi)) {
-            Envelope old = areaOfInterest;
-            areaOfInterest = aoi;
-            firePropertyChange(AREAOFINTEREST_PROPERTY, old, aoi);
+    public void setAreaOfInterest(final Envelope newValue) {
+        final Envelope oldValue = areaOfInterest;
+        if (!Objects.equals(oldValue, newValue)) {
+            areaOfInterest = newValue;
+            firePropertyChange(AREAOFINTEREST_PROPERTY, oldValue, newValue);
         }
     }
 }
diff --git a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/Presentation.java
b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/Presentation.java
index 065c7ed..92ee82f 100644
--- a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/Presentation.java
+++ b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/Presentation.java
@@ -35,9 +35,13 @@ import org.opengis.feature.Feature;
  * NOTE: this class is a first draft subject to modifications.
  * </p>
  *
- * @author Johann Sorel (Geomatys)
- * @version 2.0
- * @since   2.0
+ * @todo Maybe should be not be part of public API. This functionality could be done with
a
+ *       {@link MapItem} subclasses containing only a {@link Feature} or {@code GridCoverage}
+ *       instance, as opposed to {@link MapLayer} containing {@code Resource}.
+ *
+ * @author  Johann Sorel (Geomatys)
+ * @version 1.1
+ * @since   1.1
  * @module
  */
 public abstract class Presentation {


Mime
View raw message