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: Edit javadoc for `MapLayer`. Note: we omit the message saying that this class may change in future version; this is the case of anything in "internal" packages.
Date Tue, 04 Feb 2020 22:51:25 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 2eafd3c  Edit javadoc for `MapLayer`. Note: we omit the message saying that this
class may change in future version; this is the case of anything in "internal" packages.
2eafd3c is described below

commit 2eafd3c346aecbb035dba69535537eaa9b943eac
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Tue Feb 4 23:50:21 2020 +0100

    Edit javadoc for `MapLayer`. Note: we omit the message saying that this class may change
in future version; this is the case of anything in "internal" packages.
---
 .../java/org/apache/sis/internal/map/MapLayer.java | 158 +++++++++++++--------
 1 file changed, 98 insertions(+), 60 deletions(-)

diff --git a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
index 3373907..f2be4e7 100644
--- a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
+++ b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
@@ -17,54 +17,84 @@
 package org.apache.sis.internal.map;
 
 import java.util.Objects;
+import org.opengis.style.Style;
+import org.opengis.feature.Feature;
+import org.opengis.coverage.Coverage;
 import org.apache.sis.storage.Query;
 import org.apache.sis.storage.Resource;
-import org.opengis.style.Style;
+import org.apache.sis.storage.DataSet;
+import org.apache.sis.storage.Aggregate;
 
 
 /**
  * Data (resource) associated to visual representation (symbology).
- * Layers are the key elements of a map: they link datas (given by a {@link Resource})
- * to their visual representation (defined by a {@link Style}).
+ * Layers are the key elements of a map: they link data (given by {@link Resource}s) or a
subset of
+ * those data (filtered by {@link Query}) to their visual representation (defined by {@link
Style}s).
  * The visual appearance of a layer should be similar with any rendering engine.
  * Some details may very because of different rendering strategies for label placements,
2D or 3D,
- * but the fundamentals aspect of each {@link org.opengis.feature.Feature} or
- * {@link org.opengis.coverage.Coverage} should be unchanged.
- *
- * <p>
- * NOTE: this class is a first draft subject to modifications.
- * </p>
+ * but the fundamentals aspect of each {@link Feature} or {@link Coverage} should be unchanged.
  *
  * @author  Johann Sorel (Geomatys)
- * @version 2.0
- * @since   2.0
+ * @version 1.1
+ * @since   1.1
  * @module
  */
 public class MapLayer extends MapItem {
-
-    /** Identifies a change in the layer resource. */
+    /**
+     * The {@value} property name, used for notifications about changes in map layer resource.
+     * The resource provides the data to be rendered.
+     * Associated values should be instances of {@link DataSet} or {@link Aggregate}.
+     *
+     * @see #getResource()
+     * @see #setResource(Resource)
+     */
     public static final String RESOURCE_PROPERTY = "resource";
-    /** Identifies a change in the layer style. */
-    public static final String STYLE_PROPERTY = "style";
-    /** Identifies a change in the layer query. */
+
+    /**
+     * The {@value} property name, used for notifications about changes in map layer query.
+     * The query can filter resource data for rendering only a subset of available data.
+     * Associated values are instances of {@link Query}.
+     *
+     * @see #getQuery()
+     * @see #setQuery(Query)
+     */
     public static final String QUERY_PROPERTY = "query";
 
     /**
-     * Data to be rendered.
+     * The {@value} property name, used for notifications about changes in map layer style.
+     * The style specifies the appearance of the filtered data to be rendered.
+     * Associated values are instances of {@link Style}.
+     *
+     * @see #getStyle()
+     * @see #setStyle(Style)
      */
-    private Resource resource;
+    public static final String STYLE_PROPERTY = "style";
 
     /**
-     * Visual representation of data.
+     * Data to be rendered, or {@code null} if unavailable.
+     *
+     * @see #RESOURCE_PROPERTY
+     * @see #getResource()
      */
-    private Style style;
+    private Resource resource;
 
     /**
-     * User defined query.
+     * Filter for rendering a subset of available data, or {@code null} if none.
+     *
+     * @see #QUERY_PROPERTY
+     * @see #getQuery()
      */
     private Query query;
 
     /**
+     * Visual representation of data, or {@code null} if none.
+     *
+     * @see #STYLE_PROPERTY
+     * @see #getStyle()
+     */
+    private Style style;
+
+    /**
      * Constructs an initially empty map layer.
      *
      * @todo Expect {@code Resource} and {@code Style} in argument, for discouraging
@@ -75,11 +105,12 @@ public class MapLayer extends MapItem {
 
     /**
      * Returns the data (resource) represented by this layer.
-     * The resource should be a {@link org.apache.sis.storage.DataSet},
-     * but {@link org.apache.sis.storage.Aggregate} are also accepted.
-     * The behavior in such case depends on the rendering engine.
+     * The resource should be a {@link DataSet}, but {@link Aggregate} is also accepted.
+     * The behavior in aggregate case depends on the rendering engine.
      *
      * @return data to be rendered, or {@code null} is unavailable.
+     *
+     * @see #RESOURCE_PROPERTY
      */
     public Resource getResource() {
         return resource;
@@ -91,64 +122,71 @@ public class MapLayer extends MapItem {
      * that the layer should have existed but is unavailable for an unspecified reason.
      * This case may happen with processing or distant services resources.
      *
-     * @param  resource  the new data, or {@code null} if unavailable.
+     * <p>The given resource should be a {@link DataSet} or an {@link Aggregate} of
data sets.
+     * However this base class does not enforce those types. Subclasses may restrict the
set
+     * of resource types accepted by this method.</p>
+     *
+     * @param  newValue  the new data, or {@code null} if unavailable.
      */
-    public void setResource(Resource resource) {
-        if (!Objects.equals(this.resource, resource)) {
-            Resource old = this.resource;
-            this.resource = resource;
-            firePropertyChange(RESOURCE_PROPERTY, old, resource);
+    public void setResource(final Resource newValue) {
+        final Resource oldValue = resource;
+        if (!Objects.equals(oldValue, newValue)) {
+            resource = newValue;
+            firePropertyChange(RESOURCE_PROPERTY, oldValue, newValue);
         }
     }
 
     /**
-     * Returns the visual appearance of the data.
-     * If the style is undefined, the behavior is left to the rendering engine.
-     * It is expected that a default style should be used.
+     * Returns the filter for reducing the amount of data to render. Query filters can be
+     * specified for rendering a smaller amount of data than what the resource can provide.
+     * If the query is undefined, then all data will be rendered.
      *
-     * @return description of data visual appearance, or {@code null} if unspecified.
+     * @return filter for reducing data, or {@code null} for rendering all data.
+     *
+     * @see #QUERY_PROPERTY
      */
-    public Style getStyle() {
-        return style;
+    public Query getQuery() {
+        return query;
     }
 
     /**
-     * Sets the visual appearance of the data.
+     * Sets a filter for reducing the amount of data to render. If this method is never invoked,
the default value
+     * is {@code null}. If the given value is different than the previous value, then a change
event is sent to all
+     * listeners registered for the {@value #QUERY_PROPERTY} property.
      *
-     * @param  style  description of data visual appearance, or {@code null} if unspecified.
+     * @param  newValue  filter for reducing data, or {@code null} for rendering all data.
      */
-    public void setStyle(Style style) {
-        if (!Objects.equals(this.style, style)) {
-            Style old = this.style;
-            this.style = style;
-            firePropertyChange(STYLE_PROPERTY, old, style);
+    public void setQuery(final Query newValue) {
+        final Query oldValue = query;
+        if (!Objects.equals(oldValue, newValue)) {
+            query = newValue;
+            firePropertyChange(QUERY_PROPERTY, oldValue, newValue);
         }
     }
 
     /**
-     * Returns the definition query for this layer.If no definition
-     * query has been defined {@code null} is returned.
-     * @return query, or {@code null} if unspecified.
+     * Returns the visual appearance of the data.
+     * If the style is undefined, the behavior is left to the rendering engine.
+     * It is expected that a default style should be used.
+     *
+     * @return description of data visual appearance, or {@code null} if unspecified.
      */
-    public Query getQuery() {
-        return query;
+    public Style getStyle() {
+        return style;
     }
 
     /**
-     * Sets a filter query for this layer.
-     *
-     * <p>
-     * Query filters should be used to reduce searched or displayed resource
-     * when rendering or analyzing this layer.
-     * </p>
+     * Sets the visual appearance of the data. If this method is never invoked, the default
value is {@code null}.
+     * If the given value is different than the previous value, then a change event is sent
to all listeners
+     * registered for the {@value #STYLE_PROPERTY} property.
      *
-     * @param query the query for this layer, or {@code null} if unavailable.
+     * @param  newValue  description of data visual appearance, or {@code null} if unspecified.
      */
-    public void setQuery(Query query) {
-        if (!Objects.equals(this.query, query)) {
-            Query old = this.query;
-            this.query = query;
-            firePropertyChange(QUERY_PROPERTY, old, query);
+    public void setStyle(final Style newValue) {
+        final Style oldValue = style;
+        if (!Objects.equals(oldValue, newValue)) {
+            style = newValue;
+            firePropertyChange(STYLE_PROPERTY, oldValue, newValue);
         }
     }
 }


Mime
View raw message