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"/>
