Skip to content

Commit

Permalink
Let docs reflect upstream rename of PostgresNode
Browse files Browse the repository at this point in the history
The Perl module supplied with PostgreSQL and formerly known as
PostgresNode is renamed PostgreSQL::Test::Cluster in PG 15.

This patch keeps the original naming of the Java Node.class
and simply fixes the documentation to reflect the changed name
of the upstream Perl module (and explain the historical source
of the Java name).
  • Loading branch information
jcflack committed Apr 1, 2024
1 parent edc958b commit c3dbb04
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 16 deletions.
20 changes: 11 additions & 9 deletions pljava-packaging/src/main/java/Node.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2015-2023 Tada AB and other contributors, as listed below.
* Copyright (c) 2015-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
Expand Down Expand Up @@ -127,16 +127,18 @@
* to the installer jar anyway, it will also contain some methods intended to be
* 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 one of
* the PostgreSQL JDBC drivers).
* PostgreSQL's {@code PostgreSQL::Test::Cluster} Perl module (formerly named
* {@code PostgresNode}, from which the name of this class was taken). The
* methods can be invoked 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} ({@code StandardProtocolFamily.UNIX}
* Unlike the many capabilities of {@code PostgreSQL::Test::Cluster}, this only
* deals in 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>
Expand Down Expand Up @@ -2623,9 +2625,9 @@ private static Object invoke(InvocationHandler h, int stateIdx, Object o)
* 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
* down, and waits for the file to go away; that could be implemented here,
* but not today.
* The {@code PostgreSQL:Test:Cluster} version of this is also used when
* shutting down, and waits for the file to go away; that could be
* implemented here, but not today.
*/
private void wait_for_pid_file(Process p, ProcessHandle.Info info)
throws Exception
Expand Down
21 changes: 14 additions & 7 deletions src/site/markdown/develop/node.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,18 @@ project's repository, as a way to keep as much as possible of the testing code
common across platforms.

The overall flavor, and even some of the method names, follow the `PostgresNode`
Perl module that has been part of PostgreSQL's "PGXS" extension-building tools
since 2015, so a quick review of that follows.
Perl module that became part of PostgreSQL's "PGXS" extension-building tools
in 2015, so a quick review of that follows.

## Similarities to PostgreSQL's `PostgresNode` Perl module
For PostgreSQL 15, the module distributed with PostgreSQL was renamed from
`PostgresNode` to `PostgreSQL::Test::Cluster`, with no essential change in
functionality (though `get_new_node` did become, simply, `new`). To avoid
needless churn, this Java class still has the historical name and methods.

When used from a testing script written in Perl, the methods of `PostgresNode`
## Similarities to the upstream `PostgreSQL::Test::Cluster` Perl module

When used from a testing script written in Perl, the methods of
`PostgreSQL::Test::Cluster`
make it easy to spin up and tear down one or more PostgreSQL instances, running
in temporary directories, listening on temporary ports, non-interfering with
each other or with production instances using the standard locations and ports,
Expand All @@ -41,7 +47,7 @@ $n1->stop(); # stop the server
$n1->clean_node(); # recursively delete the temporary location
```

`PostgresNode.pm` illustrates the immense utility of making just a few
`PostgreSQL::Test::Cluster` illustrates the immense utility of making just a few
well-chosen methods available, when there is already an expressive scripting
language at hand (Perl) for putting those methods to use.

Expand All @@ -65,9 +71,10 @@ 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
more on that later. But once started, it presents a familiar
`PostgreSQL::Test::Cluster`-like
environment. As the example shows, `jshell` is lenient about statement-ending
semicolons. (It is still advisable to use them, though; that leniency has fiddly
semicolons. (Using them is still advisable, though; that leniency has fiddly
exceptions, such as not applying to pasted text.)

## `Node.class` in detail
Expand Down

0 comments on commit c3dbb04

Please sign in to comment.