[GEOS-11207] Refactor MapML MVC controller as GetMap-based operation …

…with standard parameter format

working on builder

initialize first pass

more initialize

finished first pass at head

builder first pass done

first pass at marshalling mapml map response stuff

changed the proj stuff

first pass at formatlink

Got main test working

most tests done

more tests included

all original tests passing

html

html test passing

added height and width

int not double

subtype not format

cleanup

copyright missing

more test cleanup

added default image type to HTML

fixed empty style issue

exceptions were being prematurely caught

PR responses

test cleanup

added WMS parameter and fixed header base and header styles

WMS parameter and requested changes, XML validated

fixed issues with XML namespaces and some misc fixes for new extent handling

switched from WMS to serviceinfo metadata

clean up

added multilayer tests

Front end multi-extent setting

front end test

doc updates

doc tweak

alt link height and width and remove hidden from multi-extent

query_layers for single extent

added bbox to alt and switch center lat and lon of html to use wgs84

style and self style title, bbox, width, height

added empty commas for default styles

self style default

fixed regular styles issue

Add label to multi-extent map-extent when global MapML setting enabled

Fix NPE with multi-layer, single extent requests across, layers, groups

fix issue with trailing blank style

Added test for trailing comment in styles list

Make GetMap with format=text/html; subtype=mapml respect bbox param

Add <map-link rel=style> and <map-link rel="self style" for named
styles for sinble LayerGroup requests.

Replace .equals with .equalsIgnoreCase for string comparison of style
names

GetMap tests

fix pmd for test

wms output format documentation

style note

Add some images and description to docs

fixed tcrs issue

Change WMTS GetFeatureInfo parameter name from "info_format" (WMS) to
"infoformat" (WMTS). Why do they do that :-) ?

revert

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

@@ -3,12 +3,12 @@
 MapML 
 =========
 
-Map Markup Language (MapML) is a text-based format which allows map authors to encode map information as hypertext documents exchanged over the Uniform Interface of the Web. The format definition is still a work-in-progress by the Maps for HTML W3C Community Group, but various tools to work with the format already exist, including a Leaflet-based map viewer. For more information on MapML refer to the `Maps for HTML Community Group <https://maps4html.org/>`.
+Map Markup Language (MapML) is a text-based format which allows map authors to encode map information as hypertext documents exchanged over the Uniform Interface of the Web. The format definition is a work-in-progress by the Maps for HTML W3C Community Group. Various tools to work with the format exist, including a Leaflet-based map viewer included in the GeoServer MapML extension. For more information on MapML refer to the `Maps for HTML Community Group <https://maps4html.org/>`.
 
-The MapML module for GeoServer adds new MapML resources to access WMS and WFS services configured in Geoserver. The MapML modules includes support for styles, tiling, querying, sharding, and dimensions options for WMS layers, and also provides a MapML outputFormat for WMS GetFeatureInfo and WFS GetFeatures requests. See below for information on installing and configuring the MapML module.
+The MapML module for GeoServer adds new MapML resources to access WMS, WMTS and WFS services configured in Geoserver. The MapML modules includes support for styles, tiling, querying, and dimensions options for WMS layers, and also provides a MapML outputFormat for WMS GetFeatureInfo and WFS GetFeatures requests. See below for information on installing and configuring the MapML module.
     .. warning:: The MapML extension performance is negatively affected by a recent upgrade to Spring in the GeoServer project.  This affects all versions since 2.22.0. To avoid serious performance penalty, please remove "text/.*" from the gzip filter <param-value> in your web.xml servlet configuration.
 
-    .. warning:: MapML is an experimental proposed extension of HTML for the Web. The objective of the format is to standardize map, layer and feature semantics in HTML.  As the format progresses towards a Web standard, it may change.  Always use the latest version of this extension, and follow the project's progress at https://maps4html.org.
+    .. warning:: MapML is an experimental proposed extension of HTML for the Web. The objective of the project is to standardize map, layer and feature semantics in HTML.  As the format progresses towards a Web standard, it may change slightly.  Always use the latest version of this extension, and follow or join in the project's progress at https://maps4html.org.
 
 
 Installation
@@ -29,6 +29,23 @@ Configuration can be done using the Geoserver administrator GUI. The MapML confi
 
 .. figure:: images/mapml_config_ui.png
 
+There is also a MapML-specific global WMS setting in the *MapML Extension* section of the ``WMS`` Services Settings Page.  This setting is used to control the handling of multi-layer requests.  
+
+.. 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>.
+
+.. figure:: images/mapml_wms_multi_extent.png
+
+Styles
+------
+
+Like any WMS layer or layer group available from GeoServer, a comma-separated list of styles may be supplied in the WMS GetMap `styles` parameter.  If no style name is requested, the default style will be used for that layer.  For single-layer (or layer group) requests, the set of alternate styles is presented as an option list in the layer preview map's layer control, with the currently requested style indicated.
+
+.. figure:: images/mapml_preview_multiple_styles_menu.png
+
+Note that in order to ensure that the default layer style is properly available to the preview map's option list, make sure that the style is moved to the ``Available Styles`` list in the ``Publishing`` tab of the Layer Configuration page.  If the style is set to ``Default`` but not explicitly made ``Available``, the style will not be available to MapML.  Similarly but a with a slight variation in requirement, for Layer Groups, the 'default' layer group style must be copied and given a name matching `default-style-` plus the layer group name.
+
 License Info
 ^^^^^^^^^^^^
 
@@ -108,37 +125,37 @@ feature is focused.
 MapML Resources
 ---------------
 
-MapML resources will be published for any published WMS layers. The MapML resources will be available at::
-
-  http://{serverName}/geoserver/mapml/{layerName}/{projectionName}?style={styleName}&transparent={true|false}&format={wmsFormat}
+MapML resources will be available for any published WMS layers by making a GetMap request with the WMS output format to ``format=text/mapml``.  See :ref:`WMS` for further WMS details, :ref:`wms_getmap` for GetMap details, and :ref:`wms_output_formats` for output format reference information.
 
+**SRS/CRS**
 
-The ``{layerName}`` is the WMS layer name, and the ``{serverName}`` is the name or IP address of the server on which Geoserver is running. The ``{projectionName}`` must be one of the projections supported by MapML:
+Note that the WMS SRS or CRS must be one of the projections supported by MapML:
 
-- OSMTILE
-- CBMTILE
-- APSTILE
-- WGS84 
+- EPSG:3857
+- EPSG:3978
+- EPSG:5936
+- EPSG:4326
 
-Each of the URL query string parameters are optional, but if provided they are effectively passed-through to the underlying WMS service call. Here are some details on the parameters:
+**MapML Output Format**
 
-**style**
-  If provided, the specified ``{styleName}`` must correspond to an available WMS style to use for the layer.
-
-**transparent**
-  If provided, must be either ``true`` or ``false``. The same value is passed through to the underlying WMS service. If not provided, it defaults to the inverse of the "opaque" WMS publishing layer setting. 
-
-**format**
-  If provided, must be a valid WMS format specifier. If not provided, it defaults to ``image/png``. 
+The output image format for the MapML resource should be specified using the format_options parameter with a key called ``mapml-wms-format``.  If provided, the provided mime type must be a valid WMS format specifier. If not provided, it defaults to ``image/png``.   
+
+Example::
+
+    http://localhost:8080/geoserver/tiger/wms?service=WMS&version=1.1.0&request=GetMap&layers=tiger:giant_polygon&bbox=-180.0,-90.0,180.0,90.0&width=768&height=384&srs=EPSG:4326&styles=&format=text/mapml&format_options=mapml-wms-format:image/jpeg
 
 MapML Visualization
 -------------------
 
-With the MapML Community Module installed, the GeoServer Layer Preview page is modified to add a link to the MapML resources for each layer and layer group.  The MapML link in the Layer Preview table intercepted by the MapML module, and an HTML Web map page is created on the fly which refers to the MapML resource:
+With the MapML Extension module installed, the GeoServer Layer Preview page is modified to add a WMS GetMap link to the MapML resources for each layer or layer group.  The MapML link in the Layer Preview table is generated by the MapML extension to an HTML Web map page that is created on the fly which refers to the GeoServer resource:
 
 .. figure:: images/mapml_preview_ui.png
 
-You can add layers to the map as you like, by dragging the link URL from the Layer Preview table and dropping it onto another layer's MapML preview.  If all goes well, you should see the layers stacked on the map and in the layer control.
+You can add layers to the map as you like, by dragging the URL bar value generated by the the Layer Preview WMS formats dropdown menu selection of "MapML" as shown below, and dropping it onto another layer's MapML preview:
+
+.. figure:: images/mapml_wms_format_dropdown.png
+
+If all goes well, you should see the layers stacked on the map and in the layer control.
 
 MapML visualization is supported by the Web-Map-Custom-Element project. The MapML viewer is built into the GeoServer layer and layer group preview facility.  You can find out more about the Web-Map-Custom-Element at the project `website <https://maps4html.org/web-map-doc/>`. Here is a simple, self-contained example of an HTML page that uses the <mapml-viewer> and <layer-> elements: 
 

src/extension/mapml/pom.xml

@@ -22,17 +22,14 @@
     <dependency>
       <groupId>org.geoserver</groupId>
       <artifactId>gs-rest</artifactId>
-
     </dependency>
     <dependency>
       <groupId>org.geoserver</groupId>
       <artifactId>gs-gwc</artifactId>
-
     </dependency>
     <dependency>
       <groupId>org.geoserver.web</groupId>
       <artifactId>gs-web-core</artifactId>
-
     </dependency>
     <dependency>
       <groupId>org.geoserver.web</groupId>
@@ -42,7 +39,6 @@
     <dependency>
       <groupId>org.geoserver</groupId>
       <artifactId>gs-wfs</artifactId>
-
     </dependency>
     <dependency>
       <groupId>org.geoserver</groupId>

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

@@ -18,6 +18,12 @@ public final class MapMLConstants {
     /** format mime type */
     public static final String MAPML_MIME_TYPE = "text/mapml";
 
+    /** HTML format mime type */
+    public static final String MAPML_HTML_MIME_TYPE = "text/html; subtype=mapml";
+
+    /** WMS format_options parameter */
+    public static final String MAPML_WMS_MIME_TYPE_OPTION = "mapml-wms-format";
+
     /** format MediaType */
     public static final MediaType MAPML_MEDIA_TYPE =
             new MediaType("text", "mapml", StandardCharsets.UTF_8);