sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1828090 - in /sis/branches/JDK8: core/sis-portrayal/ core/sis-portrayal/src/main/java/org/apache/sis/internal/map/ ide-project/NetBeans/nbproject/
Date Sat, 31 Mar 2018 09:58:13 GMT
Author: desruisseaux
Date: Sat Mar 31 09:58:13 2018
New Revision: 1828090

URL: http://svn.apache.org/viewvc?rev=1828090&view=rev
Log:
Javadoc on new portrayal classes.

Added:
    sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/package-info.java
  (with props)
Modified:
    sis/branches/JDK8/core/sis-portrayal/pom.xml
    sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapContext.java
    sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapGroup.java
    sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
    sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
    sis/branches/JDK8/ide-project/NetBeans/nbproject/project.xml

Modified: sis/branches/JDK8/core/sis-portrayal/pom.xml
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-portrayal/pom.xml?rev=1828090&r1=1828089&r2=1828090&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-portrayal/pom.xml (original)
+++ sis/branches/JDK8/core/sis-portrayal/pom.xml Sat Mar 31 09:58:13 2018
@@ -42,7 +42,7 @@
   <description>
   <!-- Left alignment because this description will be copied in META-INF/MANIFEST.MF
        The leading space after the first line is necessary for proper formatting. -->
-Symbology, map and rendering engine representation.
+Symbology and map representations, together with a rendering engine for display.
   </description>
 
 

Modified: sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapContext.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapContext.java?rev=1828090&r1=1828089&r2=1828090&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapContext.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapContext.java
[UTF-8] Sat Mar 31 09:58:13 2018
@@ -19,47 +19,61 @@ package org.apache.sis.internal.map;
 import org.opengis.geometry.Envelope;
 import org.opengis.referencing.crs.CoordinateReferenceSystem;
 
+
 /**
- * A map context is the root node of a map.
+ * Root node of a map.
  *
- * The map context contains all displayed layers like a MapGroup and
- * defines the area of interest which should be focused by default when
- * displayed.
+ * The map context 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>
- * NOTE : this class is a first draft subject to modifications.
+ * NOTE: this class is a first draft subject to modifications.
  * </p>
  *
- * @author Johann Sorel (Geomatys)
- * @since 1.0
+ * @author  Johann Sorel (Geomatys)
+ * @version 1.0
+ * @since   1.0
  * @module
  */
 public class MapContext extends MapGroup {
+    /**
+     * The area of interest.
+     */
+    private Envelope areaOfInterest;
 
-    private Envelope aoi;
+    /**
+     * Creates an initially empty map context.
+     */
+    public MapContext() {
+    }
 
     /**
-     * Returns the map default area of interest.
+     * Returns the map area to show by default. This is not necessarily the
+     * {@linkplain org.apache.sis.storage.DataSet#getEnvelope() envelope of data}
+     * since one may want to zoom in a different spatio-temporal area.
+     *
+     * <p>The {@linkplain org.apache.sis.geometry.GeneralEnvelope#getCoordinateReferenceSystem()
envelope CRS}
+     * defines the map projection to use for rendering the map. It may be different than
the CRS of the data.
+     * The returned envelope may have {@linkplain org.apache.sis.geometry.GeneralEnvelope#isAllNaN()
all its
+     * coordinates set to NaN} if only the {@link CoordinateReferenceSystem} is specified.</p>
      *
-     * If the returned envelope is empty, at least the {@link CoordinateReferenceSystem}
-     * defined should be used for displaying the map.
+     * @return map area to show by default, or {@code null} is unspecified.
      *
-     * @return map area of interest, may be null
+     * @see org.apache.sis.storage.DataSet#getEnvelope()
      */
     public Envelope getAreaOfInterest() {
-        return aoi;
+        return areaOfInterest;
     }
 
     /**
-     * Set map default area of interest.
-     *
-     * The given envelope is unrelated to the data contained in the map context.
+     * 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}.
      *
-     * @param aoi map area of interest, may be null
+     * @param  aoi  new map area to show by default, or {@code null} is unspecified.
      */
     public void setAreaOfInterest(Envelope aoi) {
-        this.aoi = aoi;
+        areaOfInterest = aoi;
     }
-
 }

Modified: sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapGroup.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapGroup.java?rev=1828090&r1=1828089&r2=1828090&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapGroup.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapGroup.java
[UTF-8] Sat Mar 31 09:58:13 2018
@@ -19,43 +19,48 @@ package org.apache.sis.internal.map;
 import java.util.ArrayList;
 import java.util.List;
 
+
 /**
- * A map group is collection of layers.
- *
- * <p>
+ * A collection of layers.
  * Groups are used in map contexts to regroup similar layers under a same node.
- * This allows global actions, like hiding background layers in one call.
- * </p>
+ * This allows global actions, like {@linkplain #setVisible(boolean) hiding}
+ * background layers in one call.
  *
  * <p>
- * NOTE : this class is a first draft subject to modifications.
+ * NOTE: this class is a first draft subject to modifications.
  * </p>
  *
- * @author Johann Sorel (Geomatys)
- * @since 1.0
+ * @author  Johann Sorel (Geomatys)
+ * @version 1.0
+ * @since   1.0
  * @module
  */
 public class MapGroup extends MapItem {
+    /**
+     * The components in this group.
+     */
+    private final List<MapItem> components;
 
-    private final List<MapItem> components = new ArrayList<>();
+    /**
+     * Creates an initially empty group.
+     */
+    public MapGroup() {
+        components = new ArrayList<>();
+    }
 
     /**
-     * Get the list of layers contained in this group.
+     * Gets the modifiable list of components contained in this group.
+     * The components in the list are presented in rendering order.
+     * This means that the first rendered component, which will be below
+     * all other components on the rendered map, is located at index zero.
      *
-     * <p>
-     * The layers in the list are presented in rendering order.
-     * This means the first rendered layer which will be under all others on the
-     * result map is at index zero.
-     * </p>
+     * <p>The returned list is modifiable: changes in the returned list will
+     * be immediately reflected in this {@code MapGroup}, and conversely.</p>
      *
-     * <p>
-     * The returned list is modifiable.
-     * </p>
-     *
-     * @return List of layers, never null
+     * @return modifiable list of components in this group.
      */
+    @SuppressWarnings("ReturnOfCollectionOrArrayField")
     public List<MapItem> getComponents() {
         return components;
     }
-
 }

Modified: sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java?rev=1828090&r1=1828089&r2=1828090&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
[UTF-8] Sat Mar 31 09:58:13 2018
@@ -19,66 +19,70 @@ package org.apache.sis.internal.map;
 /**
  * Parent class of all map elements.
  *
- *
  * <p>
- * NOTE : this class is a first draft subject to modifications.
+ * NOTE: this class is a first draft subject to modifications.
  * </p>
  *
- * @author Johann Sorel (Geomatys)
- * @since 1.0
+ * @todo Rename {@code MapElement} or {@code Element}?
+ *
+ * @author  Johann Sorel (Geomatys)
+ * @version 1.0
+ * @since   1.0
  * @module
  */
 public abstract class MapItem {
-
+    /**
+     * The title of this map item, for display to the user.
+     */
     private CharSequence title;
+
+    /**
+     * Whether this item should be shown on the map.
+     */
     private boolean visible = true;
 
     /**
-     * Only used by classes in this package
+     * Only used by classes in this package.
      */
     MapItem() {
-
     }
 
     /**
      * Returns the title of this map item.
+     * This title should be user friendly and may be an {@link org.opengis.util.InternationalString}.
+     * It shall not be used as an identifier.
      *
-     * This title should be user friendly and may be a InternationalString.
-     * It must not be used as an identifier.
-     *
-     * @return user friendly title, may be null
+     * @return title to be shown to the user, or {@code null} if none.
      */
     public CharSequence getTitle() {
         return title;
     }
 
     /**
-     * Set map item title.
+     * Sets a new title for this map item.
      *
-     * @param title user friendly title, can be null
+     * @param  title  title to be shown to the user, or {@code null} if none.
      */
     public void setTitle(CharSequence title) {
         this.title = title;
     }
 
     /**
-     * Return visibility state of this map item.
+     * Return whether this item should be shown on the map.
      *
-     * @return true if item is visible
+     * @return {@code true} if this item is visible.
      */
     public boolean isVisible() {
         return visible;
     }
 
     /**
-     * Set visibility state of this item.
-     * In the case of a MapGroup, all components should be hidden too when
-     * rendering.
+     * Sets whether this item should be shown on the map.
+     * If this item is a {@link MapGroup}, then hiding this group should hide all components
in this group.
      *
-     * @param visible set to false to hide item and all it's components
+     * @param visible {@code false} to hide this item and all it's components.
      */
     public void setVisible(boolean visible) {
         this.visible = visible;
     }
-
 }

Modified: sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java?rev=1828090&r1=1828089&r2=1828090&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
[UTF-8] Sat Mar 31 09:58:13 2018
@@ -19,80 +19,86 @@ package org.apache.sis.internal.map;
 import org.apache.sis.storage.Resource;
 import org.opengis.style.Style;
 
+
 /**
- * A map layer is an association of a {@link Resource} and a {@link Style}.
+ * 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}).
+ * 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>
- * Map layers are the key elements of a map, they defined the relationship
- * between datas and a symbology. The visual result of a layer should be similar
- * for any rendering engine. The result may be different because of different
- * rendering strategies for label placements, 2D or 3D but the fundamentals
- * representation of each Feature or Coverage should be unchanged.
+ * NOTE: this class is a first draft subject to modifications.
  * </p>
  *
- * <p>
- * NOTE : this class is a first draft subject to modifications.
- * </p>
- *
- * @author Johann Sorel (Geomatys)
- * @since 1.0
+ * @author  Johann Sorel (Geomatys)
+ * @version 1.0
+ * @since   1.0
  * @module
  */
 public final class MapLayer {
-
+    /**
+     * Data to be rendered.
+     */
     private Resource resource;
+
+    /**
+     * Visual representation of data.
+     */
     private Style style;
 
     /**
-     * Returns layer base resource.
+     * Constructs an initially empty map layer.
      *
-     * <p>
-     * The resource should be a DataSet but may still be a Aggregate.
+     * @todo Expect {@code Resource} and {@code Style} in argument, for discouraging
+     *       the use of {@code MapLayer} with null resource and null style?
+     */
+    public MapLayer() {
+    }
+
+    /**
+     * 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.
-     * </p>
      *
-     * @return rendered resource
+     * @return data to be rendered, or {@code null} is unavailable.
      */
     public Resource getResource() {
         return resource;
     }
 
     /**
-     * Set layer resource.
-     *
-     * <p>
-     * The resource should never be null, still the null case is tolerate
-     * to indicate the layer should have exist but is unavailable for an indeterminate
-     * reason. This case may happen for processed or distant services resources.
-     * </p>
+     * Sets the data (resource) to be rendered.
+     * The resource should never be null, still the null case is tolerated to indicate
+     * 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 , may be null
+     * @param  resource  the new data, or {@code null} if unavailable.
      */
     public void setResource(Resource resource) {
         this.resource = resource;
     }
 
     /**
-     * Returns the layer style.
-     *
-     * <p>
+     * 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.
-     * </p>
      *
-     * @return layer style, may be null
+     * @return description of data visual appearance, or {@code null} if unspecified.
      */
     public Style getStyle() {
         return style;
     }
 
     /**
-     * Set layer style.
+     * Sets the visual appearance of the data.
      *
-     * @param style layer style, can be null
+     * @param  style  description of data visual appearance, or {@code null} if unspecified.
      */
     public void setStyle(Style style) {
         this.style = style;
     }
-
 }

Added: sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/package-info.java?rev=1828090&view=auto
==============================================================================
--- sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/package-info.java
(added)
+++ sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/package-info.java
[UTF-8] Sat Mar 31 09:58:13 2018
@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+/**
+ * Symbology and map representations, together with a rendering engine for display.
+ * The {@linkplain org.apache.sis.internal.map.MapContext map context} is the root node of
a map.
+ *
+ * <p><b>WARNING:</b> this package is work in progress and is not yet part
of public API.
+ * Some classes in this package will move to public API after we gained enough confidence
+ * about their stability.</p>
+ *
+ * @todo Since everything is about maps in this package, should we omit the {@code Map} prefix
in class names?
+ *
+ * @author  Johann Sorel (Geomatys)
+ * @version 1.0
+ * @since   1.0
+ * @module
+ */
+package org.apache.sis.internal.map;

Propchange: sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/package-info.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK8/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/package-info.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain;charset=UTF-8

Modified: sis/branches/JDK8/ide-project/NetBeans/nbproject/project.xml
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/ide-project/NetBeans/nbproject/project.xml?rev=1828090&r1=1828089&r2=1828090&view=diff
==============================================================================
--- sis/branches/JDK8/ide-project/NetBeans/nbproject/project.xml (original)
+++ sis/branches/JDK8/ide-project/NetBeans/nbproject/project.xml Sat Mar 31 09:58:13 2018
@@ -27,6 +27,7 @@
                 <root id="src.webapp.dir" name="Web application"/>
                 <root id="src.javafx.dir" name="JavaFX"/>
                 <root id="src.console.dir" name="Console"/>
+                <root id="src.portrayal.dir" name="Portrayal"/>
                 <root id="src.earth-obs.dir" name="Earth observation"/>
                 <root id="src.geotiff.dir" name="GeoTIFF"/>
                 <root id="src.netcdf.dir" name="NetCDF"/>
@@ -35,7 +36,6 @@
                 <root id="src.storage.dir" name="Storage"/>
                 <root id="src.feature.dir" name="Feature"/>
                 <root id="src.raster.dir" name="Raster"/>
-                <root id="src.portrayal.dir" name="Portrayal"/>
                 <root id="src.referencing.dir" name="Referencing"/>
                 <root id="src.ref-by-id.dir" name="Referencing by identifiers"/>
                 <root id="src.metadata.dir" name="Metadata"/>
@@ -48,6 +48,7 @@
                 <root id="test.webapp.dir" name="Test web application"/>
                 <root id="test.javafx.dir" name="Test JavaFX"/>
                 <root id="test.console.dir" name="Test Console"/>
+                <root id="test.portrayal.dir" name="Test Portrayal"/>
                 <root id="test.earth-obs.dir" name="Test Earth observation"/>
                 <root id="test.geotiff.dir" name="Test GeoTIFF"/>
                 <root id="test.netcdf.dir" name="Test NetCDF"/>
@@ -56,7 +57,6 @@
                 <root id="test.storage.dir" name="Test Storage"/>
                 <root id="test.feature.dir" name="Test Feature"/>
                 <root id="test.raster.dir" name="Test Raster"/>
-                <root id="test.portrayal.dir" name="Test Portrayal"/>
                 <root id="test.referencing.dir" name="Test Referencing"/>
                 <root id="test.ref-by-id.dir" name="Test Referencing by identifiers"/>
                 <root id="test.metadata.dir" name="Test Metadata"/>



Mime
View raw message