[test] Jetty follow-ups: Windows IT, logging, ClassRule, docs

- WindowsPathResourceIT in exist-webdav (Windows CI)
- Public WindowsPathResource for cross-module test access
- org.exist.jetty WARN logging in integration test log4j2
- ExistWebServer javadoc; ControllerTest @ClassRule
- Remove redundant RestBinariesTest HTTP timeouts

Author: duncdrum

exist-core/src/main/java/org/exist/jetty/WindowsPathResource.java

@@ -41,7 +41,7 @@
  * when the URI path is {@code /D:/...}. Exploded test webapps on Windows CI hit this in
  * {@code WebAppContext.getWebInf()}. Remove when upstream Jetty restores safe Windows resolve.
  */
-final class WindowsPathResource extends Resource {
+public final class WindowsPathResource extends Resource {
 
     private final Resource delegate;
     private final ResourceFactory resourceFactory;
@@ -51,7 +51,7 @@ private WindowsPathResource(final Resource delegate, final ResourceFactory resou
         this.resourceFactory = Objects.requireNonNull(resourceFactory);
     }
 
-    static Resource wrapIfNeeded(final Resource resource, final ResourceFactory resourceFactory) {
+    public static Resource wrapIfNeeded(final Resource resource, final ResourceFactory resourceFactory) {
         if (resource == null || File.separatorChar != '\\' || !(resource instanceof PathResource)) {
             return resource;
         }

exist-core/src/main/java/org/exist/test/ExistWebServer.java

@@ -42,7 +42,32 @@
 import static org.exist.repo.AutoDeploymentTrigger.AUTODEPLOY_PROPERTY;
 
 /**
- * Exist Jetty Web Server Rule for JUnit
+ * JUnit {@link org.junit.rules.ExternalResource} that starts an embedded eXist Jetty server for tests.
+ * <p>
+ * Prefer {@link org.junit.ClassRule} over {@link org.junit.Rule} when every test method in the class
+ * can share one server instance (see {@link org.exist.http.urlrewrite.URLRewritingTest}).
+ * <p>
+ * <strong>Jetty layout ({@code jettyStandaloneMode})</strong>
+ * <ul>
+ *   <li>{@code true} (default): standalone deploy — single webapp at {@code /} via
+ *       {@code exist.jetty.standalone.webapp.dir}. The context must reach
+ *       {@link org.eclipse.jetty.server.handler.ContextHandler#isAvailable()} before HTTP clients
+ *       are used; {@link org.exist.jetty.JettyStart} blocks until it is ready.</li>
+ *   <li>{@code false}: distribution layout — {@code /exist} (main app) plus portal {@code /}.
+ *       {@code /exist} must be available; the portal may only need {@code isStarted()}.
+ *       Requires {@code exist.jetty.portal.dir} in Maven test configuration (see {@code exist-core/pom.xml}).</li>
+ * </ul>
+ * <p>
+ * <strong>Common system properties</strong> (usually set in module {@code pom.xml} Surefire config):
+ * <ul>
+ *   <li>{@code exist.jetty.standalone.webapp.dir} — exploded standalone test webapp root</li>
+ *   <li>{@code exist.jetty.portal.dir} — portal webapp for distribution-mode tests</li>
+ *   <li>{@code jetty.port}, {@code jetty.secure.port}, {@code jetty.ssl.port} — set automatically when
+ *       {@code useRandomPort} is {@code true}</li>
+ *   <li>{@code jetty.home} — Jetty configuration directory ({@code exist-jetty-config/target/classes/...})</li>
+ * </ul>
+ * Startup failures throw {@link IllegalStateException} with detail from {@link org.exist.jetty.JettyStart}
+ * (also printed to {@code System.err} when test log4j root is OFF).
  */
 public class ExistWebServer extends ExternalResource {
 

exist-core/src/test/java/org/exist/http/urlrewrite/ControllerTest.java

@@ -30,7 +30,7 @@
 import org.apache.http.entity.ContentType;
 import org.exist.http.AbstractHttpTest;
 import org.exist.test.ExistWebServer;
-import org.junit.Rule;
+import org.junit.ClassRule;
 import org.junit.Test;
 
 import java.io.IOException;
@@ -50,8 +50,8 @@ public class ControllerTest extends AbstractHttpTest {
     private static final String LEGACY_CONTROLLER_XQUERY = "<controller>xql</controller>";
     private static final String TEST_DOCUMENT_NAME = "test.xml";
 
-    @Rule
-    public final ExistWebServer existWebServer = new ExistWebServer(true, false, true, true, false);
+    @ClassRule
+    public static final ExistWebServer existWebServer = new ExistWebServer(true, false, true, true, false);
 
     @Test
     public void findsLegacyController() throws IOException {

exist-core/src/test/resources/log4j2.xml

@@ -29,6 +29,7 @@
         </Console>
     </Appenders>
     <Loggers>
+        <Logger name="org.exist.jetty" level="WARN"/>
         <Root level="OFF">
             <AppenderRef ref="Console"/>
         </Root>

extensions/exquery/restxq/src/test/resources/log4j2.xml

@@ -6,6 +6,7 @@
         </Console>
     </Appenders>
     <Loggers>
+        <Logger name="org.exist.jetty" level="WARN"/>
         <Root level="OFF">
             <AppenderRef ref="Console"/>
         </Root>

extensions/modules/file/src/test/java/org/exist/xquery/modules/file/RestBinariesTest.java

@@ -171,7 +171,6 @@ private HttpResponse postXquery(final String xquery) throws JAXBException, IOExc
         try(final UnsynchronizedByteArrayOutputStream baos = UnsynchronizedByteArrayOutputStream.builder().get()) {
             marshaller.marshal(query, baos);
             response = executor.execute(Request.Post(getRestUrl() + "/db/")
-                    .connectTimeout(10000).socketTimeout(10000)
                     .bodyByteArray(baos.toByteArray(), ContentType.APPLICATION_XML)
             ).returnResponse();
         }

extensions/modules/file/src/test/resources/log4j2.xml

@@ -29,6 +29,7 @@
         </Console>
     </Appenders>
     <Loggers>
+        <Logger name="org.exist.jetty" level="WARN"/>
         <Root level="OFF">
             <AppenderRef ref="Console"/>
         </Root>

extensions/webdav/src/test/java/org/exist/jetty/WindowsPathResourceIT.java

@@ -0,0 +1,77 @@
+/*
+ * eXist-db Open Source Native XML Database
+ * Copyright (C) 2001 The eXist-db Authors
+ *
+ * info@exist-db.org
+ * http://www.exist-db.org
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+package org.exist.jetty;
+
+import org.eclipse.jetty.util.resource.PathResource;
+import org.eclipse.jetty.util.resource.Resource;
+import org.eclipse.jetty.util.resource.ResourceFactory;
+import org.junit.Test;
+
+import java.io.File;
+import java.nio.file.Files;
+import java.nio.file.InvalidPathException;
+import java.nio.file.Path;
+
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assume.assumeTrue;
+
+/**
+ * Windows integration regression test for Jetty 12.1 {@link PathResource#resolve(String)} on
+ * drive URIs ({@code /D:/...}). Lives in {@code exist-webdav} so it runs on Windows CI
+ * ({@code verify -DskipUnitTests=true}).
+ */
+public class WindowsPathResourceIT {
+
+    @Test
+    public void resolveWebInfOnWindowsDriveUri() throws Exception {
+        assumeTrue("Windows-only PathResource URI regression", File.separatorChar == '\\');
+
+        final ResourceFactory resourceFactory = ResourceFactory.root();
+        final Path webapp = Files.createTempDirectory("webapp");
+        Files.createDirectory(webapp.resolve("WEB-INF"));
+        try {
+            final Resource resource = resourceFactory.newResource(webapp);
+            assumeTrue("Expected PathResource for local webapp directory", resource instanceof PathResource);
+            final String uriPath = resource.getURI().getPath();
+            assumeTrue("Expected absolute Windows drive URI path, got: " + uriPath,
+                    uriPath != null && uriPath.matches("/[A-Za-z]:/.*"));
+
+            final PathResource pathResource = (PathResource) resource;
+            try {
+                pathResource.resolve("WEB-INF/");
+                // Jetty version may already fix resolve; wrapped path must still work.
+            } catch (final InvalidPathException e) {
+                // Expected on Jetty 12.1.x with /X:/... URI paths.
+            }
+
+            final Resource wrapped = WindowsPathResource.wrapIfNeeded(pathResource, resourceFactory);
+            assertNotSame(pathResource, wrapped);
+
+            final Resource webInf = wrapped.resolve("WEB-INF/");
+            assertTrue("WEB-INF should resolve to a directory", webInf.isDirectory());
+        } finally {
+            Files.deleteIfExists(webapp.resolve("WEB-INF"));
+            Files.deleteIfExists(webapp);
+        }
+    }
+}

extensions/webdav/src/test/resources/log4j2.xml

@@ -29,6 +29,7 @@
         </Console>
     </Appenders>
     <Loggers>
+        <Logger name="org.exist.jetty" level="WARN"/>
         <Root level="OFF">
             <AppenderRef ref="Console"/>
         </Root>