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 <[email protected]>
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);
}
}
}
