Re: [Pljava-dev] Video Tutorial - How to Build and Install PL/Java

On 03/06/16 00:53, Igal @ Lucee.org wrote:
> I created a video tutorial:
>
> How to Build and Install PL/Java with MinGW-w64:
> https://youtu.be/hVYpzJ_phwY

Hi Igal,

I like the video a lot, but I noticed a couple of things
that I hope might not be too hard to change:

The first one is rather serious. After cloning the git repository,
you showed the checkout of a *branch*, REL1_5_STABLE. The trouble
is, the branch is not a specific *release*. That is, it branched
off from 'master' just before the first 1.5.0 beta, then a few
commits, then a point on that branch tagged V1_5_0b1, then several
more commits, then a tag V1_5_0b2, and *just by luck at this moment*
there are not any commits after b2 that I have pushed yet, on the
way to b3 or a final release. But in general, if you check out the
*branch*, you are getting some version of things between the last
released 1.5.x and the next upcoming 1.5.y, and it will install with
the same version string as the last released version, but *it won't
be that version*! And that will be certain to cause confusion, with
different people running PL/Java versions named "1.5.0-BETA2" that
are actually different.

Perhaps to be safe I should institute a practice of always committing
a version-number change immediately after tagging a release, but
so far I have not.

So, it would be much safer if you showed cloning the repository
and then checking out the *actual release tag*:

git checkout V1_5_0b2

or without using git, by downloading the .zip or .tar.gz from

https://github.com/tada/pljava/releases

You could show how that page shows each available release (or
pre-release) with the correct tag name. The tag name and commit
ID appear *above* the release name (for example, look at the
large-type "Release 1.5.0-BETA2" and above that, you see the tag
name V1_5_0b2 (with a little tag icon) and also the commit ID d5b69ef.
The zip and tar.gz download links require scrolling down past the
description.

The next thing, later on, you gave the CREATE EXTENSION pljava;
command, and it worked ... *then* you showed setting libjvm_location.
It must have been set correctly already, or the CREATE EXTENSION
would have failed. Probably in your earlier experimenting you saved
the correct value with ALTER DATABASE, or by editing the conf file?
(I think the saved value is the same as the one you gave in the SET
command, otherwise that command would have failed ... it doesn't
let you change libjvm_location in a session where the jvm has already
loaded, because it would be too late to make any difference to that
session.)

So if you wanted to make that part of the video even more helpful,
you could also show what CREATE EXTENSION does if you do *not* have
the value correctly set first, and how you can tell what happened and
recover by setting the variable. That will be very helpful to people
who do try CREATE EXTENSION without the right variable setting, and
wonder what the error messages mean. :)

Then you could also show how to save the correct setting for later
sessions, using a command like ALTER DATABASE postgres SET
pljava.libjvm_location FROM CURRENT.

It is nice to show the examples.ddr file, but it might also be good
to mention those are not *all* the function definitions, in fact that
file is only still there because not all examples are converted to
use Java annotations yet, and it contains only the ones that haven't.
It will be getting smaller and smaller....

... so you might want to also show how to list the functions with

\df javatest.*
or for more detail (including the description, where present)
\df+ javatest.*

You could also show how to see the full SQL syntax for one function's
declaration, like

\sf javatest.java_addone

Wildcards don't work with \sf, just one function at a time.

Browsing on github for the examples.ddr file, you could also show
browsing the directory of example sources, or the subdirectory
annotation, containing the examples that already have been converted
so you do not see them in examples.ddr.

Also, when browsing files on github, you could show how to start on
the releases page and click the tag for the release you have installed,
and then browse files, so that you know you are seeing the same versions
you are actually running. :)

I know those are a lot of comments, so if it didn't quite come through,
I really like the video, thanks for making it! The suggestions are for
making it even better.

Cheers,
-Chap
_______________________________________________
Pljava-dev mailing list
Pljava-dev(at)lists(dot)pgfoundry(dot)org
http://lists.pgfoundry.org/mailman/listinfo/pljava-dev