Mapml 3933 usetiles usefeatures multi

doc/en/user/source/extensions/mapml/installation.rst

@@ -1,3 +1,5 @@
+.. _mapml_installation:
+
 Installation
 --------------------
 
@@ -43,7 +45,7 @@ There is also a MapML-specific global WMS setting in the *MapML Extension* secti
 
 .. figure:: images/mapml_config_wms.png
 
-If the ``Represent multi-layer requests as multiple elements`` is checked (and the configuration is saved), an individually accessible <map-extent> element will be generated for each requested layer.  The default is to represent the layers as a single (hidden) <map-extent>.
+If the ``Represent multi-layer requests as multiple elements`` is checked (and the configuration is saved), in the Layer Preview an individually accessible <map-extent> element will be generated for each requested layer.  When making a WMS request directly include the `mapmlusemultiextents:true` parameter within FORMAT_OPTIONS.  The default is to represent the layers as a single (hidden) <map-extent>.
 
 .. figure:: images/mapml_wms_multi_extent.png
 
@@ -109,7 +111,7 @@ Tile Settings
 Using tiles to access the layer can increase the performance of your web map. This is especially true if there is a tile cache mechanism in use between GeoServer and the browser client.
 
 **Use Tiles**
-  If the "Use Tiles" checkbox is checked, by default the output MapML will define a tile-based reference to the WMS server. Otherwise, an image-based reference will be used.  If one or more of the MapML-defined GridSets is referenced by the layer or layer group in its "Tile Caching" profile, GeoServer will generate tile references instead of generating WMS GetMap URLs in the MapML document body.
+  If you check the "Use Tiles" checkbox and select the MapML format on the Layer Preview page, the output will use tile-based references to the WMS server. For example, if your layer or layer group has a cached tile layer configured, GeoServer will generate tile references (e.g., <map-link rel="tile" tref="...request=GetTile...">) instead of WMS GetMap URLs (e.g., <map-link rel="image" tref="...request=GetMap...">).
 
 Client Requests
 ^^^^^^^^^^^^^^^
@@ -131,7 +133,7 @@ Vector Settings
 MapML supports the serving of vector feature representations of the data.  This results in a smoother user navigation experience, smaller bandwidth requirements, and more options for dynamic styling on the client-side.
 
 **Use Features**
-  If the "Use Features" checkbox is checked, by default the output MapML will define a feature-based reference to the WMS server. Otherwise, an image-based reference will be used.  Note that this option is only available for vector source data.  MapML <map-extent> element with a feature link:
+  If the "Use Features" checkbox is checked, the output MapML on the Layer Preview page will define a feature-based reference to the WMS server. When making WMS request add `mapmlusefeatures:true` to the FORMAT_OPTIONS parameter.  Otherwise, an image-based reference will be used.  Note that this option is only available for vector source data.  MapML <map-extent> element with a feature link:
 
 .. code-block:: html
 
@@ -146,7 +148,7 @@ MapML supports the serving of vector feature representations of the data.  This
       <map-link tref="http://localhost:8080/geoserver/tiger/wms?format_options=mapmlfeatures:true&amp;request=GetMap&amp;crs=MapML:WGS84&amp;bbox={xmin},{ymin},{xmax},{ymax}&amp;format=text/mapml&amp;language=en&amp;version=1.3.0&amp;transparent=true&amp;service=WMS&amp;layers=poi&amp;width={w}&amp;styles=&amp;height={h}" rel="features"/>
     </map-extent>
 
-When both "Use Tiles" and "Use Features" are checked, the MapML extension will request tiled maps in ``text/mapml`` format.
+When both "Use Tiles" and "Use Features" are set in the FORMAT_OPTIONS parameter (`mapmlusefeatures:true;mapmlusetiles:true`), the MapML extension will request tiled maps in ``text/mapml`` format.
 The contents of the tiles will be clipped to the requested area, and feature attributes will be skiipped, as the MapML client cannot leverage them for the moment.
 
 
@@ -245,11 +247,11 @@ WMS GetMap considerations
 
 By default, each layer/style pair that is requested via the GetMap parameters is composed into a single <map-extent>...<map-link tref="...">...</map-extent> structure as exemplified above.  
 
-If the 'Represent multi-layer requests as multiple elements' checkbox from the global WMS Settings page is checked as described above, a request for multiple layers or layer groups in MapML format will result in the serialization of a MapML document containing multiple <map-extent> elements. Each layer/style pair is represented by a <map-extent> element in the response.  The <map-extent> elements are represented in the client viewer layer control settings as sub-layers, which turn on and off independently of each other, but which are controlled by the parent <map-layer> element's state (checked / unchecked, opacity etc) (right-click or Shift+F10 to obtain context menus):
+If the FORMAT_OPTION parameter of the WMS request is configured with `mapmlusemultiextents:true`, a request for multiple layers or layer groups in MapML format on the Layer Preview page will result in the serialization of a MapML document containing multiple <map-extent> elements.  Each layer/style pair is represented by a <map-extent> element in the response.  The <map-extent> elements are represented in the client viewer layer control settings as sub-layers, which turn on and off independently of each other, but which are controlled by the parent <map-layer> element's state (checked / unchecked, opacity etc) (right-click or Shift+F10 to obtain context menus):
 
 .. figure:: images/mapml_wms_multi_extent.png
 
-With 'Represent multi-layer requests as multiple elements' checked, if two or more layers are requested in MapML format via the GetMap 'layers' parameter, the MapML extension serialize each layer's <map-extent> according to its "Use Features" and "Use Tiles" settings.  Note that there is currently no "Use Features" setting available for layer groups.
+With the FORMAT_OPTION parameter of the WMS request is configured with `mapmlusemultiextents:true`, if two or more layers are requested in MapML format via the GetMap 'layers' parameter, the MapML extension serialize both layer's <map-extent> based on the mapmlusefeatures and mapmlusetiles settings in the FORMAT_OPTION parameter of the WMS request.  If these are not set in FORMAT_OPTION they will default to false.  Note that there is currently no "Use Features" support available for layer groups.
 
 Tile Caching
 ^^^^^^^^^^^^
@@ -265,6 +267,18 @@ in order to enable WMTS requests.
 
 .. figure:: images/mapml_tile_caching_panel_ui.png
 
+In order to properly pass the proper multi-extent, tiling, and feature parameters to the tiling WMS requests used to populate the cache, a FORMAT_OPTIONS parameter filter (see :ref:`gwc_webadmin_layers`) must be created with appropriate default values and a regular expression that matches the MapML requests.  
+
+The Default Value entry should look like this::
+
+    mapmlusemultiextents:true;mapmlusefeatures:false;mapmlusetiles:true
+
+Here is an example regular expression that matches the MapML FORMAT_OPTIONS parameters in any order::
+
+    (?i)\\b(mapmlusemultiextents|mapmlusefeatures|mapmlusetiles):\\s*(true|false)\\b(?:\\s*;\\s*(?i)\\b(mapmlusemultiextents|mapmlusefeatures|mapmlusetiles):\\s*(true|false)\\b)*(?:\\s*;\\s*(?i)\\b(mapmlusemultiextents|mapmlusefeatures|mapmlusetiles):\\s*(true|false)\\b)*
+
+.. figure:: images/mapml_tile_filter.png
+
 Starting with version 2.26.x of GeoServer, Sharding support and related configuration has been removed
 
 Dimension Config

doc/en/user/source/installation/upgrade.rst

@@ -30,6 +30,14 @@ The general GeoServer upgrade process is as follows:
 Notes on upgrading specific versions
 ------------------------------------
 
+MapML Multi-Layer As Multi-Extent Configuration (GeoServer 2.28 and newer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As of GeoServer 2.28, the configuration option for MapML Multi-Layer as Multi-Extent has been moved from 
+the WMS Administration page to the Publishing tab of the Layer Group configuration. Backwards compatibility 
+with previously configured MapML implementations is maintained through the population of Layer Group metadata 
+if the option was previously enabled in the WMS Administration page. For more information, see :ref:`mapml_installation`.
+
 FreeMarker Template Method Access (GeoServer 2.27 and newer)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/extension/mapml/src/main/java/org/geoserver/mapml/MapMLConstants.java

@@ -29,6 +29,23 @@ public final class MapMLConstants {
     /** format MediaType */
     public static final MediaType MAPML_MEDIA_TYPE = new MediaType("text", "mapml", StandardCharsets.UTF_8);
 
+    /** Multilayer represented as multi-extent */
+    public static final String MAPML_MULTILAYER_AS_MULTIEXTENT = "mapmlusemultiextents";
+
+    public static final String MAPML_USE_FEATURES_REP = "mapmlusefeatures";
+
+    public static final Boolean MAPML_USE_FEATURES_REP_DEFAULT = Boolean.FALSE;
+
+    public static final String MAPML_USE_TILES_REP = "mapmlusetiles";
+
+    public static final Boolean MAPML_USE_TILES_REP_DEFAULT = Boolean.FALSE;
+
+    /**
+     * The key for the metadata entry that controls whether a multi-layer request is rendered as a single extent or
+     * multiple extents.
+     */
+    public static final Boolean MAPML_MULTILAYER_AS_MULTIEXTENT_DEFAULT = Boolean.FALSE;
+
     /** format name */
     public static final String FORMAT_NAME = "MAPML";
 
@@ -49,6 +66,9 @@ public final class MapMLConstants {
     /** MapML layer metadata use tiles */
     public static final String MAPML_USE_TILES = "mapml.useTiles";
 
+    /** MapML layer metadata use multiextent */
+    public static final String MAPML_MULTIEXTENT = "mapml.multiextent";
+
     /** MapML layer metadata remote client request */
     public static final String MAPML_USE_REMOTE = "mapml.useRemote";