Merge REL1_6_STABLE into master

.github/workflows/ci-runnerpg.yml

@@ -3,7 +3,10 @@
 # does not have a PostgreSQL version in the build matrix. The version that's
 # preinstalled is the version you get.
 
-name: PL/Java CI with PostgreSQL version supplied by the runner
+name: CI with runner-supplied PostgreSQL version
+
+permissions:
+  contents: read
 
 on:
   push:
@@ -22,7 +25,7 @@ jobs:
         oscc:
           - os: ubuntu-latest
             cc: gcc
-          - os: macos-latest
+          - os: macos-12
             cc: clang
 #         - os: windows-latest
 #           cc: msvc

pljava-api/src/main/java/org/postgresql/pljava/annotation/Operator.java

@@ -115,6 +115,16 @@
 	 * different, so the two functions can be distinguished by overloading). A
 	 * typical case would be the twin of a cross-type function like {@code add}
 	 * that is commutative, so using the same name makes sense.
+	 *<p>
+	 * When derived by commutation, the synthetic function simply calls the
+	 * base function with the parameters swapped. For negation, the base
+	 * function must return {@code boolean} or {@code Boolean}, and the
+	 * synthetic function returns true for false, false for true, and null
+	 * for null. This will give familiar SQL behavior in many cases. For a base
+	 * function with {@code onNullInput=CALLED}, if it can return non-null
+	 * boolean results on some null inputs, it may be necessary to code
+	 * a negator or commutator by hand if the synthetic one would not have
+	 * the intended semantics.
 	 */
 	String[] synthetic() default {};
 
@@ -129,16 +139,6 @@
 	 * (which must be different) reversed. A typical case would be the twin of a
 	 * cross-type operator like {@code +} that is commutative, so using the same
 	 * name makes sense.
-	 *<p>
-	 * When derived by commutation, the synthetic function simply calls the
-	 * base function with the parameters swapped. For negation, the base
-	 * function must return {@code boolean} or {@code Boolean}, and the
-	 * synthetic function returns true for false, false for true, and null
-	 * for null. This will give familiar SQL behavior in many cases. For a base
-	 * function with {@code onNullInput=CALLED}, if it can return non-null
-	 * boolean results on some null inputs, it may be necessary to code
-	 * a negator or commutator by hand if the synthetic one would not have
-	 * the intended semantics.
 	 */
 	String[] commutator() default {};
 

pljava-api/src/main/java/org/postgresql/pljava/annotation/processing/DDRProcessor.java

@@ -173,7 +173,7 @@ public SourceVersion getSupportedSourceVersion()
 		 * Update latest_tested to be the latest Java release on which this
 		 * annotation processor has been tested without problems.
 		 */
-		int latest_tested = 22;
+		int latest_tested = 23;
 		int ordinal_9 = SourceVersion.RELEASE_9.ordinal();
 		int ordinal_latest = latest_tested - 9 + ordinal_9;
 

pljava-examples/pom.xml

@@ -58,6 +58,11 @@
 						<arg>--processor-module-path</arg>
 						<arg>${basedir}/../pljava-api/target/pljava-api-${project.version}.jar</arg>
 					</compilerArgs>
+					<annotationProcessors>
+						<annotationProcessor>
+							org.postgresql.pljava.annotation.processing.DDRProcessor
+						</annotationProcessor>
+					</annotationProcessors>
 				</configuration>
 			</plugin>
 			<plugin>

pljava-packaging/build.xml

@@ -255,6 +255,10 @@ jos.close();
 			     simple update is possible, just repeat the next entry, with
 				 the from-version changed.
 			  -->
+			<utf8 dir="target/classes" includes="pljava--.sql"
+				fullpath=
+			"pljava/sharedir/pljava/pljava--1.6.8--${project.version}.sql"
+			/>
 			<utf8 dir="target/classes" includes="pljava--.sql"
 				fullpath=
 			"pljava/sharedir/pljava/pljava--1.6.7--${project.version}.sql"

pljava-packaging/pom.xml

@@ -172,6 +172,9 @@ function execute()
 						<goals>
 							<goal>compile</goal>
 						</goals>
+						<configuration>
+							<proc>none</proc>
+						</configuration>
 					</execution>
 				</executions>
 			</plugin>

pljava-pgxs/pom.xml

@@ -56,6 +56,14 @@
 
 	<build>
 		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
+				<configuration>
+					<proc>none</proc>
+				</configuration>
+			</plugin>
+
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-plugin-plugin</artifactId>
@@ -170,6 +178,8 @@ function executeReport(report, locale)
 			 */
 			"-locale",      locale.toString(),
 			"-quiet",
+			"--show-members", "package",
+			"--show-types",   "package",
 			/*
 			 * Options that are passed to the doclet.
 			 */

pljava-pgxs/src/main/java/org/postgresql/pljava/pgxs/AbstractPGXS.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020-2021 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2020-2024 Tada AB and other contributors, as listed below.
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the The BSD 3-Clause License
@@ -21,33 +21,59 @@
 import java.util.stream.Collectors;
 
 /**
- * Class to act as a blueprint for platform specific build configurations in
- * pljava-so/pom.xml
+ * Class to act as a blueprint for platform-specific build configurations in a
+ * {@code pom.xml}.
+ *<p>
+ * A {@code scripted-goal} configuration in the POM should contain a script
+ * that somehow selects and supplies a concrete implementation of this abstract
+ * class.
+ *<p>
+ * In {@code pljava-so/pom.xml}, a block of {@code application/javascript} is
+ * supplied that contains a {@code configuration} array of JS objects, each of
+ * which has a {@code name} entry, a {@code probe} function returning true on
+ * some supported platform, and the necessary functions to serve as an
+ * implementation of this class. The script selects one whose probe succeeds
+ * and, using JSR 223 magic, makes an instance of this class from it.
+ *<p>
+ * The script can make use of convenience methods implemented here, and also
+ * a number of items (such as a {@code runCommand} function) presupplied in the
+ * script engine's binding scope by
+ * {@link PGXSUtils#getScriptEngine PGXSUtils.getScriptEngine} and by
+ * {@link ScriptingMojo#execute ScriptingMojo.execute}).
  */
 public abstract class AbstractPGXS
 {
-
 	/**
-	 * Add instructions for compiling the pljava-so C files on your platform
-	 * by implementing this method in your configuration block.
+	 * Performs platform-specific compilation of a set of {@code .c} files with
+	 * the specified compiler, target path, includes, defines, and flags.
+	 *<p>
+	 * An implementation should make any needed adjustments to the includes,
+	 * defines, and flags, format everything appropriately for the compiler
+	 * in question, execute it, and return an exit status (zero on success).
 	 */
-	public abstract int compile(String compiler, List<String> files, Path targetPath,
-								 List<String> includes, Map<String, String> defines,
-								 List<String> flags);
+	public abstract int compile(
+		String compiler, List<String> files, Path targetPath,
+		List<String> includes, Map<String, String> defines, List<String> flags);
 
 	/**
-	 * Add instructions for linking and producing the pljava-so shared library
-	 * artifact on your platform by implementing this method in your
-	 * configuration block.
+	 * Performs platform-specific linking of a set of object files with
+	 * the specified linker and flags, to produce the shared object at the
+	 * specified target path.
+	 *<p>
+	 * An implementation should make any needed adjustments to the flags, format
+	 * everything appropriately for the linker in question, execute it, and
+	 * return an exit status (zero on success).
 	 */
-	public abstract int link(String linker, List<String> flags, List<String> files, Path targetPath);
+	public abstract int link(
+		String linker, List<String> flags, List<String> files, Path targetPath);
 
 	/**
 	 * Returns a list with all items prefixed with correct include flag symbol.
 	 *
 	 * This is the default implementation for formatting the list of includes,
-	 * and prefixes the includes with -I. For compilers like MSVC that require
-	 * different symbols, override this method in your configuration block.
+	 * and prefixes the includes with {@code -I}. For compilers like MSVC that
+	 * require different formatting, the script should supply an overriding
+	 * implementation of this method.
 	 */
 	public List<String> formatIncludes(List<String> includesList)
 	{
@@ -56,12 +82,13 @@ public List<String> formatIncludes(List<String> includesList)
 	}
 
 	/**
-	 * Returns a list with all defines prefixed correctly.
+	 * Returns a list with all defines represented correctly.
 	 *
-	 * This is the default implementation for formatting the list of defines.
-	 * Each item is prefixed with -D. If the define is associated with a value,
-	 * adds equal symbol also followed by the value. If your linker expects a
-	 * different format, override the method in your configuration block.
+	 * This is the default implementation for formatting the map of defines.
+	 * Each item is prefixed with {@code -D}. If the name is mapped to a
+	 * non-null value, an {@code =} is appended, followed by the value. For
+	 * compilers like MSVC that require different formatting, the script should
+	 * supply an overriding implementation of this method.
 	 */
 	public List<String> formatDefines(Map<String, String> definesMap)
 	{
@@ -76,11 +103,11 @@ public List<String> formatDefines(Map<String, String> definesMap)
 	}
 
 	/**
-	 * Returns the input pg_config property as a list of individual flags split
-	 * at whitespace, except when quoted, and the quotes removed.
+	 * Returns the requested {@code pg_config} property as a list of individual
+	 * flags split at whitespace, except when quoted, and the quotes removed.
 	 *<p>
 	 * The assumed quoting convention is single straight quotes around regions
-	 * to be protected, which do not have to be the entire argument. This method
+	 * to be protected, which do not have to be an entire argument. This method
 	 * doesn't handle a value that <em>contains</em> a single quote as content;
 	 * the intended convention for that case doesn't seem to be documented, and
 	 * PostgreSQL's own build breaks in such a case, so there is little need,