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 <[email protected]>
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 {
