source: main/trunk/gli/README_WebGLI.txt@ 32919

--------------------------
README 
--------------------------

GLI Java Web Start application (replacement for GLI Applet) - Additional Steps

Many browsers have stopped supporting Java applets including Microsoft Edge, though Microsoft's Internet Explorer still supported it. For this reason, 3.09's GLI is now no longer provided as an applet, but has been converted into a Java Web Start application.

Instructions for using the GLI Java Web Start, which works over the JNLP protocol, are below.

1. Follow the instructions at http://wiki.greenstone.org/doku.php?id=en:release:3.09_release_notes#setting_up_a_remote_greenstone_3_server for setting up the Remote GS Server

2. Next, generate the SignedGatherer.jar:
a. Use a terminal to go into the Greenstone "gli" directory, then run
    keytool -genkey -alias privateKey -keystore appletstore -storepass greenstone
Enter the appropriate details for your organization. When it asks to enter the key password for <privateKey>, choose your own password or hit Enter to use "greenstone".
b. Next, run
    jarsigner -keystore appletstore -signedjar SignedGatherer.jar GLI.jar privateKey
When it prompts, enter the password you used in step 2a above.

3. Move the created SignedGatherer.jar file from the gli directory into GS3's web/applet subdirectory.

4. You need to associate JNLP files with Java Web Start (jre/bin/javaws).

    - On Windows, create the association in the usual way: when you first access the GLI Web Start application through Greenstone,
    a JNLP file called "GLIappWebStart.jnlp" will be offered for launching or download.
    If JavaWS is not already the default application to open JNLP files with, rightclick on the downloaded GLIappWebStart.jnlp file
    and choose Launch/Open with 
.
    Browse to your Greenstone3's packages/jre/bin/javaws.exe or any installed Java's jre/bin/javaws.exe to use Java's Web Start application as the launcher.
    
    - For Linux, create a file with .desktop extension (e.g. "javawebstart.desktop") containing the following, edit the path to javaws,
    and save this file into ~/.local/share/applications:

    --------------------------
    FILE: javawebstart.desktop
    --------------------------
        # This file makes Ubuntu associate .jnlp files with Java Web Start (javaws)
        # This file should be adjusted and then copied into ~/.local/share/applications
        # as a file with .desktop extension, e.g. javawebstart.desktop
        # https://askubuntu.com/questions/235861/how-to-associate-jnlp-file-with-javaws
        [Desktop Entry]
        Encoding=UTF-8
        Name=Java 7 Web Start
        Comment=Java 7 Web Start
        Exec=/EDIT-THIS-PATH-TO-YOUR-JRE/bin/javaws %u
        Terminal=false
        Type=Application
        Icon=javaws
        Categories=Application;Network;
        MimeType=application/x-java-jnlp-file;
    --------------------------
    
5. Launch the Java Control Panel by running jre/bin/javacpl.exe on Windows, or jre/bin/jcontrol (formerly jre/bin/ControlPanel) on Linux.
(GS3 binaries now include a JRE in the packages folder if you want to use the bundled JRE.)
In the Java Control Panel, go to the Security tab, set Security level to High if not already set.
Click Edit Site List, and then press Add to add the host:port that the GS3 will run on.
Remember, to be accessible to the outside world, the host can't be "localhost", but would be the hostname of your machine or public IP.

6. Make the GLI link on the home page active: Open web/interfaces/default/transform/pages/home.xsl for editing, find the line

    <!--<gslib:libraryInterfaceLink/><br/><br/>-->

    and remove the comments. i.e. change it to

    <gslib:libraryInterfaceLink/><br/><br/>

7. Start up the GS3 web server and visit your DL library home page, http://[hostname]:8383/greenstone3/library.

8. Since you have set up the JNLP file association in a previous step, you can now click on the "The Librarian Interface" link
and your browser should offer to save or launch a file called GLIappWebStart.jnlp. Click ''Open With'' and in the dropdown box beside it, one of the launcher applications should, at least on Windows, be the "Java(TM) Web Start Launcher" application (javaws) that you associated with .jnlp file extensions. Choose that application as the launcher.
If the browser is able to successfully launch it, Java Web Start will be used to run the GLI application indicated by the JNLP file.
If launching through the browser is not possible, for example, if the launcher application is not listed, as may happen on Linux machines, then choose to save the JNLP file.
It will download the file to a temporary user area (like C:\Users\<user>\AppData\Local\Temp on windows).
And then you can rightclick on the downloaded GLIappWebStart.jnlp file, to launch it with the Java Web Start program you already
associated with this file type. This way should work on both Linux and Windows.

9. After authorising the GLI to run, the JNLP version of the GLI Applet will eventually run and behave like the usual client-GLI
(and like the old GLI applet) from this point onward. Refer to the client-gli section of
http://wiki.greenstone.org/doku.php?id=en:release:3.09_release_notes#setting_up_a_remote_greenstone_3_server


--------------------------
LINKS
--------------------------
Reading on Java Web Start and Java Native Launch protocol (JNLP). The relationship between Java Web Start and JNLP:
https://docs.oracle.com/cd/E84882_01/otn/pdf/E84699_01.pdf
"Java Web Start is a technology that builds on the file association facilities of browsers through the use of Java Native Launch Protocol."
 

Google search: Migrate Java 1.9 webstart

https://docs.oracle.com/javase/9/whatsnew/toc.htm
https://docs.oracle.com/javase/9/deploy/migrating-java-applets-jnlp.htm
    section "Migrating an Existing Java Applet"
https://docs.oracle.com/javase/9/deploy/self-contained-application-packaging.htm
http://www.oracle.com/technetwork/java/javase/migratingfromapplets-2872444.pdf
https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/applet_dev_guide.html
https://dzone.com/articles/java-web-start-jnlp-hello

https://docs.oracle.com/javase/tutorial/uiswing/examples/misc/index.html
https://bugs.openjdk.java.net/browse/JDK-8178799
https://www.v3.co.uk/v3-uk/news/2443810/oracle-signals-the-end-of-java-applet-support-for-browsers
https://schneide.wordpress.com/2016/10/11/the-migration-path-for-java-applets/
https://docs.oracle.com/javase/9/deploy/jnlp-file-syntax.htm
https://docs.oracle.com/javase/tutorial/deployment/deploymentInDepth/embeddingJNLPFileInWebPage.html
https://stackoverflow.com/questions/7313317/jnlp-as-a-applet-in-html-page

https://stackoverflow.com/questions/17338711/jarsigner-manifest-permissions
https://stackoverflow.com/questions/19659134/how-do-i-fix-missing-codebase-permissions-and-application-name-manifest-attri
https://docs.oracle.com/javase/7/docs/technotes/guides/jweb/security/manifest.html#codebase
https://docs.oracle.com/javase/tutorial/deployment/jar/modman.html
https://docs.oracle.com/javase/tutorial/deployment/jar/build.html
https://stackoverflow.com/questions/18907695/ioexception-invalid-header-field-when-creating-jar-file-with-manifest
https://docs.oracle.com/javase/tutorial/deployment/jar/manifestindex.html
https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#JARManifest
https://community.oracle.com/thread/1536875?start=0

https://stackoverflow.com/questions/1199211/java-webstart-with-parameters
https://stackoverflow.com/questions/14116640/how-to-use-jnlp-to-pass-command-line-arguments-to-the-application


IMPORTANT: links for deleting keystores to regenerate from scratch
* https://www.tbs-certificates.co.uk/FAQ/en/supprimer-certificat-keystore-java.html
  
    1. Make a work copy of your keystore on which we're going to make modifications.
    2. Identify the problematic alias with the following command: "keytool -list -v -keystore <keystoreCopy.jks>". In our case:
    
        keytool -list -v -keystore appletstore

    3. Remove the alias from the certificate: "keytool -delete -alias <aliasToRemove> -keystore <keystoreCopy.jks>". In our case:
       keytool -delete -alias privateKey -keystore appletstore

    4. Replace your server's keystore by your copy.

* https://superuser.com/questions/1061638/where-are-certificate-private-keys-stored-in-windows-7