Merge doc/REL1_6_STABLE/issue385 and doc/REL1_6_STABLE/pg_ge_95 into REL1_6_STABLE

Author: jcflack

src/site/markdown/build/build.md

@@ -60,7 +60,13 @@ There is a "troubleshooting the build" section at the end of this page.
 
         mvn --version
 
-    succeeds.
+    succeeds. It reports not only the version of Maven, but the version of Java
+    that Maven has found and is using, which must be a Java version supported
+    for building PL/Java (see more on [version compatibility](versions.html)).
+    If Maven is not finding and using the intended Java version, the environment
+    variable `JAVA_HOME` can be set to point to the desired Java installation,
+    and `mvn --version` should then confirm that the Java being found is the
+    one intended.
 
 If you have more than one version installed of PostgreSQL, Java, or the
 compile/link tools, make sure the ones found on your search path are the
@@ -222,30 +228,6 @@ build issues that are commonly asked about.*
 
 [btwp]: https://github.com/tada/pljava/wiki/Build-tips
 
-#### Not all `[ERROR]`s are errors
-
-In the part of the build that compiles the native code, you may see lines of
-output starting with `[ERROR]`, but the build completes and shows success for
-all subprojects.
-
-Maven is capturing output from the C compiler and adding a tag at the front of
-each line. If the line from the C compiler contains the string `warning:` then
-Maven adds a `[WARNING]` tag at the front of the line; otherwise it adds
-`[ERROR]`. That is how Maven can turn a multiple-line warning, like
-
-```
-type/String.c: In function 'String_createJavaString':
-type/String.c:132:43: warning: conversion to 'jlong' from 'Size' may change
-                      the sign of the result [-Wsign-conversion]
-   bytebuf = JNI_newDirectByteBuffer(utf8, srcLen);
-                                           ^
-```
-
-(where only the second line contains `warning:`) into what looks like one
-`[WARNING]` and several `[ERROR]`s.
-
-If the compiler reports any actual errors, the build will fail.
-
 #### Capture the output of `mvn -X`
 
 The `-X` option will add a lot of information on the details of Maven's
@@ -259,3 +241,11 @@ On the first run, Maven will produce a lot of output while downloading all
 of the dependencies needed to complete the build. It is better, if the build
 fails, to simply run Maven again and capture the output of that run, which
 will not include all of the downloading activity.
+
+As an alternative, the flood of messages reflecting successful dependency
+downloads in a first run can be suppressed by adding this option on the `mvn`
+command line:
+
+```
+-Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=warn
+```

src/site/markdown/build/buildmsvc.md

@@ -21,9 +21,6 @@ PostgreSQL and PL/Java. Using a *newer* version of Visual Studio (including
 the Community 2015 version) will generally work, while older versions are more
 likely to be problematic.
 
-* PostgreSQL 9.1 to 9.3 were built using Visual Studio 2010.
-* PostgreSQL 9.4 was built using Visual Studio 2013.
-
 ## Software Prerequisites
 
 0. You will need an appropriate version of [Microsoft Visual Studio][msvc]. When
@@ -50,11 +47,6 @@ likely to be problematic.
     an `INCLUDEDIR-SERVER` line, and list the directory it refers to. There
     should be a bunch of `*.h` files there.
 
-0. OpenSSL headers: if using an EnterpriseDB PostgreSQL build older than 9.3,
-    these will be missing. They can be obtained from a 9.3 or later
-    EDB PostgreSQL build by copying the `include/openssl` directory and
-    its contents.
-
 0. You will need to install [Maven][mvn] and add it to your PATH so that
 
         mvn --version
@@ -219,26 +211,5 @@ dependency when [building your own projects that _use_ PL/Java][jproj].
 
 ### Troubleshooting the build
 
-If something fails, two tricks may be helpful. The C compilation may produce
-a lot of nuisance warnings, because the Maven plugin driving it enables many
-types of warning that would be impractical to fix. With many warnings it may
-be difficult to pick out messages that matter.
-
-If the link step of the build reports that the symbol `rint` is undefined you
-are probably using an older version of Visual Studio (2010) with a newer version
-of Postgresql (9.4). This symbol is defined in Visual Studio 2013 and later and
-the Postgresql 9.4 headers lack the appropriate conditional options for the
-older compilers. You will need to use a newer version of Visual Studio.
-
-On a machine with many cores, messages from several compilation threads may be
-intermingled in the output so that related messages are hard to identify.
-The option `-Dnar.cores=1` will force the messages into a sequential order
-(and has little effect on the speed of a PL/Java build).
-
-The `-X` option will add a lot of information on the details of Maven's
-build activities.
-
-    mvn  -X  -Dnar.cores=1  clean  install
-
-There is a more comprehensive "troubleshooting the build" section
+There is an extensive "troubleshooting the build" section
 on the [main build page][mbp].

src/site/markdown/build/package.md

@@ -25,13 +25,6 @@ When building a package, you are
 encouraged to set the default `pljava.libjvm_location` to the library of a
 JRE version that is expected to be present on your platform.
 
-**Note:** when building on Windows, the `-Dpljava.libjvmdefault` option is
-likely to produce a failed build or the wrong stored value for the library
-path. A fix for this option on Windows is unlikely (see [issue 190][bug190]);
-if preparing a package for Windows, it will be simplest to use a patch that
-changes the definition of `PLJAVA_LIBJVMDEFAULT` in
-`pljava-so/src/main/c/Backend.c`.
-
 [locatejvm]: ../install/locatejvm.html
 [bug190]: https://github.com/tada/pljava/issues/190
 
@@ -78,11 +71,13 @@ shown in that link to disable the repacking of jars.
 The one part of PL/Java that could, if desired, be handled in the manner of
 Java libraries is `pljava-api`. This single jar file is needed on the classpath
 when compiling Java code that will be loaded into PL/Java in the database.
-It is _not_ needed at the time that code will _run_. That means it could be
-appropriate to treat `pljava-api` as a separate `-devel` package, if your
-packaging guidelines encourage such a distinction. In that case, you would
-exclude the `pljava-api` jar file from the main package, and produce a `-devel`
-package that provides it.
+That means it could be
+appropriate to provide `pljava-api` in a separate `-devel` package, if your
+packaging guidelines encourage such a distinction, where it would be installed
+in the expected place for a conventional Java library. (The API jar must still
+be included in the main package also, installed in the location where PostgreSQL
+expects it. There may be no need, therefore, for the main package to depend on
+the `-devel` package.)
 
 A `-devel` package providing `pljava-api` might appropriately follow
 java library packaging guidelines to ensure it appears on a developer's
@@ -108,7 +103,7 @@ is the useful one to have in an installation target host's repository.)
 
 The PL/Java build does not automatically build javadocs. Those that go with
 `pljava-api` can be easily generated by running
-`mvn --projects pljava-api javadoc:javadoc` to build them, then collecting
+`mvn --projects pljava-api site` to build them, then collecting
 the `apidocs` subtree from `target/site`. They can be included in the same
 package as `pljava-api` or in a separate javadoc package, as your guidelines
 may require.
@@ -126,7 +121,7 @@ been built first and installed into the build host's local Maven repository.
 Note that many of the examples do double duty as tests, as described in
 _confirming the build_ below.
 
-When building for (and with) Java 8 or later and PostgreSQL 8.4 or later,
+Unless they are not wanted,
 the XML examples based on the Saxon library should also be built,
 by adding `-Psaxon-examples` to the `mvn` command line.
 
@@ -137,7 +132,7 @@ the package.
 
 `-Dpljava.libjvmdefault=`_path/to/jvm-shared-object_
 : As suggested earlier, please use this option to build a useful default
-into PL/Java for the `pljava.libjvm_location` PostgreSQL variable, users
+into PL/Java for the `pljava.libjvm_location` PostgreSQL variable, so users
 of your package will not need to set that variable before
 `CREATE EXTENSION pljava` works.
 
@@ -170,6 +165,14 @@ Some tests involving Unicode are skipped if the `server_encoding` is not
 `utf-8`, so it is best to run them in a server instance created with that
 encoding.
 
+To simplify automated testing, the jar file that is the end product of a full
+PL/Java source build contains a class that can serve as a PostgreSQL test
+harness from Java's `jshell` script engine. It is documented [here][node],
+and the continuous-integration scripts in PL/Java's own source-control
+repository can be consulted as examples of its use.
+
+[node]: ../develop/node.html
+
 ## Packaging the built items
 
 The end product of a full PL/Java source build is a jar file that functions as
@@ -179,8 +182,11 @@ those needed to support `ALTER EXTENSION UPGRADE`.
 
 It also contains the `pljava-api` jar, needed for developing Java code to use
 in a database with PL/Java, and the `pljava-examples` jar. As discussed above,
-these may be omitted from a base package and supplied separately, if packaging
-guidelines require.
+the examples jar may be omitted from a base package and supplied separately,
+if packaging guidelines require, and the API jar may be included also in a
+`-devel` package that installs it in a standard Java-library location. (However,
+the API jar cannot be omitted from the base package; it is needed at runtime, in
+the `SHAREDIR/pljava` location where the extension expects it.)
 
 The self-extracting jar consults `pg_config` at the time of extraction to
 determine where the files should be installed.
@@ -216,9 +222,10 @@ will have on the target system.
 
 In addition to the files named in the self-extractor's output, additional
 files could be included in the package (if guidelines require the README
-or COPYRIGHT, for example). As discussed above, the `pljava-api` jar could
-be filtered from the list if it will be delivered in a separate `-devel`
-package, and the same could be done for `pljava-examples`.
+or COPYRIGHT, for example). As discussed above, the `pljava-examples` jar could
+be filtered from the list if it will be delivered in a separate
+package, and the `pljava-api` jar could be additionally delivered in a separate
+`-devel` package (but must not be excluded from the base package).
 
 [install]: ../install/install.html
 

src/site/markdown/examples/saxon.md

@@ -451,18 +451,6 @@ string (`\A\z` in Java syntax):
 That workaround would also cause the replacement to happen if the input string
 is completely empty to start with, which might not be what's wanted.
 
-#### Syntax in older PostgreSQL versions
-
-The desugared syntax shown above can be used in PostgreSQL versions as old
-as 9.5. In 9.4 and 9.3, the same syntax, but with `=>` replaced by `:=` for
-the named parameters, can be used. The functions remain usable in still
-earlier PostgreSQL versions, but with increasingly convoluted SQL syntax
-needed to call them; before 9.3, for example, there was no `LATERAL` in a
-`SELECT`, and a function could not refer to earlier `FROM` items. Before 9.0,
-named-parameter notation can't be used in function calls. Before 8.4, the
-functions would have to be declared without their `DEFAULT` clauses and the
-`IntervalStyle` settings, and would not work with PostgreSQL interval values.
-
 ### Minimizing startup time
 
 Saxon is a large library, and benefits greatly from precompilation into a

src/site/markdown/install/install.md.vm

@@ -39,10 +39,9 @@ see the jar file there.
 __Upgrade installations__
 below*.
 
-*Not running PostgreSQL 9.1 or higher? Use
+*Avoiding `CREATE EXTENSION` for some reason? Use
 `LOAD 'libpljava-so-${project.version}';` instead of the `CREATE EXTENSION`
-command. (It works in later versions too, if you prefer it to
-`CREATE EXTENSION`.) Using a Mac? Be sure to add `.bundle` at the end of the file name
+command. Using a Mac? Be sure to add `.bundle` at the end of the file name
 in the `LOAD` command. Windows? Remove `lib` from the front. Something else?
 Keep reading.*
 
@@ -187,7 +186,7 @@ Another approach is to save them to the server's configuration file.
 If you wish PL/Java to be available for all databases in a cluster, it may
 be more convenient to put the settings in the file than to issue
 `ALTER DATABASE` for several databases, but `pg_ctl reload` will be needed
-to make changed settings effective. Starting with PostgreSQL 9.4,
+to make changed settings effective.
 `ALTER SYSTEM` may be used as an alternative to editing the file.
 
 If you have several databases in the cluster and you favor the
@@ -197,9 +196,6 @@ sure that `CREATE EXTENSION` just works, in any database where PL/Java
 is wanted. Different per-database settings can still be made if one
 database needs them.
 
-For PostgreSQL releases [earlier than 9.2][pre92], the configuration file is
-the _only_ way to make your settings persistent.
-
 $h2 Upgrade installations
 
 PL/Java performs an upgrade installation if there is already an `sqlj` schema
@@ -215,10 +211,12 @@ $h2 Usage permission
 
 Installation of PL/Java creates two "languages", `java` and `javau`.
 Functions that specify `LANGUAGE javau` can be created only by superusers,
-and are subject to very few restrictions at runtime. Functions that specify
+and PL/Java's default policy grants them some filesystem access. Functions that
+specify
 `LANGUAGE java` can be created by any user or role that has been granted
-`USAGE` permission `ON LANGUAGE java`. They run under a security manager that
-denies access to the host filesystem.
+`USAGE` permission `ON LANGUAGE java`. The default policy grants them no extra
+permissions. The exact permissions granted in either case can be customized
+in [`pljava.policy`][policy].
 
 __Note: For implications when running on Java 17 or later,
 please see [JEP 411][jep411]__.
@@ -237,12 +235,10 @@ $h2 Special topics
 
 Be sure to read these additional sections if:
 
-* You are installing to [a PostgreSQL release earlier than 9.2][pre92]
 * You are installing on [a system using SELinux][selinux]
 * You are installing on [Mac OS X][osx]
 * You are installing on [Ubuntu][ubu] and the self-extracting jar won't work
 
-[pre92]: prepg92.html
 [selinux]: selinux.html
 [osx]: ../build/macosx.html
 [ubu]: ../build/ubuntu.html
@@ -254,9 +250,10 @@ $h3 Puzzling error message from `CREATE EXTENSION`
     ERROR:  relation "see doc: do CREATE EXTENSION PLJAVA in new session"
     already exists
 
-For PL/Java, `CREATE EXTENSION` (which works in PostgreSQL 9.1 and later) is a
-wrapper around installation via `LOAD` (which works in all versions PL/Java
-supports). A quirk of this arrangement is that PostgreSQL treats `LOAD` as a
+For PL/Java, `CREATE EXTENSION` is a wrapper around installation via `LOAD`
+(which was needed for PostgreSQL versions now of only historical interest,
+and remains supported for cases where `CREATE EXTENSION` is too inflexible).
+A quirk of this arrangement is that PostgreSQL treats `LOAD` as a
 no-op for the remainder of a session once the library has been loaded, so
 `CREATE EXTENSION pljava` works in a *fresh* session, but not in one where
 PL/Java's native code is already in place.
@@ -283,7 +280,7 @@ Because PL/Java, by design, runs entirely in the backend process created
 for each connection to PostgreSQL, to configure it does not require any
 cluster-wide actions such as stopping or restarting the server, or editing
 the configuration file; any necessary settings can be made in SQL over
-an ordinary connection (in PostgreSQL 9.2 and later, anyway).
+an ordinary connection.
 
 _Caution: if you are installing a new, little-tested PL/Java build, be aware
 that in the unexpected case of a crash, the `postmaster` will kick other
@@ -399,3 +396,4 @@ readable by the user running `postgres`, and set the `pljava.*` variables
 accordingly.
 
 [jep411]: https://github.com/tada/pljava/wiki/JEP-411
+[policy]: ../use/policy.html

src/site/markdown/install/locate.md.vm

@@ -31,11 +31,9 @@ work with a `.jar` file no matter what.
 
 Relative to the root of the build tree, the jar file is found at
 
-`pljava-packaging/target/pljava-${pgversion}-${naraol}.jar`
+`pljava-packaging/target/pljava-${pgversion}.jar`
 
-where `${pgversion}` resembles `pg9.4` and `${naraol}` is an
-*architecture-os-linker* triple, for example `amd64-Linux-gpp`
-or `amd64-Windows-msvc`. It contains these things:
+where `${pgversion}` resembles `pg16`. The jar contains these things:
 
 `pljava/pkglibdir/libpljava-\${project.version}.so` (or `.dll`, etc.)
 : The architecture-dependent, native library portion of the PL/Java
@@ -62,13 +60,24 @@ or `amd64-Windows-msvc`. It contains these things:
 : Various files scripting what `CREATE EXTENSION` or
     `ALTER EXTENSION ... UPDATE` really do.
 
+`pljava/sysconfdir/pljava.policy`
+: Policy file defining the Java permissions granted to the languages `java`
+    and `javaU`, to any custom language aliases, or to specific jars, as
+    described [here][policy].
+
 It could happen that future versions add more files in the jar before
 updating this page. Also, every jar file has a `MANIFEST.MF`, and this
 file also contains a `JarX.class` to make it self-extracting; these are
 not otherwise important to PL/Java. See the [installation page][inst]
 for how to control the self-extraction.
 
+Another file, `Node.class`, present in this jar is also unimportant for
+normal installation, but provides some facilities for automated testing,
+as described [here][node].
+
 [examples]: ../examples/examples.html
+[node]: ../develop/node.html
+[policy]: ../use/policy.html
 
 Extract the needed files from this archive and place them in appropriate
 locations, then complete the [installation][inst].
@@ -112,11 +121,8 @@ $h3 The architecture-dependent PL/Java native library
 This is built by the `pljava-so` subproject. Its filename extension can depend
 on the operating system: `.so` on many systems, `.dll` on Windows, `.bundle` on
 Mac OS X / Darwin. Relative to the source root where the build was performed, it
-is at the end of a long and redundant path that contains the project version
-(twice), an "architecture-OS-linker" string (twice), and a build type
-("plugin"), also twice.
+is found in the `pljava-so/pljava-pgxs` directory.
 
-An example, for version `${project.version}` and arch-os-linker of
-`amd64-Linux-gpp` is (very deep breath):
+An example for version `${project.version}` is:
 
-`pljava-so/target/nar/pljava-so-${project.version}-amd64-Linux-gpp-plugin/lib/amd64-Linux-gpp/plugin/libpljava-so-${project.version}.so`
+`pljava-so/pljava-pgxs/libpljava-so-${project.version}.so`