From 4ee2a9d1cfd089f49767a21cfb070e42ef512317 Mon Sep 17 00:00:00 2001
From: Chapman Flack <chap@anastigmatix.net>
Date: Sat, 16 Sep 2023 22:47:10 -0400
Subject: [PATCH 1/4] Allow use of Node with either PGJDBC or pgjdbc-ng

The two drivers use slightly different URL syntax, and
different names for some properties (database.name vs.
PGDBNAME, and application.name vs. ApplicationName
matter here). Expose a new static s_urlForm and constants
URL_FORM_PGJDBC and URL_FORM_PGJDBCNG (and URL_FORM_NONE
if no recognized driver has been found) so a client can
know what's been selected.

To simply count the otherwise-unwanted rows of a
ResultSet, pgjdbc-ng allows rs.last();rs.getRow(); but
PGJDBC does not, at least under its default for ResultSet
scrollability. The method voidResultSetDims gets a change here
to not attempt to count the rows when called by peek();
instead, it just returns -1 for rows in that case, which will
look odd but play well with both drivers.

The PostgreSQL backend sends an interesting message in the case
of function/procedure creation with types mentioned that are
shells. The message has severity NOTICE but SQLState 42809
(ERRCODE_WRONG_OBJECT_TYPE). For some reason, pgjdbc-ng has
not been delivering those, but PGJDBC does, and the heuristic
of looking at the class digits to decide if it's ok or not
would make the wrong call seeing class 42. Happily, PGJDBC
exposes (by casting to PGJDBC-specific types) the severity
tag from the backend. So that has to be done here, and
done reflectively, to avoid a hard PGJDBC dependency.

PGJDBC exposes the SEVERITY (S) tag, but not the
SEVERITY_NONLOCALIZED (V) tag that was added in PG 10
(postgres/postgres@26fa446). The upshot is that the rule
used here to recognize WARNING will fail if the backend is
using a language where it's some other word. A new static
method set_WARNING_localized can be used to set the correct
tag (PERINGATAN in Indonesian, for example) so the classification
will happen correctly for the language selected in the backend.

For utility statements with no result, where in pgjdbc-ng
there really is no result, in PGJDBC there is a zero row
count, the same as for a DML statement that touched no rows.
It'll take another commit to make the test state machines
work either way.
---
 pljava-packaging/pom.xml                 |  17 ++
 pljava-packaging/src/main/java/Node.java | 238 +++++++++++++++++++++--
 2 files changed, 235 insertions(+), 20 deletions(-)

diff --git a/pljava-packaging/pom.xml b/pljava-packaging/pom.xml
index b7262e705..ee19ad959 100644
--- a/pljava-packaging/pom.xml
+++ b/pljava-packaging/pom.xml
@@ -64,6 +64,23 @@
 			</properties>
 		</profile>
 
+		<!--
+		  - Activate this profile just as a convenient way to make Maven
+		  - download the pgjdbc driver. It isn't needed in any way for
+		  - building, but then you will have it in your local Maven repository
+		  - if you want to add it to your classpath for some tests.
+		  -->
+		<profile>
+			<id>pgjdbc</id>
+			<dependencies>
+				<dependency>
+					<groupId>org.postgresql</groupId>
+					<artifactId>postgresql</artifactId>
+					<version>[42.6.0,)</version>
+				</dependency>
+			</dependencies>
+		</profile>
+
 		<!--
 		  - Activate this profile just as a convenient way to make Maven
 		  - download the pgjdbc-ng driver. It isn't needed in any way for
diff --git a/pljava-packaging/src/main/java/Node.java b/pljava-packaging/src/main/java/Node.java
index 48deda9de..681385100 100644
--- a/pljava-packaging/src/main/java/Node.java
+++ b/pljava-packaging/src/main/java/Node.java
@@ -32,8 +32,16 @@
 
 import static java.lang.ProcessBuilder.Redirect.INHERIT;
 import java.lang.reflect.InvocationHandler; // flexible SAM allowing exceptions
+import java.lang.reflect.UndeclaredThrowableException;
 import static java.lang.Thread.interrupted;
 
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodHandles.Lookup;
+import static java.lang.invoke.MethodHandles.explicitCastArguments;
+import static java.lang.invoke.MethodHandles.filterReturnValue;
+import static java.lang.invoke.MethodHandles.publicLookup;
+import static java.lang.invoke.MethodType.methodType;
+
 import static java.net.InetAddress.getLoopbackAddress;
 import static java.net.URLEncoder.encode;
 import java.net.ServerSocket;
@@ -59,6 +67,7 @@
 import java.nio.file.NoSuchFileException;
 
 import java.sql.Connection;
+import static java.sql.DriverManager.drivers;
 import static java.sql.DriverManager.getConnection;
 import java.sql.ParameterMetaData;
 import java.sql.PreparedStatement;
@@ -289,6 +298,143 @@ else if ( storedPath.matches(
 	public static final boolean s_isWindows =
 		getProperty("os.name").startsWith("Windows");
 
+	/**
+	 * The first form of PostgreSQL JDBC driver connection URL found to be
+	 * recognized by an available driver, or {@code URL_FORM_NONE}.
+	 */
+	public static final int s_urlForm;
+
+	/**
+	 * Value of {@link #s_urlForm s_urlForm} indicating no available JDBC driver
+	 * was found to accept any of the supported connection URL forms.
+	 */
+	public static final int URL_FORM_NONE = -1;
+
+	/**
+	 * Value of {@link #s_urlForm s_urlForm} indicating an available JDBC driver
+	 * reported accepting a connection URL in the PGJDBC form starting with
+	 * {@code "jdbc:postgresql:"}.
+	 */
+	public static final int URL_FORM_PGJDBC = 0;
+
+	/**
+	 * Value of {@link #s_urlForm s_urlForm} indicating an available JDBC driver
+	 * reported accepting a connection URL in the pgjdbc-ng form starting with
+	 * {@code "jdbc:pgsql:"}.
+	 */
+	public static final int URL_FORM_PGJDBCNG = 1;
+
+	/**
+	 * A function to map an {@code SQLWarning} to a rough classification
+	 * (info, warning) of its severity.
+	 *<p>
+	 * If the PGJDBC {@code PSQLWarning} class is available for access to the
+	 * severity tag from the backend, "warning" will be returned if that tag is
+	 * {@code WARNING}, and "info" will be returned in any other case. (The next
+	 * more severe backup level is {@code ERROR}, which would not appear here as
+	 * an {@code SQLWarning}.)
+	 *<p>
+	 * If the severity tag is not available, "info" will be returned if the
+	 * class (leftmost two positions of SQLState) is 00, otherwise "warning".
+	 */
+	private static final Function<SQLWarning,String> s_toSeverity;
+
+	private static String s_WARNING_localized = "WARNING";
+
+	/**
+	 * Changes the severity string used to recognize when the backend is sending
+	 * a {@code WARNING}.
+	 *<p>
+	 * When the driver is PGJDBC, the classification done here of
+	 * {@code SQLWarning} instances into actual warning messages or informative
+	 * ones depends on a tag ("WARNING" in English) that the backend delivers
+	 * in the local language. For the classification to happen correctly when
+	 * a different language is selected, use this method to supply the string
+	 * (for example, "PERINGATAN" in Indonesian) that the backend uses for
+	 * warnings in that language.
+	 */
+	public static void set_WARNING_localized(String s)
+	{
+		s_WARNING_localized = requireNonNull(s);
+	}
+
+	static
+	{
+		String[] candidateURLs = { "jdbc:postgresql:", "jdbc:pgsql:x" };
+		s_urlForm =
+			IntStream.range(0, candidateURLs.length)
+				.filter(i ->
+					drivers().anyMatch(d ->
+					{
+						try
+						{
+							return d.acceptsURL(candidateURLs[i]);
+						}
+						catch ( SQLException e )
+						{
+							throw new ExceptionInInitializerError(e);
+						}
+					}))
+				.findFirst()
+				.orElse(URL_FORM_NONE);
+
+		Function<SQLWarning,String> toSeverity = Node::toSeverityFallback;
+
+		try
+		{
+			Class<?> psqlWarning =
+				Class.forName("org.postgresql.util.PSQLWarning");
+			Class<?> sErrMessage =
+				Class.forName("org.postgresql.util.ServerErrorMessage");
+
+			Lookup pub = publicLookup();
+
+			MethodHandle getserrm =
+				pub.findVirtual(psqlWarning, "getServerErrorMessage",
+					methodType(sErrMessage));
+			MethodHandle getSev =
+				pub.findVirtual(sErrMessage, "getSeverity",
+					methodType(String.class));
+
+			MethodHandle h = explicitCastArguments(
+				filterReturnValue(getserrm, getSev),
+				methodType(String.class, Object.class));
+
+			toSeverity = w ->
+			{
+				if ( psqlWarning.isInstance(w) )
+				{
+					try
+					{
+						String s = (String)h.invokeExact(psqlWarning.cast(w));
+						if ( null == s  ||  s_WARNING_localized.equals(s) )
+							return "warning";
+						return "info";
+					}
+					catch ( Throwable t )
+					{
+						throw new UndeclaredThrowableException(t, t.getMessage());
+					}
+				}
+
+				return toSeverityFallback(w);
+			};
+		}
+		catch ( ReflectiveOperationException e )
+		{
+		}
+
+		s_toSeverity = toSeverity;
+	}
+
+	private static String toSeverityFallback(SQLWarning w)
+	{
+		if ( w.getSQLState().startsWith("00") )
+			return "info";
+		else
+			return "warning";
+	}
+
 	/**
 	 * Name of a "Node"; null for an ordinary Node instance.
 	 */
@@ -985,18 +1131,43 @@ public Connection connect(Map<String,String> suppliedProperties)
 	 */
 	public Connection connect(Properties p) throws Exception
 	{
-		String url = "jdbc:pgsql://localhost:" + m_port + '/';
+		String url;
+		String dbNameKey;
+		String appNameKey;
+
+		switch ( s_urlForm )
+		{
+		case URL_FORM_PGJDBC:
+			url = "jdbc:postgresql://localhost:" + m_port + '/';
+			dbNameKey = "PGDBNAME";
+			appNameKey = "ApplicationName";
+			break;
+		case URL_FORM_PGJDBCNG:
+			url = "jdbc:pgsql://localhost:" + m_port + '/';
+			dbNameKey = "database.name";
+			appNameKey = "application.name";
+			break;
+		default:
+			throw new UnsupportedOperationException(
+				"no recognized JDBC driver found to connect to the node");
+		}
+
 		p = (Properties)p.clone();
-		p.putIfAbsent("database.name", "postgres");
+		p.putIfAbsent(dbNameKey, "postgres");
 		p.putIfAbsent("user", "postgres");
 		p.putIfAbsent("password", m_password);
-		p.computeIfAbsent("application.name", o -> "Conn" + (m_connCount++));
-		/*
-		 * Contrary to its documentation, pgjdbc-ng does *not* accept a URL with
-		 * the database name omitted. It is no use having it in the properties
-		 * here; it must be appended to the URL.
-		 */
-		url += encode(p.getProperty("database.name"), "UTF-8");
+		p.computeIfAbsent(appNameKey, o -> "Conn" + (m_connCount++));
+
+		if ( URL_FORM_PGJDBCNG == s_urlForm )
+		{
+			/*
+			 * Contrary to its documentation, pgjdbc-ng does *not* accept a URL
+			 * with the database name omitted. It is no use having it in the
+			 * properties here; it must be appended to the URL.
+			 */
+			url += encode(p.getProperty(dbNameKey), "UTF-8");
+		}
+
 		return getConnection(url, p);
 	}
 
@@ -1783,7 +1954,7 @@ public static void peek(Object o)
 	{
 		try
 		{
-			int[] dims = voidResultSetDims(o);
+			int[] dims = voidResultSetDims(o, true); // only peek
 
 			if ( null != dims )
 			{
@@ -1967,6 +2138,12 @@ public static void qp(Throwable t)
 	 *<p>
 	 * The third string will be as returned by {@code getMessage}, and may be
 	 * null if the throwable was not constructed with a message.
+	 *<p>
+	 * If an {@code SQLWarning} is of the PGJDBC driver's {@code PSQLWarning}
+	 * class and the backend's severity tag is available, it will be used to
+	 * determine the first string, in place of the "starts with 00" rule. A tag
+	 * of "WARNING" (or null) produces "warning", while any other tag produces
+	 * "info".
 	 */
 	public static String[] classify(Throwable t)
 	{
@@ -1978,14 +2155,9 @@ public static String[] classify(Throwable t)
 			sqlState = ((SQLException)t).getSQLState();
 			if ( t instanceof SQLWarning )
 			{
-				if ( sqlState.startsWith("00") )
-				{
-					element = "info";
-					if ( "00000".equals(sqlState) )
+				element = s_toSeverity.apply((SQLWarning)t);
+				if ( "info".equals(element) && "00000".equals(sqlState) )
 						sqlState = null;
-				}
-				else
-					element = "warning";
 			}
 		}
 		return new String[] { element, sqlState, msg };
@@ -2038,9 +2210,13 @@ else if ( '"' == c )
 	 * If this method returns non-null, the result set is left positioned on its
 	 * last row.
 	 * @param o Object to check
+	 * @param peek whether to avoid moving the row cursor. If true, and all of
+	 * the columns are indeed void, the result array will have the column count
+	 * at index 1 and -1 at index 0.
 	 * @return null or a two-element int[], as described above
 	 */
-	public static int[] voidResultSetDims(Object o) throws Exception
+	public static int[] voidResultSetDims(Object o, boolean peek)
+	throws Exception
 	{
 		if ( ! (o instanceof ResultSet) )
 			return null;
@@ -2048,14 +2224,36 @@ public static int[] voidResultSetDims(Object o) throws Exception
 		ResultSet rs = (ResultSet)o;
 		ResultSetMetaData md = rs.getMetaData();
 		int cols = md.getColumnCount();
+		int rows = 0;
 
 		for ( int c = 1; c <= cols; ++c )
 			if ( Types.OTHER != md.getColumnType(c)
 				||  ! "void".equals(md.getColumnTypeName(c)) )
 				return null;
 
-		rs.last(); // last(), getRow() appears to work, in pgjdbc-ng
-		return new int[] { rs.getRow(), cols };
+		if ( peek )
+			rows = -1;
+		else if ( URL_FORM_PGJDBCNG == s_urlForm )
+		{
+			rs.last(); // last(), getRow() appears to work, in pgjdbc-ng
+			rows = rs.getRow();
+		}
+		else
+		{
+			while ( rs.next() ) // PGJDBC requires this unless rs is scrollable
+				++ rows;
+		}
+
+		return new int[] { rows, cols };
+	}
+
+	/**
+	 * Equivalent to
+	 * {@link #voidResultSetDims(Object,boolean) voidResultSetDims(o,false)};
+	 */
+	public static int[] voidResultSetDims(Object o)	throws Exception
+	{
+		return voidResultSetDims(o, false);
 	}
 
 	/**

From 2191191b9f9242fcc7e7eda2b3ae9f505d667f68 Mon Sep 17 00:00:00 2001
From: Chapman Flack <chap@anastigmatix.net>
Date: Sun, 17 Sep 2023 18:45:44 -0400
Subject: [PATCH 2/4] Let stateMachine states make relative moves

It would be nice to have a little library of common
stateMachine states, heretofore difficult because the
next state must be indicated by returning an absolute
state number. So, use one of the otherwise-unused parameters
of the InvocationHandler functional interface to supply
a state with its own state number, so it can make relative
moves.

To start the library, here is NOTHING_OR_PGJDBC_ZERO_COUNT,
because the PGJDBC and pgjdbc-ng drivers differ in handling
a utility statement with no result (CREATE EXTENSION, that sort
of thing). In pgjdbc-ng, there is no result, while in PGJDBC,
there is a zero row count, as would be seen for a DML statement
that had not updated anything.

So, NOTHING_OR_PGJDBC_ZERO_COUNT simply moves to the numerically
next state, after consuming (if the driver is pgjdbc-ng) nothing,
or (if the driver is PGJDBC) a zero row count.
---
 .github/workflows/ci-runnerpg.yml        | 16 ++++++-
 appveyor.yml                             | 16 ++++++-
 pljava-packaging/src/main/java/Node.java | 56 +++++++++++++++++++++---
 3 files changed, 79 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/ci-runnerpg.yml b/.github/workflows/ci-runnerpg.yml
index c534680a1..fb456a7fa 100644
--- a/.github/workflows/ci-runnerpg.yml
+++ b/.github/workflows/ci-runnerpg.yml
@@ -215,6 +215,8 @@ jobs:
         import static org.postgresql.pljava.packaging.Node.stateMachine;
         import static org.postgresql.pljava.packaging.Node.isVoidResultSet;
         import static org.postgresql.pljava.packaging.Node.s_isWindows;
+        import static
+            org.postgresql.pljava.packaging.Node.NOTHING_OR_PGJDBC_ZERO_COUNT;
         /*
          * Imports that will be needed to serve a jar file over http
          * when the time comes for testing that.
@@ -339,7 +341,9 @@ jobs:
               // state 1: consume any diagnostics, or to state 2 with same item
               (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
 
-              // state 2: must be end of input
+              NOTHING_OR_PGJDBC_ZERO_COUNT, // state 2
+
+              // state 3: must be end of input
               (o,p,q) -> null == o
             );
           }
@@ -566,6 +570,9 @@ jobs:
                 .peek(Node::peek),
 
                 (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+                NOTHING_OR_PGJDBC_ZERO_COUNT,
+                NOTHING_OR_PGJDBC_ZERO_COUNT,
+                NOTHING_OR_PGJDBC_ZERO_COUNT,
                 (o,p,q) -> null == o
               );
 
@@ -598,6 +605,8 @@ jobs:
               .peek(Node::peek),
 
               (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
               (o,p,q) -> null == o
             );
           }
@@ -633,6 +642,7 @@ jobs:
               .peek(Node::peek),
 
               (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
               (o,p,q) -> null == o
             );
 
@@ -647,6 +657,7 @@ jobs:
                 .peek(Node::peek),
 
                 (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+                NOTHING_OR_PGJDBC_ZERO_COUNT,
                 (o,p,q) -> null == o
               );
             }
@@ -672,6 +683,7 @@ jobs:
               .peek(Node::peek),
 
               (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
               (o,p,q) -> null == o
             );
 
@@ -687,6 +699,8 @@ jobs:
               .peek(Node::peek),
 
               (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
               (o,p,q) -> null == o
             );
           }
diff --git a/appveyor.yml b/appveyor.yml
index a0e534ee2..ed964f202 100644
--- a/appveyor.yml
+++ b/appveyor.yml
@@ -108,6 +108,8 @@ test_script:
       import static org.postgresql.pljava.packaging.Node.q;
       import static org.postgresql.pljava.packaging.Node.stateMachine;
       import static org.postgresql.pljava.packaging.Node.isVoidResultSet;
+      import static
+        org.postgresql.pljava.packaging.Node.NOTHING_OR_PGJDBC_ZERO_COUNT;
       /*
        * Imports that will be needed to serve a jar file over http
        * when the time comes for testing that.
@@ -221,7 +223,9 @@ test_script:
             // state 1: consume any diagnostics, or show same item to state 2
             (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
 
-            // state 2: must be end of input
+            NOTHING_OR_PGJDBC_ZERO_COUNT, // state 2
+
+            // state 3: must be end of input
             (o,p,q) -> null == o
           );
         }
@@ -448,6 +452,9 @@ test_script:
               .peek(Node::peek),
 
               (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
               (o,p,q) -> null == o
             );
 
@@ -480,6 +487,8 @@ test_script:
             .peek(Node::peek),
 
             (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+            NOTHING_OR_PGJDBC_ZERO_COUNT,
+            NOTHING_OR_PGJDBC_ZERO_COUNT,
             (o,p,q) -> null == o
           );
         }
@@ -515,6 +524,7 @@ test_script:
             .peek(Node::peek),
 
             (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+            NOTHING_OR_PGJDBC_ZERO_COUNT,
             (o,p,q) -> null == o
           );
 
@@ -529,6 +539,7 @@ test_script:
               .peek(Node::peek),
 
               (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+              NOTHING_OR_PGJDBC_ZERO_COUNT,
               (o,p,q) -> null == o
             );
           }
@@ -554,6 +565,7 @@ test_script:
             .peek(Node::peek),
 
             (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+            NOTHING_OR_PGJDBC_ZERO_COUNT,
             (o,p,q) -> null == o
           );
 
@@ -569,6 +581,8 @@ test_script:
             .peek(Node::peek),
 
             (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+            NOTHING_OR_PGJDBC_ZERO_COUNT,
+            NOTHING_OR_PGJDBC_ZERO_COUNT,
             (o,p,q) -> null == o
           );
         }
diff --git a/pljava-packaging/src/main/java/Node.java b/pljava-packaging/src/main/java/Node.java
index 681385100..015835600 100644
--- a/pljava-packaging/src/main/java/Node.java
+++ b/pljava-packaging/src/main/java/Node.java
@@ -435,6 +435,29 @@ private static String toSeverityFallback(SQLWarning w)
 			return "warning";
 	}
 
+	/**
+	 * A state (see {@link #stateMachine stateMachine}) that expects nothing
+	 * (if the driver is pgjdbc-ng) or a zero row count (if the driver is
+	 * PGJDBC).
+	 *<p>
+	 * For some utility statements (such as {@code CREATE EXTENSION}) with no
+	 * result, the pgjdbc-ng driver will produce no result, while the PGJDBC
+	 * driver produces a zero count, as it would for a DML statement that did
+	 * not affect any rows. This state handles either case.
+	 *<p>
+	 * When {@code URL_FORM_PGJDBCNG == s_urlForm}, this state consumes nothing
+	 * and moves to the numerically next state. Otherwise (JDBC), it checks
+	 * that the current object is a zero row count, consuming it and moving to
+	 * the numerically next state if it is, returning false otherwise.
+	 */
+	public static final InvocationHandler NOTHING_OR_PGJDBC_ZERO_COUNT=(o,p,q)->
+	{
+		int myStateNum = (int)q[0];
+		if ( URL_FORM_PGJDBCNG == s_urlForm )
+			return -(1 + myStateNum);
+		return 0 == as(Long.class, o) ? 1 + myStateNum : false;
+	};
+
 	/**
 	 * Name of a "Node"; null for an ordinary Node instance.
 	 */
@@ -2312,9 +2335,10 @@ public static boolean isVoidResultSet(Object o, int rows, int columns)
 	 * by {@link InvocationHandler}, an existing functional interface with a
 	 * versatile argument list and permissive {@code throws} clause. Each state
 	 * must be represented as a lambda with three parameters (the convention
-	 * {@code (o,p,q)} is suggested), of which only the first is used. If Java
-	 * ever completes the transition to {@code _} as an unused-parameter marker,
-	 * the suggested convention will be {@code (o,_,_)}.
+	 * {@code (o,p,q)} is suggested), of which only the first is normally used.
+	 * If Java ever completes the transition to {@code _} as an unused-parameter
+	 * marker, the suggested convention will be {@code (o,_,_)}, unless the
+	 * third (<var>q</var>) is also needed for special purposes (more below).
 	 *<p>
 	 * As the input item passed to each state is typed {@code Object}, and as
 	 * null can only represent the end of input, it may be common for a state to
@@ -2324,6 +2348,14 @@ public static boolean isVoidResultSet(Object o, int rows, int columns)
 	 * throw a specific instance of {@code ClassCastException}, which will be
 	 * treated, when caught by {@code stateMachine}, just as if the state
 	 * had returned {@code false}.
+	 *<p>
+	 * The third parameter to an {@code InvocationHandler} is an {@code Object}
+	 * array, and is here used to pass additional information that may at times
+	 * be of use in a state. The first element of the array holds the boxed form
+	 * of the current (1-based) state number. As a state must indicate the next
+	 * state by returning an absolute state number, having the state's own
+	 * number available opens the possibility of reusable presupplied state
+	 * implementations that do not depend on their absolute position.
 	 * @param name A name for this state machine, used only in exception
 	 * messages if it fails to match all the input
 	 * @param reporter a Consumer to accept a diagnostic string if the machine
@@ -2367,7 +2399,8 @@ public static boolean stateMachine(
 					hasCurrent = true;
 				}
 
-				result = invoke(states[currentState], currentInput);
+				result =
+					invoke(states[currentState], currentState, currentInput);
 
 				if ( result instanceof Boolean )
 				{
@@ -2397,7 +2430,7 @@ public static boolean stateMachine(
 			for ( ;; )
 			{
 				++ stepCount;
-				result = invoke(states[currentState], null);
+				result = invoke(states[currentState], currentState, null);
 				if ( result instanceof Boolean  &&  (Boolean)result )
 					return true;
 				else if ( result instanceof Integer  &&  0 > (Integer)result )
@@ -2435,12 +2468,21 @@ public static <T> T as(Class<T> clazz, Object o)
 	private static final ClassCastException failedAsException =
 		new ClassCastException();
 
-	private static Object invoke(InvocationHandler h, Object o)
+	/**
+	 * Invokes the state handler <var>h</var>, passing it the current object
+	 * <var>o</var> and, for special purposes, the state index (adjusted to
+	 * be 1-based).
+	 *<p>
+	 * Conforming to the existing {@code InvocationHandler} interface, the
+	 * state index is passed in boxed form as element zero of an {@code Object}
+	 * array passed as the third argument.
+	 */
+	private static Object invoke(InvocationHandler h, int stateIdx, Object o)
 	throws Exception
 	{
 		try
 		{
-			return h.invoke(o, null, null);
+			return h.invoke(o, null, new Object[] { 1 + stateIdx });
 		}
 		catch ( ClassCastException e )
 		{

From ffb678fb5d45a61a6c608bf0fff03a980c81d225 Mon Sep 17 00:00:00 2001
From: Chapman Flack <chap@anastigmatix.net>
Date: Sun, 17 Sep 2023 18:45:55 -0400
Subject: [PATCH 3/4] Close a Node's Connections when stopping it

This is all about convenience when using JShell interactively,
where try-with-resources gets in the way. The VM shutdown hooks
to stop and clean up the Node work well, but if any Connection
is open at the time, the type of shutdown signalled to the
server may not cause it to be closed, leading to a hang. The
Java Process API does not expose enough types of OS signals
to easily request a faster shutdown. (When the node is using
pg_ctl, that's an option, but not when signaling the server
directly.)

So, have each Node remember the Connections it makes, in a
WeakHashMap. They'll be removed from the map once unreachable
(and if that happens before they're closed, both drivers
include a cleaner task that will eventually close them; there
may be a bit of delay, but that's better than the former hang).
When stopping a Node, close whatever Connections are still
around in the map.
---
 pljava-packaging/src/main/java/Node.java | 96 +++++++++++++++++++++---
 1 file changed, 84 insertions(+), 12 deletions(-)

diff --git a/pljava-packaging/src/main/java/Node.java b/pljava-packaging/src/main/java/Node.java
index 015835600..33b1e2180 100644
--- a/pljava-packaging/src/main/java/Node.java
+++ b/pljava-packaging/src/main/java/Node.java
@@ -99,6 +99,7 @@
 import static java.util.Spliterator.NONNULL;
 import static java.util.Spliterator.ORDERED;
 import static java.util.Spliterators.spliteratorUnknownSize;
+import java.util.WeakHashMap;
 
 import java.util.concurrent.Callable; // like a Supplier but allows exceptions!
 import java.util.concurrent.CancellationException;
@@ -516,6 +517,26 @@ private static String toSeverityFallback(SQLWarning w)
 	 */
 	private boolean m_usePostgres = true;
 
+	/**
+	 * A weakly-held collection of {@link Connection}s, so that any remaining
+	 * unclosed when {@link #stop(UnaryOperator) stop} is called can be closed
+	 * then.
+	 *<p>
+	 * Java takes care of removing {@code Connection}s from this map as they
+	 * become unreachable. In case any become unreachable before being closed,
+	 * both supported JDBC drivers have cleaner actions that will eventually
+	 * close them.
+	 */
+	private final WeakHashMap<Connection,Void> m_connections;
+
+	/**
+	 * True during a {@link #stop(UnaryOperator) stop} call.
+	 *<p>
+	 * Used to prevent any new unclosed {@code Connection} being added to
+	 * {@link m_connections m_connections} undetected.
+	 */
+	private boolean m_stopping = false;
+
 	/**
 	 * Identifying information for a "node" instance, or for the singleton
 	 * extractor instance.
@@ -540,6 +561,7 @@ private Node(String nodeName, int port, Path basedir, String password)
 		m_port = port;
 		m_basedir = basedir;
 		m_password = password;
+		m_connections = null == nodeName ? null : new WeakHashMap<>();
 	}
 
 	/**
@@ -1045,21 +1067,53 @@ public void stop(UnaryOperator<ProcessBuilder> tweaks) throws Exception
 	{
 		if ( null == ( m_usePostgres ? m_server : m_serverHandle ) )
 			return;
-		if ( ! m_usePostgres )
+
+		try
 		{
-			stopViaPgCtl(tweaks);
-			return;
+			Connection[] connections;
+
+			synchronized ( this )
+			{
+				m_stopping = true;
+				connections = // Java >= 10: use a List and List.copyOf
+					m_connections.keySet().stream().toArray(Connection[]::new);
+				m_connections.clear();
+			}
+
+			for ( Connection c : connections )
+			{
+				try
+				{
+					c.close();
+				}
+				catch ( Exception e )
+				{
+				}
+			}
+
+			if ( ! m_usePostgres )
+			{
+				stopViaPgCtl(tweaks);
+				return;
+			}
+			if ( m_server.isAlive() )
+			{
+				m_server.destroy();
+				m_server.waitFor();
+				m_server = null;
+				return;
+			}
+			System.err.println("Server had already exited with status " +
+				m_server.exitValue());
+			m_server = null;
 		}
-		if ( m_server.isAlive() )
+		finally
 		{
-			m_server.destroy();
-			m_server.waitFor();
-			m_server = null;
-			return;
+			synchronized ( this )
+			{
+				m_stopping = false;
+			}
 		}
-		System.err.println("Server had already exited with status " +
-			m_server.exitValue());
-		m_server = null;
 	}
 
 	private void stopViaPgCtl(UnaryOperator<ProcessBuilder> tweaks)
@@ -1191,7 +1245,25 @@ public Connection connect(Properties p) throws Exception
 			url += encode(p.getProperty(dbNameKey), "UTF-8");
 		}
 
-		return getConnection(url, p);
+		Connection c = getConnection(url, p);
+
+		synchronized ( this )
+		{
+			if ( m_stopping )
+			{
+				try
+				{
+					throw new IllegalStateException(
+						"Node " + m_name + " is being stopped");
+				}
+				finally
+				{
+					c.close(); // add any exception as 'suppressed' to above
+				}
+			}
+			m_connections.put(c, null);
+			return c;
+		}
 	}
 
 	/**

From f7d2d5b78f6a231c5ee584ed2280866993f12393 Mon Sep 17 00:00:00 2001
From: Chapman Flack <chap@anastigmatix.net>
Date: Sun, 17 Sep 2023 18:46:03 -0400
Subject: [PATCH 4/4] Update the documentation for the Node test harness

Update the docs chiefly to reflect that either PGJDBC or pgjdbc-ng
may be used as the JDBC driver, and how to accommodate the slight
differences between the two. Numerous other updates, including to more
consistently observe the conventional javadoc style where lead sentences
are third-person rather than second.

In the course of better documenting when tweaks are applied,
caught one place where forWindowsCRuntime would not be applied
on Windows. (The known arguments being supplied right there in
the code could squeak by without it, but who knows what could be
added in a tweak?)
---
 pljava-packaging/src/main/java/Node.java    | 232 +++++++++++---------
 pljava-packaging/src/site/markdown/index.md |   4 +-
 src/site/markdown/develop/node.md           | 148 +++++++++----
 3 files changed, 237 insertions(+), 147 deletions(-)

diff --git a/pljava-packaging/src/main/java/Node.java b/pljava-packaging/src/main/java/Node.java
index 33b1e2180..eb25fd406 100644
--- a/pljava-packaging/src/main/java/Node.java
+++ b/pljava-packaging/src/main/java/Node.java
@@ -119,7 +119,7 @@
 import static java.util.stream.StreamSupport.stream;
 
 /**
- * Subclass the JarX extraction tool to provide a {@code resolve} method that
+ * Extends the JarX extraction tool to provide a {@code resolve} method that
  * replaces prefixes {@code pljava/foo/} in path names stored in the archive
  * with the result of {@code pg_config --foo}.
  *<p>
@@ -128,16 +128,17 @@
  * useful for tasks related to installation and testing. The idea is not to go
  * overboard, but supply a few methods largely modeled on the most basic ones of
  * PostgreSQL's {@code PostgresNode.pm}, with the idea that they can be invoked
- * from {@code jshell} if its classpath includes the installer jar (and
- * pgjdbc-ng).
+ * from {@code jshell} if its classpath includes the installer jar (and one of
+ * the PostgreSQL JDBC drivers).
  *<p>
  * An
  * <a href="../../../../../../develop/node.html">introduction with examples</a>
  * is available.
  *<p>
  * Unlike the many capabilities of {@code PostgresNode.pm}, this only deals in
- * TCP sockets bound to {@code localhost} (Java doesn't have Unix sockets out of
- * the box yet) and only a few of the most basic operations.
+ * TCP sockets bound to {@code localhost} ({@code StandardProtocolFamily.UNIX}
+ * finally arrived in Java 16 but this class does not support it yet) and only
+ * a few of the most basic operations.
  *<p>
  * As in JarX itself, some liberties with coding style may be taken here to keep
  * this one extra {@code .class} file from proliferating into a bunch of them.
@@ -161,7 +162,7 @@ public class Node extends JarX {
 	private static String s_sharedObject;
 
 	/**
-	 * Perform an ordinary installation, using {@code pg_config} or the
+	 * Performs an ordinary installation, using {@code pg_config} or the
 	 * corresponding system properties to learn where the files belong, and
 	 * unpacking the files (not including this class or its ancestors) there.
 	 */
@@ -177,7 +178,7 @@ public static void main(String[] args) throws Exception
 	}
 
 	/**
-	 * Extract the jar contents, just as done in the normal case of running
+	 * Extracts the jar contents, just as done in the normal case of running
 	 * this class with {@code java -jar}.
 	 *<p>
 	 * Only to be called on the singleton instance {@code s_jarxHelper}.
@@ -194,7 +195,7 @@ public void extract() throws Exception
 	}
 
 	/**
-	 * Prepare the resolver, ignoring the passed string (ordinarily a script or
+	 * Prepares the resolver, ignoring the passed string (ordinarily a script or
 	 * rules); this resolver's rules are hardcoded.
 	 */
 	@Override
@@ -550,7 +551,7 @@ public String toString()
 	}
 
 	/**
-	 * Construct an instance; all nulls for the parameters are passed by the
+	 * Constructs an instance; all nulls for the parameters are passed by the
 	 * static initializer to make the singleton extractor instance, and any
 	 * other instance is constructed by {@code get_new_node} for controlling
 	 * a PostgreSQL instance.
@@ -565,7 +566,7 @@ private Node(String nodeName, int port, Path basedir, String password)
 	}
 
 	/**
-	 * Return a new {@code Node} that can be used to initialize and start a
+	 * Returns a new {@code Node} that can be used to initialize and start a
 	 * PostgreSQL instance.
 	 *<p>
 	 * Establishes a VM shutdown hook that will stop the server (if started)
@@ -598,7 +599,7 @@ public static Node get_new_node(String name) throws Exception
 	}
 
 	/**
-	 * Return a TCP port on the loopback interface that is free at the moment
+	 * Returns a TCP port on the loopback interface that is free at the moment
 	 * this method is called.
 	 */
 	public static int get_free_port() throws Exception
@@ -610,7 +611,7 @@ public static int get_free_port() throws Exception
 	}
 
 	/**
-	 * Recursively remove the <em>basedir</em> and its descendants.
+	 * Recursively removes the <em>basedir</em> and its descendants.
 	 */
 	public void clean_node() throws Exception
 	{
@@ -618,7 +619,8 @@ public void clean_node() throws Exception
 	}
 
 	/**
-	 * Recursively remove the <em>basedir</em> and its descendants.
+	 * Recursively removes the <em>basedir</em> (unless <var>keepRoot</var>)
+	 * and its descendants.
 	 * @param keepRoot if true, the descendants are removed, but not the basedir
 	 * itself.
 	 */
@@ -657,7 +659,8 @@ public void clean_node(boolean keepRoot) throws Exception
 	}
 
 	/**
-	 * Process the jar without really extracting, to compute the path mappings.
+	 * Processes the jar without really extracting, to compute
+	 * the path mappings.
 	 */
 	private static void dryExtract() throws Exception
 	{
@@ -678,7 +681,7 @@ private static void dryExtract() throws Exception
 	 * Given a path from the archive, or any path <em>resembling</em> one in
 	 * the archive (that is, always {@code /} as the separator, and starting
 	 * with {@code pljava/}<em>key</em> where {@code --}<em>key</em> is known
-	 * to {@code pg_config}, return the platform-specific path where it would
+	 * to {@code pg_config}, returns the platform-specific path where it would
 	 * be installed.
 	 */
 	private static String resolve(String archivePath) throws Exception
@@ -688,7 +691,7 @@ private static String resolve(String archivePath) throws Exception
 	}
 
 	/**
-	 * Return the directory name to be used as the PostgreSQL data directory
+	 * Returns the directory name to be used as the PostgreSQL data directory
 	 * for this node.
 	 */
 	public Path data_dir()
@@ -721,7 +724,8 @@ public AutoCloseable initialized_cluster(Map<String,String> suppliedOptions)
 	}
 
 	/**
-	 * Like {@code init()} but returns an {@code AutoCloseable} that will
+	 * Like {@link #init(Map,UnaryOperator) init()} but returns
+	 * an {@code AutoCloseable} that will
 	 * recursively remove the files and directories under the <em>basedir</em>
 	 * (but not the <em>basedir</em> itself) on the exit of a calling
 	 * try-with-resources scope.
@@ -734,7 +738,8 @@ public AutoCloseable initialized_cluster(
 	}
 
 	/**
-	 * Like {@code init()} but returns an {@code AutoCloseable} that will
+	 * Like {@link #init(Map,UnaryOperator) init()} but returns
+	 * an {@code AutoCloseable} that will
 	 * recursively remove the files and directories under the <em>basedir</em>
 	 * (but not the <em>basedir</em> itself) on the exit of a calling
 	 * try-with-resources scope.
@@ -752,7 +757,7 @@ public AutoCloseable initialized_cluster(
 	}
 
 	/**
-	 * Invoke {@code initdb} for the node, passing default options appropriate
+	 * Invokes {@code initdb} for the node, passing default options appropriate
 	 * for this setting.
 	 */
 	public void init() throws Exception
@@ -761,7 +766,7 @@ public void init() throws Exception
 	}
 
 	/**
-	 * Invoke {@code initdb} for the node, with <em>suppliedOptions</em>
+	 * Invokes {@code initdb} for the node, with <em>suppliedOptions</em>
 	 * overriding or supplementing the ones that would be passed by default.
 	 */
 	public void init(Map<String,String> suppliedOptions) throws Exception
@@ -770,9 +775,9 @@ public void init(Map<String,String> suppliedOptions) throws Exception
 	}
 
 	/**
-	 * Invoke {@code initdb} for the node, passing default options appropriate
-	 * for this setting, and tweaks to be applied to the
-	 * {@code ProcessBuilder} before it is started.
+	 * Invokes {@code initdb} for the node, passing default options appropriate
+	 * for this setting, and {@linkplain #init(Map,UnaryOperator) tweaks} to be
+	 * applied to the {@code ProcessBuilder} before it is started.
 	 */
 	public void init(UnaryOperator<ProcessBuilder> tweaks) throws Exception
 	{
@@ -780,7 +785,7 @@ public void init(UnaryOperator<ProcessBuilder> tweaks) throws Exception
 	}
 
 	/**
-	 * Invoke {@code initdb} for the node, with <em>suppliedOptions</em>
+	 * Invokes {@code initdb} for the node, with <em>suppliedOptions</em>
 	 * overriding or supplementing the ones that would be passed by default,
 	 * and <em>tweaks</em> to be applied to the {@code ProcessBuilder}
 	 * before it is started.
@@ -796,7 +801,9 @@ public void init(UnaryOperator<ProcessBuilder> tweaks) throws Exception
 	 * @param suppliedOptions a Map where each key is an option to initdb
 	 * (for example, --encoding), and the value corresponds.
 	 * @param tweaks a lambda applicable to the {@code ProcessBuilder} to
-	 * further configure it.
+	 * further configure it. On Windows, the tweaks will be applied ahead of
+	 * transformation of the arguments by
+	 * {@link #forWindowsCRuntime forWindowsCRuntime}.
 	 */
 	public void init(
 		Map<String,String> suppliedOptions,
@@ -890,8 +897,13 @@ public AutoCloseable started_server(Map<String,String> suppliedOptions)
 	}
 
 	/**
-	 * Like {@code start()} but returns an {@code AutoCloseable} that will
+	 * Like {@link #start(Map,UnaryOperator) start()} but returns
+	 * an {@code AutoCloseable} that will
 	 * stop the server on the exit of a calling try-with-resources scope.
+	 *<p>
+	 * Supplied <em>tweaks</em> will be applied to the {@code ProcessBuilder}
+	 * used to start the server; if {@code pg_ctl} is being used, they will also
+	 * be applied when running {@code pg_ctl stop} to stop it.
 	 */
 	public AutoCloseable started_server(UnaryOperator<ProcessBuilder> tweaks)
 	throws Exception
@@ -900,7 +912,8 @@ public AutoCloseable started_server(UnaryOperator<ProcessBuilder> tweaks)
 	}
 
 	/**
-	 * Like {@code start()} but returns an {@code AutoCloseable} that will
+	 * Like {@link #start(Map,UnaryOperator) start()} but returns
+	 * an {@code AutoCloseable} that will
 	 * stop the server on the exit of a calling try-with-resources scope.
 	 *<p>
 	 * Supplied <em>tweaks</em> will be applied to the {@code ProcessBuilder}
@@ -920,7 +933,7 @@ public AutoCloseable started_server(
 	}
 
 	/**
-	 * Start a PostgreSQL server for the node with default options appropriate
+	 * Starts a PostgreSQL server for the node with default options appropriate
 	 * for this setting.
 	 */
 	public void start() throws Exception
@@ -929,7 +942,7 @@ public void start() throws Exception
 	}
 
 	/**
-	 * Start a PostgreSQL server for the node, with <em>suppliedOptions</em>
+	 * Starts a PostgreSQL server for the node, with <em>suppliedOptions</em>
 	 * overriding or supplementing the ones that would be passed by default.
 	 */
 	public void start(Map<String,String> suppliedOptions) throws Exception
@@ -938,8 +951,9 @@ public void start(Map<String,String> suppliedOptions) throws Exception
 	}
 
 	/**
-	 * Start a PostgreSQL server for the node, passing default options
-	 * appropriate for this setting, and tweaks to be
+	 * Starts a PostgreSQL server for the node, passing default options
+	 * appropriate for this setting, and
+	 * {@linkplain #start(Map,UnaryOperator) tweaks} to be
 	 * applied to the {@code ProcessBuilder} before it is started.
 	 */
 	public void start(UnaryOperator<ProcessBuilder> tweaks) throws Exception
@@ -948,7 +962,7 @@ public void start(UnaryOperator<ProcessBuilder> tweaks) throws Exception
 	}
 
 	/**
-	 * Start a PostgreSQL server for the node, with <em>suppliedOptions</em>
+	 * Starts a PostgreSQL server for the node, with <em>suppliedOptions</em>
 	 * overriding or supplementing the ones that would be passed by default, and
 	 * <em>tweaks</em> to be applied to the {@code ProcessBuilder} before it
 	 * is started.
@@ -970,7 +984,11 @@ public void start(UnaryOperator<ProcessBuilder> tweaks) throws Exception
 	 * name as seen in {@code postgresql.conf} or passed to the server with
 	 * {@code -c} and the value corresponds.
 	 * @param tweaks a lambda applicable to the {@code ProcessBuilder} to
-	 * further configure it.
+	 * further configure it. Under {@link #use_pg_ctl use_pg_ctl(true)}, the
+	 * tweaks are applied after the arguments have been transformed by
+	 * {@link #asPgCtlInvocation asPgCtlInvocation}. On Windows, they are
+	 * applied ahead of transformation of the arguments by
+	 * {@link #forWindowsCRuntime forWindowsCRuntime}.
 	 */
 	public void start(
 		Map<String,String> suppliedOptions,
@@ -1044,7 +1062,7 @@ public void start(
 
 
 	/**
-	 * Stop the server instance associated with this Node.
+	 * Stops the server instance associated with this Node.
 	 *<p>
 	 * Has the effect of {@link #stop(UnaryOperator) stop(tweaks)} without
 	 * any tweaks.
@@ -1055,13 +1073,15 @@ public void stop() throws Exception
 	}
 
 	/**
-	 * Stop the server instance associated with this Node.
+	 * Stops the server instance associated with this Node.
 	 *<p>
 	 * No effect if it has not been started or has already been stopped, but
 	 * a message to standard error is logged if the server had been started and
 	 * the process is found to have exited unexpectedly.
-	 * @param tweaks tweaks to apply to a ProcessBuilder; unused unless pg_ctl
-	 * will be used to stop the server
+	 * @param tweaks tweaks to apply to a ProcessBuilder; unused unless
+	 * {@code pg_ctl} will be used to stop the server. When used, they are
+	 * applied ahead of the transformation of the arguments by
+	 * {@link #forWindowsCRuntime forWindowsCRuntime} used on Windows.
 	 */
 	public void stop(UnaryOperator<ProcessBuilder> tweaks) throws Exception
 	{
@@ -1132,6 +1152,10 @@ private void stopViaPgCtl(UnaryOperator<ProcessBuilder> tweaks)
 			.redirectOutput(INHERIT)
 			.redirectError(INHERIT);
 		pb = tweaks.apply(pb);
+
+		if ( s_isWindows )
+			pb = forWindowsCRuntime(pb);
+
 		Process p = pb.start();
 		p.getOutputStream().close();
 
@@ -1158,7 +1182,7 @@ private void stopViaPgCtl(UnaryOperator<ProcessBuilder> tweaks)
 	}
 
 	/**
-	 * Indicate whether to use {@code pg_ctl} to start and stop the server
+	 * Sets whether to use {@code pg_ctl} to start and stop the server
 	 * (if true), or start {@code postgres} and stop it directly (if false,
 	 * the default).
 	 *<p>
@@ -1175,7 +1199,7 @@ public void use_pg_ctl(boolean setting)
 	}
 
 	/**
-	 * Return a {@code Connection} to the server associated with this Node,
+	 * Returns a {@code Connection} to the server associated with this Node,
 	 * using default properties appropriate for this setting.
 	 */
 	public Connection connect() throws Exception
@@ -1184,7 +1208,7 @@ public Connection connect() throws Exception
 	}
 
 	/**
-	 * Return a {@code Connection} to the server associated with this Node,
+	 * Returns a {@code Connection} to the server associated with this Node,
 	 * with <em>suppliedProperties</em> overriding or supplementing the ones
 	 * that would be passed by default.
 	 */
@@ -1197,7 +1221,7 @@ public Connection connect(Map<String,String> suppliedProperties)
 	}
 
 	/**
-	 * Return a {@code Connection} to the server associated with this Node,
+	 * Returns a {@code Connection} to the server associated with this Node,
 	 * with supplied properties <em>p</em> overriding or supplementing the ones
 	 * that would be passed by default.
 	 *<p>
@@ -1267,12 +1291,12 @@ public Connection connect(Properties p) throws Exception
 	}
 
 	/**
-	 * Set a configuration variable on the server.
+	 * Sets a configuration variable on the server.
 	 *<p>
 	 * This deserves a convenience method because the most familiar PostgreSQL
 	 * syntax for SET doesn't lend itself to parameterization.
-	 * @return a {@link #q(Statement,Callable) result stream} from executing
-	 * the statement
+	 * @return a {@linkplain #q(Statement,Callable) result stream} from
+	 * executing the statement
 	 */
 	public static Stream<Object> setConfig(
 		Connection c, String settingName, String newValue, boolean isLocal)
@@ -1287,7 +1311,8 @@ public static Stream<Object> setConfig(
 	}
 
 	/**
-	 * Load PL/Java (with a {@code LOAD} command, not {@code CREATE EXTENSION}).
+	 * Loads PL/Java (with a {@code LOAD} command,
+	 * not {@code CREATE EXTENSION}).
 	 *<p>
 	 * This was standard procedure in PostgreSQL versions that pre-dated the
 	 * extension support. It is largely obsolete with the advent of
@@ -1299,8 +1324,12 @@ public static Stream<Object> setConfig(
 	 * that {@code pljava.module_path} is set correctly to locate the jar files,
 	 * and give the correct shared-object path to {@code LOAD} (which this
 	 * method does).
-	 * @return a {@link #q(Statement,Callable) result stream} from executing
-	 * the statement
+	 *<p>
+	 * It is also useful to see better diagnostics if something is going wrong,
+	 * as PostgreSQL severely suppresses diagnostic messages during
+	 * {@code CREATE EXTENSION}.
+	 * @return a {@linkplain #q(Statement,Callable) result stream} from
+	 * executing the statement
 	 */
 	public static Stream<Object> loadPLJava(Connection c) throws Exception
 	{
@@ -1320,9 +1349,9 @@ public static Stream<Object> loadPLJava(Connection c) throws Exception
 	}
 
 	/**
-	 * Install a jar.
-	 * @return a {@link #q(Statement,Callable) result stream} from executing
-	 * the statement
+	 * Installs a jar.
+	 * @return a {@linkplain #q(Statement,Callable) result stream} from
+	 * executing the statement
 	 */
 	public static Stream<Object> installJar(
 		Connection c, String uri, String jarName, boolean deploy)
@@ -1337,9 +1366,9 @@ public static Stream<Object> installJar(
 	}
 
 	/**
-	 * Remove a jar.
-	 * @return a {@link #q(Statement,Callable) result stream} from executing
-	 * the statement
+	 * Removes a jar.
+	 * @return a {@linkplain #q(Statement,Callable) result stream} from
+	 * executing the statement
 	 */
 	public static Stream<Object> removeJar(
 		Connection c, String jarName, boolean undeploy)
@@ -1353,9 +1382,9 @@ public static Stream<Object> removeJar(
 	}
 
 	/**
-	 * Set the class path for a schema.
-	 * @return a {@link #q(Statement,Callable) result stream} from executing
-	 * the statement
+	 * Sets the class path for a schema.
+	 * @return a {@linkplain #q(Statement,Callable) result stream} from
+	 * executing the statement
 	 */
 	public static Stream<Object> setClasspath(
 		Connection c, String schema, String... jarNames)
@@ -1369,10 +1398,11 @@ public static Stream<Object> setClasspath(
 	}
 
 	/**
-	 * Append a jar to a schema's class path if not already included.
-	 * @return a {@link #q(Statement,Callable) result stream} that includes, on
-	 * success, a one-column {@code void} result set with a single row if the
-	 * jar was added to the path, and no rows if the jar was already included.
+	 * Appends a jar to a schema's class path if not already included.
+	 * @return a {@linkplain #q(Statement,Callable) result stream} that
+	 * includes, on success, a one-column {@code void} result set with a single
+	 * row if the jar was added to the path, and no rows if the jar was already
+	 * included.
 	 */
 	public static Stream<Object> appendClasspathIf(
 		Connection c, String schema, String jarName)
@@ -1405,9 +1435,9 @@ public static Stream<Object> appendClasspathIf(
 	}
 
 	/**
-	 * Execute some arbitrary SQL
-	 * @return a {@link #q(Statement,Callable) result stream} from executing
-	 * the statement
+	 * Executes some arbitrary SQL
+	 * @return a {@linkplain #q(Statement,Callable) result stream} from
+	 * executing the statement
 	 */
 	public static Stream<Object> q(Connection c, String sql) throws Exception
 	{
@@ -1788,8 +1818,8 @@ public static Stream<Object> q(final ParameterMetaData pmd)
 	}
 
 	/**
-	 * Execute some arbitrary SQL and pass
-	 * the {@link #q(Statement,Callable) result stream}
+	 * Executes some arbitrary SQL and passes
+	 * the {@linkplain #q(Statement,Callable) result stream}
 	 * to {@link #qp(Stream)} for printing to standard output.
 	 */
 	public static void qp(Connection c, String sql) throws Exception
@@ -1798,8 +1828,8 @@ public static void qp(Connection c, String sql) throws Exception
 	}
 
 	/**
-	 * Invoke some {@code execute} method on a {@code Statement} and pass
-	 * the {@link #q(Statement,Callable) result stream}
+	 * Invokes some {@code execute} method on a {@code Statement} and passes
+	 * the {@linkplain #q(Statement,Callable) result stream}
 	 * to {@link #qp(Stream)} for printing to standard output.
 	 *<p>
 	 * This is how, for example, to prepare, then print the results of, a
@@ -1818,7 +1848,7 @@ public static void qp(Statement s, Callable<Boolean> work) throws Exception
 	}
 
 	/**
-	 * Return true if the examples jar includes the
+	 * Returns true if the examples jar includes the
 	 * {@code org.postgresql.pljava.example.saxon.S9} class (meaning the
 	 * appropriate Saxon jar must be installed and on the classpath first before
 	 * the examples jar can be deployed, unless {@code check_function_bodies}
@@ -1836,12 +1866,12 @@ public static boolean examplesNeedSaxon() throws Exception
 	}
 
 	/**
-	 * Install the examples jar, under the name {@code examples}.
+	 * Installs the examples jar, under the name {@code examples}.
 	 *<p>
 	 * The jar is specified by a {@code file:} URI and the path is the one where
 	 * this installer installed (or would have installed) it.
-	 * @return a {@link #q(Statement,Callable) result stream} from executing
-	 * the statement
+	 * @return a {@linkplain #q(Statement,Callable) result stream} from
+	 * executing the statement
 	 */
 	public static Stream<Object> installExamples(Connection c, boolean deploy)
 	throws Exception
@@ -1853,15 +1883,15 @@ public static Stream<Object> installExamples(Connection c, boolean deploy)
 	}
 
 	/**
-	 * Install the examples jar, under the name {@code examples}, and append it
-	 * to the class path for schema {@code public}.
+	 * Installs the examples jar, under the name {@code examples}, and appends
+	 * it to the class path for schema {@code public}.
 	 *<p>
 	 * The return of a concatenated result stream from two consecutive
 	 * statements might be likely to fail in cases where the first
-	 * statement has any appreciable data to return, but pgjdbc-ng seems to
+	 * statement has any appreciable data to return, but the drivers seem to
 	 * handle it at least in this case where each statement just returns one
 	 * row / one column of {@code void}. And it is convenient.
-	 * @return a combined {@link #q(Statement,Callable) result stream} from
+	 * @return a combined {@linkplain #q(Statement,Callable) result stream} from
 	 * executing the statements
 	 */
 	public static Stream<Object> installExamplesAndPath(
@@ -1874,11 +1904,11 @@ public static Stream<Object> installExamplesAndPath(
 	}
 
 	/**
-	 * Install a Saxon jar under the name {@code saxon}, given the path to a
+	 * Installs a Saxon jar under the name {@code saxon}, given the path to a
 	 * local Maven repo and the needed version of Saxon, assuming the jar has
 	 * been downloaded there already.
-	 * @return a {@link #q(Statement,Callable) result stream} from executing
-	 * the statement
+	 * @return a {@linkplain #q(Statement,Callable) result stream} from
+	 * executing the statement
 	 */
 	public static Stream<Object> installSaxon(
 		Connection c, String repo, String version)
@@ -1891,9 +1921,9 @@ public static Stream<Object> installSaxon(
 	}
 
 	/**
-	 * Install a Saxon jar under the name {@code saxon}, and append it to the
+	 * Installs a Saxon jar under the name {@code saxon}, and appends it to the
 	 * class path for schema {@code public}.
-	 * @return a combined {@link #q(Statement,Callable) result stream} from
+	 * @return a combined {@linkplain #q(Statement,Callable) result stream} from
 	 * executing the statements
 	 */
 	public static Stream<Object> installSaxonAndPath(
@@ -1906,13 +1936,13 @@ public static Stream<Object> installSaxonAndPath(
 	}
 
 	/**
-	 * A four-fer: install Saxon, add it to the class path, then install the
-	 * examples jar, and update the classpath to include both.
+	 * A four-fer: installs Saxon, adds it to the class path, then installs the
+	 * examples jar, and updates the classpath to include both.
 	 * @param repo the base directory of a local Maven repository into which the
 	 * Saxon jar has been downloaded
 	 * @param version the needed version of Saxon
 	 * @param deploy whether to run the example jar's deployment code
-	 * @return a combined {@link #q(Statement,Callable) result stream} from
+	 * @return a combined {@linkplain #q(Statement,Callable) result stream} from
 	 * executing the statements
 	 */
 	public static Stream<Object> installSaxonAndExamplesAndPath(
@@ -1975,7 +2005,7 @@ else if ( oneResult instanceof SQLException )
 	}
 
 	/**
-	 * Print streamed results of a {@code Statement} in (somewhat) readable
+	 * Prints streamed results of a {@code Statement} in (somewhat) readable
 	 * fashion.
 	 *<p>
 	 * Uses {@code writeXml} of {@code WebRowSet}, which is very verbose, but
@@ -1993,7 +2023,7 @@ public static void qp(Stream<Object> s) throws Exception
 	}
 
 	/**
-	 * Print streamed results of a {@code Statement} in (somewhat) readable
+	 * Prints streamed results of a {@code Statement} in (somewhat) readable
 	 * fashion, with a choice of flattener for diagnostics.
 	 *<p>
 	 * For <em>flattener</em>, see {@link flattenDiagnostics flattenDiagnostics}
@@ -2190,14 +2220,14 @@ private static void qp(RowSetMetaDataImpl mdi) throws Exception
 	}
 
 	/**
-	 * Print a {@code Throwable} retrieved from a result stream, with
+	 * Prints a {@code Throwable} retrieved from a result stream, with
 	 * special handling for {@code SQLException} and {@code SQLWarning}.
 	 *<p>
 	 * In keeping with the XMLish vibe established by
 	 * {@link #qp(Stream) qp} for other items in a result
 	 * stream, this will render a {@code Throwable} as an {@code error},
 	 * {@code warning}, or {@code info} element (PostgreSQL's finer
-	 * distinctions of severity are not exposed by pgjdbc-ng's API.)
+	 * distinctions of severity are not exposed by every JDBC driver's API.)
 	 *<p>
 	 * An element will have a {@code message} attribute if it has a message.
 	 * It will have a {@code code} attribute containing the SQLState, if it is
@@ -2219,8 +2249,8 @@ public static void qp(Throwable t)
 	}
 
 	/**
-	 * Return an array of three {@code String}s, element, sqlState, and message,
-	 * as would be printed by {@link #qp(Throwable)}.
+	 * Returns an array of three {@code String}s, element, sqlState,
+	 * and message, as would be printed by {@link #qp(Throwable)}.
 	 *<p>
 	 * The first string will be: (1) if the throwable is an {@code SQLWarning},
 	 * "info" if its class (leftmost two positions of SQLState) is 00, otherwise
@@ -2259,11 +2289,11 @@ public static String[] classify(Throwable t)
 	}
 
 	/**
-	 * Escape a string as an XML attribute.
+	 * Escapes a string as an XML attribute.
 	 *<p>
 	 * Right on the borderline of trivial enough to implement here rather than
-	 * forcing the beleaguered user to add yet one more --add-modules for
-	 * {@code java.xml} just to run this in {@code jshell}.
+	 * using `java.xml` APIs (even though those are available in `jshell` too,
+	 * transitively supplied by our reliance on `java.sql`).
 	 */
 	private static String asAttribute(String s)
 	{
@@ -2352,7 +2382,7 @@ public static int[] voidResultSetDims(Object o)	throws Exception
 	}
 
 	/**
-	 * Predicate testing that an object is a {@code ResultSet} that has only
+	 * A predicate testing that an object is a {@code ResultSet} that has only
 	 * columns of {@code void} type, and the expected number of rows
 	 * and columns.
 	 *<p>
@@ -2371,7 +2401,7 @@ public static boolean isVoidResultSet(Object o, int rows, int columns)
 	/**
 	 * Executes a state machine specified in the form of
 	 * a list of lambdas representing its states, to verify that a
-	 * {@link #q(Statement,Callable) result stream} is as expected.
+	 * {@linkplain #q(Statement,Callable) result stream} is as expected.
 	 *<p>
 	 * Treats the list of lambdas as a set of consecutively-numbered states
 	 * (the first in the list is state number 1, and is the initial state).
@@ -2431,7 +2461,7 @@ public static boolean isVoidResultSet(Object o, int rows, int columns)
 	 * @param name A name for this state machine, used only in exception
 	 * messages if it fails to match all the input
 	 * @param reporter a Consumer to accept a diagnostic string if the machine
-	 * fails to match, defaulting if null to System.err::println
+	 * fails to match, defaulting if null to {@code System.err::println}
 	 * @param input A Stream of input items, of which none may be null
 	 * @param states Lambdas representing states of the machine
 	 * @return true if an accepting state was reached coinciding with the end
@@ -2590,7 +2620,7 @@ private static Object invoke(InvocationHandler h, int stateIdx, Object o)
 	private static final String PM_STATUS_READY = "ready   ";
 
 	/**
-	 * Wait for the {@code postmaster.pid} file to have the right contents
+	 * Waits for the {@code postmaster.pid} file to have the right contents
 	 * (the right pid for process <em>p</em>, and ready status for PG 10+).
 	 *<p>
 	 * The {code PostgresNode.pm} version of this is also used when shutting
@@ -2772,9 +2802,9 @@ && waitPrePG10() )
 	}
 
 	/**
-	 * Check whether the server being started is earlier than PG 10 and, if so,
-	 * sleep for a period expected to be adequate for it to become ready to
-	 * accept connections, then return true.
+	 * Checks whether the server being started is earlier than PG 10 and, if so,
+	 * sleeps for a period expected to be adequate for it to become ready to
+	 * accept connections, then returns true.
 	 *<p>
 	 * This is called from the generic {@code wait_for_pid_file}, only if the
 	 * file has already appeared and has all entries but {@code PM_STATUS}. That
@@ -2824,7 +2854,7 @@ private boolean waitPrePG10() throws Exception
 	 * changes there if desirable.
 	 */
 	/**
-	 * Adjust the command arguments of a {@code ProcessBuilder} so that they
+	 * Adjusts the command arguments of a {@code ProcessBuilder} so that they
 	 * will be recovered correctly on Windows by a target C/C++ program using
 	 * the argument parsing algorithm of the usual C run-time code, when it is
 	 * known that the command will not be handled first by {@code cmd}.
@@ -3004,7 +3034,7 @@ public static ProcessBuilder forWindowsCRuntime(ProcessBuilder pb)
 	}
 
 	/**
-	 * Adjust the command arguments of a {@code ProcessBuilder} that would
+	 * Adjusts the command arguments of a {@code ProcessBuilder} that would
 	 * directly invoke {@code postgres} to start a server, so that it will
 	 * instead start {@code postgres} via {@code pg_ctl}.
 	 *<p>
diff --git a/pljava-packaging/src/site/markdown/index.md b/pljava-packaging/src/site/markdown/index.md
index 8a1e332d9..1e0773a46 100644
--- a/pljava-packaging/src/site/markdown/index.md
+++ b/pljava-packaging/src/site/markdown/index.md
@@ -28,9 +28,11 @@ That allows `jshell` to serve as an environment for scripting tests
 of PL/Java in a running PostgreSQL instance, with capabilities similar to
 (and modeled on) the [PostgresNode][] Perl module distributed with PostgreSQL.
 
-See the javadoc for [the Node class][node] for details.
+See [this introduction][nodetut] and the javadoc for [the Node class][node]
+for details.
 
 [install]: ../install/install.html
 [JShell]: https://docs.oracle.com/javase/9/jshell/introduction-jshell.htm
 [PostgresNode]: https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/test/perl/PostgresNode.pm;h=aec3b9a;hb=e640093
 [node]: apidocs/org/postgresql/pljava/packaging/Node.html
+[nodetut]: ../develop/node.html
diff --git a/src/site/markdown/develop/node.md b/src/site/markdown/develop/node.md
index 1011182d2..ae647da14 100644
--- a/src/site/markdown/develop/node.md
+++ b/src/site/markdown/develop/node.md
@@ -51,7 +51,7 @@ installer jar on its classpath, and you have an interactive, scriptable version
 of Java, with the methods of `Node.class` available in it.
 
 The ones that correspond to the Perl example above have the same names, for
-consistency (right down to the Perlish spelling with underscores rather than
+familiarity (right down to the Perlish spelling with underscores rather than
 Javaish camelCase):
 
 ```java
@@ -67,7 +67,8 @@ n1.clean_node()
 `jshell` has to be run with a rather lengthy command line to get to this point;
 more on that later. But once started, it presents a familiar `PostgresNode`-like
 environment. As the example shows, `jshell` is lenient about statement-ending
-semicolons.
+semicolons. (It is still advisable to use them, though; that leniency has fiddly
+exceptions, such as not applying to pasted text.)
 
 ## `Node.class` in detail
 
@@ -102,19 +103,16 @@ The full set of `Node` methods available can be seen
 
 Running `initdb` and starting a server are all well and good, but sooner or
 later a test may need to connect to it. That requires a JDBC driver to be on the
-classpath also: specifically `pgjdbc-ng` (at least, that is the one that's been
-tested and whose URL syntax is built in to `Node`). The older `pgjdbc` punts on
-the correct handling of warning/notice responses from the server, which seems
-rather disqualifying for a testing environment. In `pgjdbc-ng`, notices and
-warnings (any PostgreSQL severity less than `ERROR` and at or above the
-`client_min_messages` setting) are chained together as `SQLWarning` instances,
-as JDBC provides.
-
-A new profile has been added to PL/Java's Maven build, and can be activated with
-`-Ppgjdbc-ng` on the `mvn` command line. It has no effect but to declare an
-extra dependency on the `pgjdbc-ng` dependencies-included jar. It is not used in
-the build, but Maven will have downloaded it to the local repository, and that
-location can be added to `jshell`'s classpath to make the driver available.
+classpath also; either `PGJDBC` or `pgjdbc-ng` will work, with a few minor
+differences.
+
+New profiles have been added to PL/Java's Maven build, and can be activated with
+`-Ppgjdbc` or `-Ppgjdbc-ng` on the `mvn` command line. They have no effect but
+to declare an extra dependency on the corresponding dependencies-included driver
+jar. It is not used in the build, but Maven will have downloaded it to the local
+repository, and that location can be added to `jshell`'s classpath to make the
+driver available. (In the case of `PGJDBC`, adding the jar to the module path
+also works.)
 
 That addition leads to the final long unwieldy command line needed to start
 `jshell`, which can be seen in all its glory toward the end of this page.
@@ -122,12 +120,12 @@ Once that is copied and pasted into a terminal and any local paths changed, the
 rest is easy:
 
 ```java
-import org.postgresql.pljava.packaging.Node
-Node n1 = Node.get_new_node("TestNode1")
-n1.init()
-n1.start()
-import java.sql.Connection
-Connection c1 = n1.connect()
+import org.postgresql.pljava.packaging.Node;
+Node n1 = Node.get_new_node("TestNode1");
+n1.init();
+n1.start();
+import java.sql.Connection;
+Connection c1 = n1.connect();
 ```
 
 Once you have an open connection (or several), the convenience methods `Node`
@@ -138,11 +136,11 @@ parameter.
 
 ```java
 import static org.postgresql.pljava.packaging.Node.qp; // query-print
-qp(c1, "create table foo (bar int, baz text)")
-qp(c1, "insert into foo (values (1, 'Howdy!'))")
-qp(c1, "select 1/0")
-qp(c1, "select pg_sleep(1.5)")
-qp(c1, "select * from foo")
+qp(c1, "CREATE TABLE foo (bar int, baz text)");
+qp(c1, "INSERT INTO foo (VALUES (1, 'Howdy!'))");
+qp(c1, "SELECT 1/0");
+qp(c1, "SELECT pg_sleep(1.5)");
+qp(c1, "SELECT * FROM foo");
 ```
 
 This example shows `qp` used several different ways: with a DDL statement that
@@ -152,18 +150,18 @@ produces a one-row result with one column typed `void` and always null), and one
 that returns a general query result. What it prints:
 
 ```
-jshell> qp(c1, "create table foo (bar int, baz text)")
+jshell> qp(c1, "CREATE TABLE foo (bar int, baz text)");
 
-jshell> qp(c1, "insert into foo (values (1, 'Howdy!'))")
+jshell> qp(c1, "INSERT INTO foo (VALUES (1, 'Howdy!'))");
 <success rows='1'/>
 
-jshell> qp(c1, "select 1/0")
+jshell> qp(c1, "SELECT 1/0");
 <error code='22012' message='division by zero'/>
 
-jshell> qp(c1, "select pg_sleep(1.5)")
+jshell> qp(c1, "SELECT pg_sleep(1.5)");
 <void rows='1' cols='1'/>
 
-jshell> qp(c1, "select * from foo")
+jshell> qp(c1, "SELECT * FROM foo");
       ...
       <column-type-name>text</column-type-name>
     </column-definition>
@@ -192,6 +190,16 @@ the output format consistent. The `void` output is special treatment for
 the common case of a result set with only the `void` column type, to spare the
 effort of generating a whole `WebRowSet` XML that only shows nothing is there.
 
+The results shown above were obtained with `pgjdbc-ng`. If using `PGJDBC`, you
+will notice these minor differences:
+
+* For the first case shown, DDL with no result, `PGJDBC` will present a zero-row
+    success result, the same as for DML that did not affect any rows. This has
+    to be taken into account if writing a state machine to check results, as
+    discussed further below.
+* The `message` attribute produced for an error will have a prefix of `ERROR: `
+    (or the corresponding word in the PostgreSQL server's configured language).
+
 #### `qp` dissected
 
 `qp` is for interactive, exploratory use, generating printed output. For
@@ -206,7 +214,8 @@ update count), or throwables (caught exceptions, or `SQLWarning` instances). The
 JDBC `Statement` is polled for new `SQLWarning`s before checking for each next
 result (`ResultSet` or update count). An error or exception that is thrown and
 caught will be placed on the stream when caught (and will be the last thing on
-the stream).
+the stream, though it may carry chains of cause, suppressed, or next exceptions
+that may follow it if `flattenDiagnostics` is used on the stream).
 
 All 'notices' from PostgreSQL (severity below `ERROR` but at or above
 `client_min_messages`) are turned into `SQLWarning` instances by `pgjdbc-ng`,
@@ -215,6 +224,16 @@ of the details other than the message and SQLState code. `Node` classifies them
 as `info` if the SQLState 'class' (leftmost two positions) is `00`, otherwise as
 `warning`. Exceptions of any other kind are classified as `error`.
 
+`PGJDBC` also turns notices below `ERROR` into `SQLWarning` instances, but
+provides access to the severity tag from the server, so `Node` uses that to
+classify them as `warning` or `info`, instead of the class `00` rule. If the
+severity is `WARNING` (or happens to be null for some reason), `Node` will
+classify the notice as `warning`; any other severity will be classified as
+`info`. (Note, however, that this scheme will not work if the server is
+configured for a language that uses a different word for `WARNING`. To make it
+work in that case, you can call `Node.set_WARNING_localized` in advance, passing
+the word that PostgreSQL uses for `WARNING` in your language.)
+
 As it happens, there is also an overload of `qp` with just one `Stream<Object>`
 parameter. If you have already run a query with `q` and have the result stream,
 and decide you just want to print that, just pass it to `qp`. There are other
@@ -240,15 +259,15 @@ will install it from there, given a path to the repository root and the desired
 version of Saxon-HE. Not to be outdone, `installSaxonAndExamplesAndPath`
 combines the steps in correct order to install the Saxon jar, place it on the
 classpath, install and deploy the examples jar, and set a final classpath that
-installs both.
+includes both.
 
 ```java
-import static java.nio.file.Paths.get
-import java.sql.Connection
-import org.postgresql.pljava.packaging.Node
-import static org.postgresql.pljava.packaging.Node.qp
+import static java.nio.file.Paths.get;
+import java.sql.Connection;
+import org.postgresql.pljava.packaging.Node;
+import static org.postgresql.pljava.packaging.Node.qp;
 
-Node n1 = Node.get_new_node("TestNode1")
+Node n1 = Node.get_new_node("TestNode1");
 
 try (
   AutoCloseable t1 = n1.initialized_cluster();
@@ -273,8 +292,8 @@ try (
   {
     qp(Node.installSaxonAndExamplesAndPath(c,
       get(System.getProperty("user.home"), ".m2", "repository").toString(),
-      "10.2",
-      true))
+      "10.9",
+      true));
   }
 }
 /exit
@@ -290,6 +309,8 @@ would expect of a test.
 Worked-out examples that do the rest of that can be seen in the project
 repository in the configuration files for the CI testing services.
 
+#### `stateMachine` for checking results
+
 One last `Node` method most useful for checking returned results
 programmatically is `stateMachine` (full description in
 [the javadocs][nodeapi]). For example, the `installSaxonAndExamplesAndPath` call
@@ -353,6 +374,36 @@ The `isDiagnostic` method shown above isn't part of the `Node` class; in the
 actual test configurations in the repository, it is trivially defined in
 `jshell` a few lines earlier. Not everything needs to be built in.
 
+The difference in treatment of no-result DDL statements between drivers (where
+`pgjdbc-ng` really has no result, and `PGJDBC` has a zero-row update count as
+it would for a DML statement) can complicate writing a state machine that works
+with both drivers. `Node` predefines a state function
+`NOTHING_OR_PGJDBC_ZERO_COUNT` that consults the `s_urlForm` static field to
+determine which driver is in use, and then moves to the numerically next state,
+after consuming
+
+* nothing, if the driver is `pgjdbc-ng`, or
+* a single zero row count (rejecting any other input), if the driver
+    is `PGJDBC`.
+
+```java
+succeeding &= stateMachine(
+  "descriptive string for this state machine",
+  null,
+
+  q(c, "CREATE TABLE foo (bar int, baz text)")
+  .flatMap(Node::semiFlattenDiagnostics)
+  .peek(Node::peek), // so they also appear in the log
+
+  (o,p,q) -> isDiagnostic(o, Set.of("error")) ? 1 : -2,
+
+  Node.NOTHING_OR_PGJDBC_ZERO_COUNT,
+
+  (o,p,q) -> null == o
+);
+
+```
+
 ## Invoking `jshell` to use `Node.class`
 
 As hinted above, the command needed to get `jshell` started so all the foregoing
@@ -369,7 +420,8 @@ jshell \
 ```
 
 where _$packageJar_ is a PL/Java self-installer jar, _$jdbcJar_ should point
-to a `pgjdbc-ng` "fat jar" (`pgjdbc-ng-all`), and _$pgConfig_ should point to
+to a "fat jar" for the JDBC driver of choice (`postgresql-`_version_`.jar` or
+`pgjdbc-ng-all-`_version_`.jar`), and _$pgConfig_ should point to
 the `pg_config` executable for the PostgreSQL installation that should be used.
 (If there is only one PostgreSQL installation or the right `pg_config` will be
 found on the search path, it doesn't have to be specified.)
@@ -379,13 +431,19 @@ The `-J--add-modules` is needed because even though `jshell` treats
 (because of `--execution local`) wouldn't know that without being told.
 
 The path given to `jshell` itself (`--class-path` without the `-J`) does not
-need to mention the `pgjdbc-ng` jar, because it can be a provider of the
+need to mention _$jdbcJar_, because that can be a provider of the
 `java.sql.Driver` service without having to be visible. If the script will
-want to use `pgjdbc-ng`-specific classes, then the jar does have to be
+want to use driver-specific extension classes, then the jar does have to be
 on `jshell`'s class path too.
 
-The `noUnsafe` setting silences a complaint from the `netty` library
-about Java (correctly!) denying it access to private internals.
+When the driver is `PGJDBC`, it can be placed on the class path or on the module
+path (in which case it becomes the named module `org.postgresql.jdbc`). Again,
+it does not need to be on `jshell`'s module path also---the one without
+`-J`---unless the script will be referring to driver-specific classes.
+
+The `noUnsafe` setting, needed only when the driver is `pgjdbc-ng`, silences
+a complaint from the `netty` library about Java (correctly!) denying it access
+to private internals.
 
 [jshell]: https://docs.oracle.com/en/java/javase/15/jshell/introduction-jshell.html
 [nodeapi]: ../pljava-packaging/apidocs/org/postgresql/pljava/packaging/Node.html#method.summary