Re: Video Tutorial - How to Build and Install PL/Java

Hi Chap,

I created a video tutorial:

How to Build and Install PL/Java with MinGW-w64:
https://youtu.be/hVYpzJ_phwY

Best,

Igal

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

On 03/06/16 02:23, Chapman Flack wrote:
> 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.

... another thing that might be nice to show would be a

\c

in psql to quickly put you in a new session, and then show that
PL/Java works in the new session because the correct setting was
saved. Which could also show how to see the PL/Java and Java versions
being used, in case someone needs to know ... just \c to start a new
session, then

SET client_min_messages TO debug1;

before running any PL/Java function, and then whenever you first
call a PL/Java function (even just sqlj.get_classpath('public')
for example), you'll see the debug message with all the versions.

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

On 3/5/2016 11:23 PM, Chapman Flack wrote:
> 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.

I personally would prefer to see document/blog/wiki format instructions
over a video demonstration of a software procedure hands down.
Bonus, its easier to make minor changes such as Chapman suggests...
Updating a video will require reshooting scenes, and reediting the
video, or if it was done in one take, reshooting the whole thing.

--
john r pierce, recycling bits in santa cruz

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

On 03/06/16 02:36, John R Pierce wrote:

> I personally would prefer to see document/blog/wiki format instructions over
> a video demonstration of a software procedure hands down. Bonus, its
> easier to make minor changes such as Chapman suggests... Updating a video
> will require reshooting scenes, and reediting the video, or if it was done
> in one take, reshooting the whole thing.

Well, so the document/wiki format instructions are already there, and
I think Igal has added something very valuable for people who do prefer
to see a process shown. (Especially if it can be edited to show common
experiences like what happens when libjvm_location isn't right, or what
happens on your *next* session if you didn't save the right GUC values,
or search path, or class path ... because those seem to be the causes
of a lot of "what's going wrong?" inquiries, and in a written doc it
is hard to emphasize them enough for the readers who are skimming,
without seeming to overdo it for the ones who are concentrating.)

I am assuming, of course, that Igal is using nice editing software, and
still has the input bits and not just the final rendering....

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

On 3/5/2016 11:23 PM, Chapman Flack wrote:
> 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
OK, I can do that
> The next thing, later on, you gave the CREATE EXTENSION pljava;
> command, and it worked ... *then* you showed setting libjvm_location.
did you see my pull request at
https://github.com/tada/pljava/pull/97/files ?
> 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.)
while playing with this before I tried both ALTER DATABASE and ALTER SYSTEM
to set that value. unfortunately I was unable to UN-SET that value? I
tried ALTER - RESET
but that didn't seem to work
> 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.
so you want me to show the "pitfalls" and troubleshooting? I want to
keep the video
rather short. replacing git with download can save some time so it
might be offset,
but I really prefer to keep the whole thing under 15 minutes
> 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.
OK, much of this is very new to me. I have very little experience with
PostgreSQL, psql, PL/java, etc.
> 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. :)
sure, I can show the local files instead of the github repo in the browser
> 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.
thank you. I'll try to re-do it with these points in mind.

can you please explain:

1) how do I unset the value

2) where are the docs for the `sqlj` namespace (or is it a schema?), for
example, what do the additional args do exactly?

SELECT
sqlj.install_jar('file:/C:/Apps/pgsql951/share/pljava/pljava-examples-1.5.0-BETA2.jar',
'examples', true);

and this one? creates a schema named javatest and maps it to the
'examples' namespace from the previous command?

SELECT sqlj.set_classpath('javatest', 'examples');

thanks,

Igal

On 3/6/2016 12:27 AM, Chapman Flack wrote:
> Well, so the document/wiki format instructions are already there, and
> I think Igal has added something very valuable for people who do prefer
> to see a process shown. (Especially if it can be edited to show common
> experiences like what happens when libjvm_location isn't right, or what
> happens on your *next* session if you didn't save the right GUC values,
> or search path, or class path ... because those seem to be the causes
> of a lot of "what's going wrong?" inquiries, and in a written doc it
> is hard to emphasize them enough for the readers who are skimming,
> without seeming to overdo it for the ones who are concentrating.)
I agree with Chap. the written docs are very clear, but I think that
most users are too lazy to read the whole thing, especially if it seems
a bit overwhelming. a video can show that it really isn't as
complicated as it might first look.

my concern with showing pitfalls and troubleshooting as per the other
email in this thread is that it will still show the process to be
overwhelming.
> I am assuming, of course, that Igal is using nice editing software, and
> still has the input bits and not just the final rendering....
unfortunately, I do not. I am using Windows Movie Maker, which is the
default program that comes with Windows. I tried a couple of the
commercial products for Windows but they have been even worse, with many
crashes, etc.

still, I can re-do the video given the right information.

Igal

On 3/6/2016 11:09 AM, Igal @ Lucee.org wrote:
>
> 1) how do I unset the value
OK, I found the answer to my first question at
https://github.com/tada/pljava/wiki/Complete-uninstall :

# ALTER DATABASE postgres RESET pljava.libjvm_location;
# ALTER SYSTEM RESET pljava.libjvm_location;
# SELECT pg_reload_conf();
# \c

Igal

On 03/06/16 14:09, Igal @ Lucee.org wrote:

> did you see my pull request at https://github.com/tada/pljava/pull/97/files ?

I did. I mean to pull it into both master and REL1_5_STABLE (so it will be
in 1.5) and I'll have to do that the old-fashioned git way, I can't just
use the big green button on github. :)

>> (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.)
> while playing with this before I tried both ALTER DATABASE and ALTER SYSTEM
> to set that value. unfortunately I was unable to UN-SET that value? I
> tried ALTER - RESET
> but that didn't seem to work

Hmm, that's puzzling. You could start with

select name, source from pg_settings
where name like 'pljava.%' order by source;

to see exactly where it thinks it got the value. If the source is
'database' then ALTER DATABASE ... RESET ... ought to work, if it is
coming from ALTER SYSTEM I guess it would say 'configuration file' and
ALTER SYSTEM RESET ... ought to work.

After doing an ALTER DATABASE ... RESET ... you would need a \c in psql
to start a new session; after an ALTER SYSTEM RESET ... you would need
a pg_ctl reload (and start a new session).

> so you want me to show the "pitfalls" and troubleshooting? I want to keep
> the video
> rather short. replacing git with download can save some time so it might be
> offset,
> but I really prefer to keep the whole thing under 15 minutes

I don't know how much time it would add, but if you showed CREATE EXTENSION
before the libjvm_location was set, you could point out that the error
message pretty much says "hey, you should set pljava.libjvm_location" and
then you could show how to do that ... likewise, if you try calling an
example function before setting the classpath, you can say "oh, here's what
this ClassNotFoundException is telling us".

I think people remember things better when they see why you are telling
them. What you say about pljava.libjvm_location already takes nearly a
full minute (6:22 to 7:18) but the viewer doesn't actually see why you
are spending the time on it, because nothing failed. You could probably
do a CREATE EXTENSION that failed, showing the error message implicating
libjvm_location, find the jvm, set the variable, and show that it works,
in roughly the same amount of time, and ... in my experience anyway ...
it might stick better for the viewer that way.

Now, there are two different ways you could show how to recover. One
would be to just say "oh, I needed to set the JVM location, let's do
ALTER DATABASE postgres SET pljava.libjvm_location TO '...', then start
a new session with \c so it takes effect, THEN try CREATE EXTENSION again"
and that would be a quick, tidy way to show it.

The other way would be to demonstrate staying in the same session, showing
how setting the variable correctly allows the installation to immediately
complete, and the message reminds you to save the setting, do a \c and then
the CREATE EXTENSION pljava FROM unpackaged; to finish the job. That's
a little messier, so you may prefer to show the other way; I'm not sure
which would really take longer on screen.

> sure, I can show the local files instead of the github repo in the browser

I wasn't necessarily suggesting to show the local files instead of the
github browser ... a lot of the time I prefer to look at the github
browser, it just colorizes them nicely and so on.

But what I would suggest is this: instead of just going to
https://github.com/tada/pljava and browsing around the files there
(because that shows whatever happens to be in 'master' at this exact
moment), show how to start at https://github.com/tada/pljava/releases
and then click the tag link for the release you have installed
(say V1_5_0b2) and *then* browse around the files there.

> 1) how do I unset the value

tried to cover that above ...

> 2) where are the docs for the `sqlj` namespace (or is it a schema?), for

Just for fun, PostgreSQL uses the terms 'namespace' and 'schema'
interchangeably.

> example, what do the additional args do exactly?

Couple of places for that info: the wiki:
https://github.com/tada/pljava/wiki/SQL-functions
and the javadocs:
http://tada.github.io/pljava/pljava/apidocs/index.html?org/postgresql/pljava/management/Commands.html

They should pretty much agree. :)

> SELECT
> sqlj.install_jar('file:/C:/Apps/pgsql951/share/pljava/pljava-examples-1.5.0-BETA2.jar',
> 'examples', true);

The first argument is of course what this jar file is called outside
of PostgreSQL. The second argument ('examples') is what it will be called
inside PostgreSQL once it is installed.

The boolean argument is whether PL/Java should execute the commands in
the jar's DDR files after installing the jar. Passing true means it does,
so all the necessary SQL commands get executed.

> and this one? creates a schema named javatest and maps it to the 'examples'
> namespace from the previous command?
>
> SELECT sqlj.set_classpath('javatest', 'examples');

Well, from the previous command, 'examples' is what you named the jar file
you just installed. 'javatest' is the name of a schema that all the example
functions got declared in (all of that was done by the DDR commands when
the jar was installed, including creating the schema 'javatest' itself;
you can see that as the first install command in examples.ddr.

So the only thing left to do is tell PL/Java "when you are looking up
functions that are declared in the schema 'javatest', look for them in
the jar named 'examples'." That's what this command does.

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

On 03/06/16 14:14, Igal @ Lucee.org wrote:

> unfortunately, I do not. I am using Windows Movie Maker, which is the
> default program that comes with Windows. I tried a couple of the commercial
> products for Windows but they have been even worse, with many crashes, etc.

Ugh. My own dabbling in videos has been done with OpenShot, which I found
also to crash often, but I just made saving-even-more-often part of my work
method and it worked out.

The very first project I did with it, when I was done I rendered it down
to a single file and got rid of the input components to save space, and
I have regretted that ever since, because there are a couple of small
things I want to go back and change, and now it is not easy.

I keep the source pieces around for later projects ... disk space is
cheaper than regret. :)

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