diff --git a/src/site/markdown/build/build.md b/src/site/markdown/build/build.md index d48103354..9c0dee7ac 100644 --- a/src/site/markdown/build/build.md +++ b/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 +``` diff --git a/src/site/markdown/build/buildmsvc.md b/src/site/markdown/build/buildmsvc.md index d9af41837..715a05426 100644 --- a/src/site/markdown/build/buildmsvc.md +++ b/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]. diff --git a/src/site/markdown/build/package.md b/src/site/markdown/build/package.md index e61c80d95..346791829 100644 --- a/src/site/markdown/build/package.md +++ b/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 diff --git a/src/site/markdown/examples/saxon.md b/src/site/markdown/examples/saxon.md index 213ef9195..de4f72495 100644 --- a/src/site/markdown/examples/saxon.md +++ b/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 diff --git a/src/site/markdown/install/install.md.vm b/src/site/markdown/install/install.md.vm index b34979fd2..ca56fa833 100644 --- a/src/site/markdown/install/install.md.vm +++ b/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 diff --git a/src/site/markdown/install/locate.md.vm b/src/site/markdown/install/locate.md.vm index 1564bafc0..58512c014 100644 --- a/src/site/markdown/install/locate.md.vm +++ b/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` diff --git a/src/site/markdown/install/prepg92.md b/src/site/markdown/install/prepg92.md deleted file mode 100644 index b1fb8fbff..000000000 --- a/src/site/markdown/install/prepg92.md +++ /dev/null @@ -1,63 +0,0 @@ -# Installation on PostgreSQL releases earlier than 9.2 - -In PostgreSQL releases 9.2 and later, PL/Java can be installed entirely -without disturbing the `postgresql.conf` file or reloading/restarting the -server: the configuration variables can be set interactively in a session -until PL/Java loads sucessfully, then saved with a simple -`ALTER DATABASE` _dbname_ `SET` _var_ `FROM CURRENT` for each setting -that had to be changed. - -Releases earlier than 9.2 are slightly less convenient. It is still possible -to work out the right settings in an interactive session, but once found, -the settings must be added to `postgresql.conf` to be persistent, and the -postmaster signalled (with `pg_ctl reload`) to pick up the new settings. - -Releases before 9.2 also require setting `custom_variable_classes` in -`postgresql.conf` to include the prefix `pljava`, and that assignment must -be earlier in the file than any settings of `pljava.*` variables. - -## Trying settings interactively - -It is still possible to do an exploratory session to find the variable settings -that work before touching `postgresql.conf` at all, but -the details are slightly different. - -In later PostgreSQL versions, you would typically use some `SET` commands -followed by a `LOAD` (followed, perhaps, by more `SET` commands unless you -always get things right on the first try). - -Before release 9.2, however, the order has to be `LOAD` first, which typically -will lead to an incompletely-started warning because the configuration settings -have not been made yet. _Then_, because the module has been loaded, -`pljava.*` variables will be recognized and can be set and changed until -PL/Java successfully loads, just as in the newer versions of PostgreSQL. - -Once working settings are found, edit `postgresql.conf`, make sure that -`custom_variable_classes` includes `pljava`, copy in the variable settings -that worked, and use `pg_ctl reload` to make the new settings effective. - -## But what if I want the load to fail and it doesn't? - -The procedure above relies on the way loading stops when the settings are not -right, giving you a chance to adjust them interactively. That turns out to be -a problem if there are previously-saved settings, or the original defaults, -that happen to *work* even if they are not the settings you want. In that case, -the `LOAD` command starts PL/Java right up, leaving you no chance in the -interactive session to change anything. - -To escape that behavior, there is one more very simple configuration variable, -`pljava.enable`. If it is `off`, `LOAD`ing PL/Java will always stop early and -allow you to set other variables before setting `pljava.enable` to `on`. - -To answer the hen-and-egg question of how to set `pljava.enable` to `off` -before loading the module, it _defaults_ to `off` on PostgreSQL releases -earlier than 9.2, so you will always have the chance to test your settings -interactively (and you will always have to set it explicitly `on` when -you are ready). - -If it is already `on` because of an earlier configuration saved in -`postgresql.conf`, it will be recognized in your interactive session and you -can set it `off` as needed. - -On later PostgreSQL releases with no such complications, it defaults to `on` -and can be ignored. diff --git a/src/site/markdown/use/parallel.md b/src/site/markdown/use/parallel.md index 861a621b4..11524d899 100644 --- a/src/site/markdown/use/parallel.md +++ b/src/site/markdown/use/parallel.md @@ -1,9 +1,7 @@ # PL/Java in parallel query or background worker With some restrictions, PL/Java can be used in [parallel queries][parq], from -PostgreSQL 9.6, and in some [background worker processes][bgworker] (as -introduced in PostgreSQL 9.3, though 9.5 or later is needed for support -in PL/Java). +PostgreSQL 9.6, and in some [background worker processes][bgworker]. [bgworker]: https://www.postgresql.org/docs/current/static/bgworker.html [parq]: https://www.postgresql.org/docs/current/static/parallel-query.html diff --git a/src/site/markdown/use/use.md b/src/site/markdown/use/use.md index 0f486d3b0..973717516 100644 --- a/src/site/markdown/use/use.md +++ b/src/site/markdown/use/use.md @@ -98,8 +98,8 @@ significant advantages to using the ### Parallel query -PostgreSQL 9.3 introduced [background worker processes][bgworker] -(though at least PostgreSQL 9.5 is needed for support in PL/Java), +PL/Java understands [background worker processes][bgworker] +in PostgreSQL 9.5 and later, and PostgreSQL 9.6 introduced [parallel query][parq]. For details on PL/Java in a background worker or parallel query, see diff --git a/src/site/markdown/use/variables.md b/src/site/markdown/use/variables.md index cb465c1fa..a3cf32841 100644 --- a/src/site/markdown/use/variables.md +++ b/src/site/markdown/use/variables.md @@ -40,8 +40,7 @@ These PostgreSQL configuration variables can influence PL/Java's operation: `pljava.enable` : Setting this variable `off` prevents PL/Java startup from completing, until - the variable is later set `on`. It can be useful when - [installing PL/Java on PostgreSQL versions before 9.2][pre92]. + the variable is later set `on`. It can be useful in some debugging settings. `pljava.implementors` : A list of "implementor names" that PL/Java will recognize when processing