[GEOS-11294] map ml wms vector representation

doc/en/developer/source/programming-guide/config/resource.rst

@@ -17,21 +17,51 @@ Reference:
 * `GSIP-136 - Resource Notification Dispatcher <https://github.com/geoserver/geoserver/wiki/GSIP-136>`__
 * `GSIP-132 - GSIP 132 - Resource Store changes <https://github.com/geoserver/geoserver/wiki/GSIP-132>`__
 
-.. note::
+Parameter Naming Convention
+---------------------------
 
-   The methods in the Resource API use String parameter names consistently:
+The methods in the Resource API use String parameter names consistently:
 
-   * ``path`` relative location of resource within the data directory.
+* ``resource path`` parameter is a path to a resource in the resource store.
+
+  In the case of the default FileSystemResourceStore, this is file path that is relative with respect to the data directory. To preserve generic behaviour compatible with any resource store, developers should not assume this to be the case.
 
-     Paths are represented similar to a File URL, ``file://`` prefix used internally and
-     by the resource REST API.
-
-   * ``file`` a java File reference.
+  Resource paths do not support the `.` and `..` relative directory names. Resource paths use forward slashes, similar to URL's and unix style file paths, and are OS-independent.
+
+* ``file path`` parameter is an absolute path to a file in the file system.
+
+  While these are OS dependent (with regard to the root of the absolute path) but they must always use forward slashes, as supported by all operating systems and compatible with resource paths as well as file URL's. Note that ``Resource.path()`` for resources obtained by ``Files.asResource(file)`` will return a file path rather than a resource path.
+
+* ``file`` parameter is a java File reference.
+
+* ``url`` a location resolved with respect to the resource store.
+
+  A number of special cases developed over time distilled into ``Resources.fromUrl(base,url)`` method.
+
+General Guidelines
+------------------
+
+All geoserver developers should be wary of the following general principles when contributing or reviewing:
+
+* Avoid as much as possible using the file system directly.
+
+  .. note:: The only acceptable exception is when third party libraries require use of a File. Even in this case use Resources API as much as possible.
+
+* Use Avoid the usage of ``Resource.file()`` and ``Resource.directory()``.
 
-   * ``url`` a location resolved with respect to the data directory.
+  These methods are only necessary for third party libraries that require usage of the file system, when the third party library accepts a file input.
 
-     A large number of special cases developed over time distilled into  ``Resources.fromUrl(base,url)`` and ``Files.url(base,url)`` methods.
+  .. note:: The ``file()`` and ``directory()`` methods are never be used for permanent storage. Since there are alternative implementations of the ResourceStore that do not use the file system as underlying storage device, modifying a file on disk does not necessarily have a lasting effect.
+
+* For custom configuration files with a fixed location, always use ``ResourceStore``.
 
+  ``GeoServerResourceLoader`` and ``GeoServerDataDirectory`` from GeoServer 1.0 have been rewritten internally to use Resource API , and should not be used in new code.
+
+* For URL's provided by user configuration (such as templates, style sheets, etc), use ``Resources.fromURL``.
+
+* For input/output, always use ``Resource.in()`` and ``Resource.out()``.
+x  
+  This approach is compatible with java try-with-resource making for easy to follow code.
 
 ResourceStore
 -------------
@@ -42,10 +72,10 @@ InputStream used to access configuration information:
 
 .. code-block:: java
 
-  Properties properties = new Properties();
-  try (InputStream in = resourceStore.get("module/configuration.properties").in() ){
-    properties.load(in);
-  }
+   Properties properties = new Properties();
+   try (InputStream in = resourceStore.get("module/configuration.properties").in() ){
+     properties.load(in);
+   }
 
 An OutputStream is provided for storage (a Resource will be created as needed):
 
@@ -83,17 +113,19 @@ Resource contents are streamed using ``out()`` and ``in()`` methods. The entire
 
 Resource ``path()`` provides the complete path relative to the ``ResourceStore`` base directory. Use ``name()`` to retrieve the resource name (as the last component in the path name sequence).
 
-Resource creation is handled in a lazy fashion, use ``file()`` or ``out()`` and the resource will be created as required.
+Resource creation is handled in a lazy fashion, use ``out()`` and the resource will be created as required, including any required parent directories are created to produce the completed path.
 
-Use ``dir()`` to create a empty directory. Directories have the ability to ``list()`` their contents:
+Directory resources have the ability to ``list()`` their contents:
 
 .. code-block:: java
 
    for( Resource child : resource.list()) {
       ...    
    }
 
-When creating a resource with ``file()``, ``out()`` or ``dir()`` any required parent directories are created to produce the completed path).
+The method ``isInternal()`` returns whether the resource is part of the resource store or rather a wrapped file obtained by ``File.asResource``. If this method returns `false` then ``path()`` returns a file path rather than a resource path.
+
+The methods ``file()`` and ``dir()`` may be used to obtain a file system representation of the resource. Depending on the resource store implementation, this may be the underlying storage entity (in the case of the default FileSystemResourceStore), or merely a cached entity. Changes to these should not be assumed to be permanent. These methods should only be used for input when a third library requires a file and does not support passing on streams.
 
 Once created resources can be managed with ``delete()``, ``renameTo(resource)`` methods.
 
@@ -104,7 +136,7 @@ Resource ``lock()`` is also supported.
 Paths
 -----
 
-The ``Paths`` facade provides methods for working with the relative paths used by ResourceStore.
+The ``Paths`` facade provides methods for working with resource paths used by ResourceStore.
 
 Helpful methods are provided for working with paths and names:
 
@@ -114,14 +146,21 @@ Helpful methods are provided for working with paths and names:
 * ``sidecar(path, extension)``
 * ``names(path)`` processes the path into a list of names as discussed below.
 
-The definition of a path has been expanded to work with the external locations (with ``Paths.isAbsolute(path)`` and ``Paths.names(path)``).
-
 Paths are broken down into a sequence of names, as listed by ``Paths.names(path)``:
 
 * ``Path.names("data/tasmania/roads.shp")`` is represented as a list of ``data``, ``tasmania``, ``roads.shp``.
-* On linux ``Path.names("/src/gis/cadaster/district.geopkg")`` starts with a marker to indicate an absolute path, resulting in ``/``, ``src``, ``gis``, ``cadaster``, ``district.geopkg``.
-* On windows ``Path.names("D:/gis/cadaster/district.geopkg")`` starts with a marker to indicate an absolute path, resulting in ``D:/``, ``gis``, ``cadaster``, ``district.geopkg``.
 
+For file paths that are OS dependent, use ``FilePaths.names(file_path)`` instead.
+
+FilePaths
+---------
+
+The ``FilePaths`` facade provides methods for working with file paths.
+
+Paths are broken down into a sequence of names, as listed by ``Paths.names(path)``:
+
+* On linux ``FilePath.names("/src/gis/cadaster/district.geopkg")`` starts with a marker to indicate an absolute path, resulting in ``/``, ``src``, ``gis``, ``cadaster``, ``district.geopkg``.
+* On windows ``FilePath.names("D:/gis/cadaster/district.geopkg")`` starts with a marker to indicate an absolute path, resulting in ``D:/``, ``gis``, ``cadaster``, ``district.geopkg``.
 
 
 Paths.convert
@@ -167,33 +206,45 @@ There are also method for working with directories recursively and filtering con
 Resources.fromUrl
 ^^^^^^^^^^^^^^^^^
 
-There is an important method ``Resources.fromURL( baseDirectory, url)`` that is used by a lot of code trying to understand data references:
+The interpretation of the URLs is as follows:
+
+* ``resource:`` prefix - interpreted as a resource path, returns resource from the resource store.
+* ``file:`` prefix with absolute path - interpreted as file path, returns resource created by Files.asResource that refers to file in the file system.
+* ``file:`` prefix with relative path (deprecated) - interpreted as a resource path, returns resource from the resource store.
 
+Examples:
+
+* ``Resources.fromURL( baseDirectory, "resource:images/image.png")`` - resource path
+* ``Resources.fromURL( baseDirectory, "file:images/image.png")`` - resource path (deprecated)
 * ``Resources.fromURL( null, "/src/gis/cadaster/district.geopgk")`` - absolute file path (linux)
 * ``Resources.fromURL( baseDirectory, "D:\\gis\\cadaster\\district.geopkg")`` - absolute file path (windows)
 * ``Resources.fromURL( baseDirectory, "file:///D:/gis/cadaster/district.geopkg")`` - absolute file url (windows)
 * ``Resources.fromURL( baseDirectory, "ftp://veftp.gsfc.nasa.gov/bluemarble/")`` - null (external reference)
 
-For the absolute file references above, see the next section on ``Files.url``.
-
 Files
 -----
 
 The ``Files`` facade provides methods for working with file objects, and one method of critical importace to the Resource API.
 
-The ``Files.asResource(file)`` method creates a ``ResourceAdapter`` wrapper around an absolute file location. Allows the use of Resource API when working with content outside of the data directory.
+Files.asResource
+^^^^^^^^^^^^^^^^
+
+The ``Files.asResource(file)`` method creates a ``ResourceAdapter`` wrapper around an absolute file location. Allows the use of Resource API when working with content outside of the data directory. This is primary useful for writing test cases. 
 
 Files.url
 ^^^^^^^^^
 
+.. warning:: This method is deprecated along with File use, recommend use of ``Resources.fromURL (baseDirectory, url )`` to obtain Resource.
+
 The other key method is ``Files.url( baseDirectory, url)`` which is used to look up files based on a user provided URL (or path).
 
-* ``Files.fromURL( null, "resource:styles/logo.svg")`` - internal url format restricted to data directory content
-* ``Files.fromURL( null, "/src/gis/cadaster/district.geopgk")`` - absolute file path (linux)
-* ``Files.fromURL( baseDirectory, "D:\\gis\\cadaster\\district.geopkg")`` - absolute file path (windows)
-* ``Files.fromURL( baseDirectory, "file:///D:/gis/cadaster/district.geopkg")`` - absolute file url (windows)
-* ``Files.fromURL( baseDirectory, "ftp://veftp.gsfc.nasa.gov/bluemarble/")`` - null (external reference ignored as we cannot determine a file)
-* ``Files.fromURL( baseDirectory, "sde://user:pass@server:port")`` - null (custom strings are ignored as we cannot determine a file)
+
+* ``Files.url( null, "resource:styles/logo.svg")`` - internal url format restricted to data directory content
+* ``Files.url( null, "/src/gis/cadaster/district.geopgk")`` - absolute file path (linux)
+* ``Files.url( baseDirectory, "D:\\gis\\cadaster\\district.geopkg")`` - absolute file path (windows)
+* ``Files.url( baseDirectory, "file:///D:/gis/cadaster/district.geopkg")`` - absolute file url (windows)
+* ``Files.url( baseDirectory, "ftp://veftp.gsfc.nasa.gov/bluemarble/")`` - null (external reference ignored as we cannot determine a file)
+* ``Files.url( baseDirectory, "sde://user:pass@server:port")`` - null (custom strings are ignored as we cannot determine a file)
 
 
 GeoServerDataDirectory

doc/en/user/source/community/index.rst

@@ -47,6 +47,7 @@ officially part of the GeoServer releases. They are however built along with the
    jdbcconfig/index
    jdbcstore/index
    jms-cluster/index
+   jwt-headers/index
    keycloak/index
    libdeflate/index
    mbtiles/index