review sphinx docs for java 17 update

jodygarnett · jodygarnett · commit 158a42b56d56 · 2025-06-25T16:49:23.000-07:00
diff --git a/documentation/en/user/source/configuration/layers/howto.rst b/documentation/en/user/source/configuration/layers/howto.rst
@@ -33,8 +33,8 @@ It is recommended to use a special XML editing tool or at the very least a text
 
 Two recommended free editors, both of which have support for XML validation, are:
 
-* `jEdit <http://www.jedit.org/>`_ (cross platform)
-* `Notepad++ <http://notepad-plus-plus.org/>`_ (Windows only)
+* `jEdit <https://www.jedit.org>`_ (cross platform)
+* `Notepad++ <https://notepad-plus-plus.org/>`_ (Windows only)
 
 It is also possible to validate an XML document outside of a text editor environment.
 
diff --git a/documentation/en/user/source/configuration/storage.rst b/documentation/en/user/source/configuration/storage.rst
@@ -23,53 +23,57 @@ does not explicitly indicate which blobstore shall be used.
 
 .. note:: **there will always be a "default" blobstore**. If a blobstore to be used by default is not explicitly configured, one will
    be created automatically following the legacy cache location lookup mechanism used in versions prior to 1.8.0.
- 
+
+.. _configuration.file
+
 Configuration File
 ------------------
 
-The location of the configuration file, :file:`geowebcache.xml`, will be defined by the ``GEOWEBCACHE_CACHE_DIR`` application argument.
+The location of the configuration file, :file:`geowebcache.xml`, will be defined by the ``GEOWEBCACHE_CACHE_DIR`` application parameter.
 
-There are a few ways to define this argument:
+There are a few ways to define ``GEOWEBCACHE_CACHE_DIR``:
 
 * JVM system environment variable
 * Servlet context parameteter
 * Operating system environment variable
 
 The variable in all cases is defined as ``GEOWEBCACHE_CACHE_DIR``.
 
-To set as a JVM system environment variable, add the parameter ``-DGEOWEBCACHE_CACHE_DIR=<path>`` to your servlet startup script.  
-In Tomcat, this can be added to the Java Options (JAVA_OPTS) variable in the startup script.
-
-To set as a servlet context parameter, edit the GeoWebCache :file:`web.xml` file and add the following code:
-
-.. code-block:: xml
-
-   <context-param>
-     <param-name>GEOWEBCACHE_CACHE_DIR</param-name>
-     <param-value>PATH</param-value>
-   </context-param>
-
-where ``PATH`` is the location of the cache directory.
+1. To set as a JVM system environment variable, add the parameter ``-DGEOWEBCACHE_CACHE_DIR=<path>`` to your servlet startup script.
 
-To set as an operating system environment variable, run one of the the following commands:
+   In Tomcat, this can be added to the Java Options (``JAVA_OPTS``) variable in the startup script, or by creating :file:`setenv.sh` / :file:`setenv.bat`:
 
-Windows::
+2. To set as a servlet context parameter, edit the GeoWebCache :file:`web.xml` file and add the following code:
 
-  > set GEOWEBCACHE_CACHE_DIR=<path>
+   .. code-block:: xml
+   
+      <context-param>
+        <param-name>GEOWEBCACHE_CACHE_DIR</param-name>
+        <param-value>PATH</param-value>
+      </context-param>
 
-Linux/OS X::
+    where ``PATH`` is the location of the cache directory.
 
-  $ export GEOWEBCACHE_CACHE_DIR=<path>
+3. To set as an operating system environment variable, run one of the the following commands:
 
-Finally, although not recommended, it is possible to set this location directly in the :file:`geowebcache-core-context.xml` file.  Uncomment this code:
+   Windows::
+   
+     > set GEOWEBCACHE_CACHE_DIR=<path>
+   
+   Linux/OS X::
+   
+     $ export GEOWEBCACHE_CACHE_DIR=<path>
 
-.. code-block:: xml
+4. Not recommended: It is possible to set this location directly in the :file:`geowebcache-core-context.xml` file.
+   However this file will be replaced each update:
 
-   <!-- bean id="gwcBlobStore" class="org.geowebcache.storage.blobstore.file.FileBlobStore" destroy-method="destroy">
-     <constructor-arg value="/tmp/gwc_blobstore" />
-   </bean -->
+   .. code-block:: xml
+   
+      <!-- bean id="gwcBlobStore" class="org.geowebcache.storage.blobstore.file.FileBlobStore" destroy-method="destroy">
+        <constructor-arg value="/tmp/gwc_blobstore" />
+      </bean -->
 
-making sure to edit the path.  As usual, any changes to the servlet configuration files will require :ref:`configuration.reload`.
+   making sure to edit the path.  As usual, any changes to the servlet configuration files will require :ref:`configuration.reload`.
 
 .. note:: if ``GEOWEBCACHE_CACHE_DIR`` is not provided by any of the above mentioned methods, the directory will default
     to the temporary storage folder specified by the web application container. (For Tomcat, this is the :file:`temp` directory inside the root.)
diff --git a/documentation/en/user/source/faq/index.rst b/documentation/en/user/source/faq/index.rst
@@ -4,5 +4,7 @@ Frequently Asked Questions
 This section will answer common questions about GeoWebCache.
 
 Does GeoWebCache support WFS feature caching?
-  Not currently.  Earlier versions of GeoWebCache had an experimental prototype of vector feature caching, but it was highly unstable and was removed from GeoWebCache as of version 1.2.5.
 
+  Not currently.  Earlier versions of GeoWebCache had an experimental prototype of vector feature caching, but it was highly unstable and was removed from GeoWebCache as of version 1.2.5.
+  
+  However when used with a vector tiles output format GeoWebCache can cache a vector representation of the features within each tile. It is up to client software to stich together the resulting shapes during vector tile rendering.
diff --git a/documentation/en/user/source/installation/geowebcache.rst b/documentation/en/user/source/installation/geowebcache.rst
@@ -3,11 +3,11 @@
 Installing GeoWebCache
 ======================
 
-Once the :ref:`Java Servlet environment <prerequisites>` is in place, installing GeoWebCache is simple. 
+Once the :ref:`Java Servlet environment <prerequisites>` is in place:
 
-The latest Web ARchive (WAR) file can be downloaded from `GeoWebCache.osgeo.org <https://geowebcache.osgeo.org>`_.  
+1. The :file:`geowebcache-war.zip` Web ARchive (WAR) file can be downloaded from `GeoWebCache.osgeo.org <https://geowebcache.osgeo.org>`_.  
 
-Unpack the zip file and make sure to read the software :ref:`license`.
+2. Unpack the zip file and make sure to read the software :ref:`license`, and locate the :file:`geowebcache.war` for deployment.
 
 Option 1: Tomcat Administration Tool
 ------------------------------------
@@ -18,13 +18,23 @@ Option 1: Tomcat Administration Tool
 
 #. After the upload is complete, look for :guilabel:`geowebcache` in the :guilabel:`Applications` table. 
 
-#. GeoWebCache should be installed at ``http://localhost:8080/geowebcache``.
+#. Once the application is started, GeoWebCache is available ``http://localhost:8080/geowebcache``.
 
 Option 2: Manual Installation
 -----------------------------
 
-The file :file:`geowebcache.war` is just a zip file.  The Tomcat Administration Tool unpacks this file to a folder inside the Tomcat webapps directory called ``<tomcat dir>/webapps/geowebcache``.  If you wish, you can unpack this archive manually in this location. You can also make configuration changes before copying to the webapps directory.
+1. Tomcat will need to be stopped before making any changes to the webapps directory.
+   
+   Ensure that the Tomcat process is stopped before proceeding, as the JVM does not always release file handles immediately.
 
-.. note:: Tomcat will need to be stopped before making any changes to the webapps directory.  Ensure that the Tomcat process is stopped before proceeding, as the JVM does not always release file handles immediately.
+2. To manually deploy:
 
-After restarting Tomcat, GeoWebCache should be installed at ``http://localhost:8080/geowebcache``.
+   * Copy the file :file:`geowebcache.war` to :file:`<tomcat dir>/webapps`.
+   
+     On startup Tomcat will deploy the application to the folder :file:`<tomcat dir>/webapps/geowebcache`
+     
+   * If you wish, you can unpack this archive manually in this location. The :file:`geowebcache.war` may be treated as a zip file and be unpacked to :file:`<tomcat dir>/webapps/geowebcache`.
+  
+    This approach allows you to make configuration changes before restartig Tomcat.
+
+3. After restarting Tomcat, GeoWebCache is available ``http://localhost:8080/geowebcache``.
diff --git a/documentation/en/user/source/installation/prerequisites/linux.rst b/documentation/en/user/source/installation/prerequisites/linux.rst
@@ -17,14 +17,7 @@ Java Runtime Environment
 
 Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoWebCache requires a Java 17 or Java 21 environment, available from `OpenJDK <https://openjdk.java.net/>`__, `Adoptium <https://adoptium.net/>`_, or provided by your OS distribution.
 
-============ ================= ================ ================ ==================
-Java         Initial           Required         Final            Tested
-============ ================= ================ ================ ==================
-Java 21 LTS  GeoWebCache 1.25                                    OpenJDK
-Java 17 LTS  GeoWebCache 1.22  GeoWebCache 1.28                  OpenJDK
-Java 11 LTS  GeoWebCache 1.15  GeoWebCache 1.22 GeoWebCache 1.27 OpenJDK
-Java 8 LTS   GeoWebCache 1.9   GeoWebCache 1.9  GeoWebCache 1.22 Oracle and OpenJDK
-============ ================= ================ ================ ==================
+See :doc:`/installation/upgrading` for compatibility table.
   
 Apache Tomcat
 -------------
@@ -43,7 +36,7 @@ Using your favorite text editor, open ``/opt/apache-tomcat-9.0.106/bin/catalina.
 The first line sets the the JRE just installed is the one that Tomcat uses.  The second line tells Tomcat to run with server settings and to use 256MB for heap memory. (It may be possible to run with less heap memory, but this is no recommended.)  On big installations you will want to use 1024MB or more. Note that this resource is shared among all servlets running in the container, so if you add more servlets later you may have to adjust this number.
 
 Access Control
---------------
+^^^^^^^^^^^^^^
 
 If you wish to use Tomcat's web administration tool, you will need to create an account for the administrator.
 
@@ -55,7 +48,7 @@ Open ``/opt/apache-tomcat-9.0.106/conf/tomcat-users.xml`` in a text editor. Imme
 Replace ``s3cret`` with your actual password. After making this change you will have to restart Tomcat.
 
 Controlling Tomcat
-------------------
+^^^^^^^^^^^^^^^^^^
 
 Running as your own user, you should be able to start and stop Tomcat by using the scripts
 ``/opt/apache-tomcat-9.0.106/bin/startup.sh`` and ``/opt/apache-tomcat-a.b.c/bin/shutdown.sh``
diff --git a/documentation/en/user/source/installation/prerequisites/macosx.rst b/documentation/en/user/source/installation/prerequisites/macosx.rst
@@ -6,7 +6,9 @@ MacOS X
 MacOS has a number of command line package managers for open source components. We recommend using `SDKMAN! <https://sdkman.io/>`_ to manage Java and Tomcat environment.
 
 Java
-^^^^^
+----
+
+Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoWebCache requires a Java 17 or Java 21 environment.
 
 * Required: Java Development Kit 17 (JDK 17)
 
@@ -27,12 +29,18 @@ Java
      # Select Java for use 
      sdk use java 17<tab>
 
+See :doc:`/installation/upgrading` for compatibility table.
+
 Apache Tomcat
-^^^^^^^^^^^^^
+-------------
 
 GeoWebCache requires Apache Tomcat 9 required for JavaEE environment.
 
-* 
+1. Navigate to `Tomcat 9 <https://tomcat.apache.org/download-90.cgi>`_ **Downloads** section, and save the ``zip`` file listed under **Binary Distributions / Core**.
+
+   * Tomcat 9 Required: GeoWebCache uses the JavaEE environment last supported in Tomcat 9.
+   
+   * Tomcat 10 Unsupported: GeoWebCache is not yet compatibile with the JakartaEE environment used by Tomcat 10 and newer.
 
 * SDKMan!
 
diff --git a/documentation/en/user/source/installation/prerequisites/windows.rst b/documentation/en/user/source/installation/prerequisites/windows.rst
@@ -6,6 +6,8 @@ Windows
 Java Runtime Environment
 ------------------------
 
+Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoWebCache requires a Java 17 or Java 21 environment.
+
 1. Download an OpenJDK release for your platform:
 
    * https://adoptium.net/temurin/releases/?version=11 Temurin 11 (LTS) (Recommended)
@@ -15,6 +17,8 @@ Java Runtime Environment
    * Updating the JAVA_HOME environment variable
    * Add the installation to the PATH environment variable
 
+See :doc:`/installation/upgrading` for compatibility table.
+
 Apache Tomcat
 -------------
 
@@ -30,7 +34,7 @@ Apache Tomcat
     Note that this resource is shared among all servlets running in the container, so if you add more servlets later you may have to adjust this number.
 
 Access Control
---------------
+^^^^^^^^^^^^^^
 
 If you wish to use Tomcat's web administration tool, you will need to create an account for the administrator.
 
@@ -44,7 +48,7 @@ Do this by opening the :file:`conf\tomcat-users.xml` file in from your Tomcat Pr
 Replace ``s3cret`` with your actual password. After making this change you will have to restart Tomcat.
 
 Controlling Tomcat
-------------------
+^^^^^^^^^^^^^^^^^^
 
 By default, Tomcat will now start automatically with your computer. You can modify this by going through the :menuselection:`Control Panel -> Administrative Tools -> Services`, and editing the settings for the **Apache Tomcat** service.
 
diff --git a/documentation/en/user/source/installation/upgrading.rst b/documentation/en/user/source/installation/upgrading.rst
@@ -1,9 +1,53 @@
 .. _upgrading:
 
-Upgrading from a pre 1.15 release
-=================================
+Upgrading
+=========
 
-In 1.15 GeoWebCache changed to work on Java 9 and higher.  This included several changes to package names to avoid splitting packages across modules.  If you used any of the following classes in plugins, while emebdding GWC in a larger application, or using modified application contexts, you will need to make the follwing changes.
+1. Before you start:
+   
+   * Make a note of any customizations made to geowebcache :file:`WEB-INF` folder.
+
+     .. warning:: When updating, be sure to preserve any changes made to :file:`WEB-INF/geowebcache-core-context.xml` or :file:`WEB-INF/web.xml` as these files will be replaced during the upgrading process.
+
+   * To maintain cache location, follow the :ref:`configuration.file` instructions to define ``GEOWEBCACHE_CACHE_DIR`` and the location of :file:`geowebcache.xml` configuration.
+
+2. Stop Tomcat, follow the installation instructions to download and install the latest GeoWebCache version.
+   
+   Deploying a new version of GeoWebCache will replace :file:`<tomcat dir>/webapps/geowebcache` folder.
+
+3. Re-apply any customizations made to the :file:`WEB-INF` folder.
+
+4. Start tomcat 
+
+Java Compatibility
+------------------
+
+GeoWebCache is compiled with Java 17 (LTS) and tested with Java 17 LTS and Java 21 LTS.
+
+============ ================= ================ ================ ==================
+Java         Initial           Required         Final            Tested
+============ ================= ================ ================ ==================
+Java 21 LTS  GeoWebCache 1.25                                    OpenJDK
+Java 17 LTS  GeoWebCache 1.22  GeoWebCache 1.28                  OpenJDK
+Java 11 LTS  GeoWebCache 1.15  GeoWebCache 1.22 GeoWebCache 1.27 OpenJDK
+Java 8 LTS   GeoWebCache 1.9   GeoWebCache 1.9  GeoWebCache 1.22 Oracle and OpenJDK
+============ ================= ================ ================ ==================
+
+GeoWebCache 1.18 Update
+-----------------------
+
+Java 17 Minimum
+^^^^^^^^^^^^^^^
+
+GeoWebCache 1.18 is now compiled with Java 17 LTS, and is tested with Java 17 LTS and Java 21 LTS.
+
+GeoWebCache 1.15 Update
+-----------------------
+
+Java 9 Minimum
+^^^^^^^^^^^^^^
+
+In 1.15 GeoWebCache changed to work with Java 9 or higher, with Java 11 LTS recommended. This included several changes to package names to avoid splitting packages across modules.  If you used any of the following classes in plugins, while emebdding GWC in a larger application, or using modified application contexts, you will need to make the follwing changes.
 
 +----------------+---------------------------------------+-------------------------------------------+
 | Module         | ≤ 1.14                                | ≥ 1.15                                    |
@@ -38,8 +82,11 @@ In 1.15 GeoWebCache changed to work on Java 9 and higher.  This included several
 +----------------+---------------------------------------+-------------------------------------------+
 
 
-Upgrading from a pre 1.4 release
-================================
+GeoWebCache 1.4.0 Update
+------------------------
+
+File Blob Store replaces metastore
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Starting with GeoWebCache 1.4.0 the metastore support has been removed and all its functionality has been moved to the file blob store, including support for tile expiration based on creatin date and request parameter handling.
 
diff --git a/documentation/en/user/source/quickstart/index.rst b/documentation/en/user/source/quickstart/index.rst
@@ -12,9 +12,9 @@ All servers conforming to the `OGC Web Map Service specification <http://www.ope
 View preconfigured layers
 -------------------------
 
-GeoWebCache comes preconfigured with three layers.  To view them, navigate to your GeoWebCache demo page at ``http://GEOWEBCACHE_URL/demo`` (often this is ``http://localhost:8080/geowebcache/demo``).  Click on any of the links next to the :guilabel:`OpenLayers` column.
+GeoWebCache comes preconfigured with three layers from a default GeoServer install which may be installed alongside GeoNetwork.  To view them, navigate to your GeoWebCache demo page at ``http://localhost:8080/geowebcache/demo``.  Click on any of the links next to the :guilabel:`OpenLayers` column.
 
-These layers are all served by the WMS available at ``http://demo.opengeo.org/geoserver/``.
+These layers are all served by the WMS available at ``http://localhost:8080/geowebcache/``.
 
 .. list-table::
    :header-rows: 1
@@ -29,14 +29,14 @@ These layers are all served by the WMS available at ``http://demo.opengeo.org/ge
    * - **topp:states**
      - topp:states
 
-.. note:: This information is set in the :file:`geowebcache.xml` file, which is typically available at :file:`opt/apache-tomcat-6.0.29/webapps/geowebcache/WEB-INF/classes` or :file:`C:\\Program Files\\Apache Software Foundation\\Tomcat 6.0.29\\webapps\\geowebcache\\WEB-INF\\classes`.  See the section on :ref:`configuration.layers` for more information on customizing this file.
+.. note:: This information is set in the :file:`geowebcache.xml` file, which is typically available at :file:`webapps/geowebcache/WEB-INF/classes`. See the section on :ref:`configuration.layers` for more information on customizing this file.
 
 .. _quickstart.wms:
 
 View layers from a WMS
 ----------------------
 
-The file :file:`geowebcache-core-context.xml` is a configuration file controling how the application is loaded. It is located inside the WEB-INF folder, typically :file:`/opt/apache-tomcat-6.0.29/webapps/geowebcache/WEB-INF/` or :file:`C:\\Program Files\\Apache Software Foundation\\Tomcat 6.0.29\\webapps\\geowebcache\\WEB-INF` along with several other configuration files.
+The file :file:`geowebcache-core-context.xml` is a configuration file controling how the application is loaded. It is located inside the WEB-INF folder, typically :file:`webapps/geowebcache/WEB-INF/` along with several other configuration files.
 
 #. Open :file:`geowebcache-core-context.xml` in a text editor.
 
@@ -52,7 +52,7 @@ The file :file:`geowebcache-core-context.xml` is a configuration file controling
 
    .. code-block:: xml
 
-      <constructor-arg value="http://localhost:8282/geoserver/wms?request=getcapabilities&amp;version=1.1.0&amp;service=wms" />
+      <constructor-arg value="http://localhost:8080/geoserver/wms?request=getcapabilities&amp;version=1.1.0&amp;service=wms" />
 
 #. Replace the value with a URL pointing to a valid WMS capabilities document, such as:
 
