eXist-db/documentation

Document how to load custom Java Libraries

adamretter opened this issue · 9 comments

adamretter commented
  1. Place them in $EXIST_HOME/lib/
  2. Make an entry for them in the .xml file which has the same name as the .bat/.sh file that you use from $EXIST_HOME/bin.
  3. Restart the database.
duncdrum commented

while we're at it we should also mention how to do this for docker containers

TurekBot commented

Excited to see this documentation. Thanks all!

gmella commented

Please find some comments.
It seems that startup.xml is honored by standalone version only through org.codehaus.mojo.appassembler.booter.AppassemblerBooter. Docker does not use the .xml just
running org.exist.start.Main

I used to call method from jar which were part of my xar files. This was very nice and easy saving overhead of writting a java module for some basic or rapid code. I would be very happy to find such dynamic integration back again through docker also.

@dariok, my workarround to call Java Methods from XQuery in my docker containers is to override the CLASSPATH env adding path to my jar. I bind the jar file using a volume. See ex. in my docker-compose below

  environment:
# does not work :(    - CLASSPATH=/exist/lib/exist.uber.jar:/exist/data/expathrepo/jmmc-resources-0.23/content/jmal-TRUNK.jar
    - CLASSPATH=/exist/lib/exist.uber.jar:/exist/lib/jmal-TRUNK.jar
  volumes:
# next line is a workarround for current limitation : https://github.com/eXist-db/exist/issues/1771      
    - ./jmmc-resources/content/jmal-TRUNK.jar:/exist/lib/jmal-TRUNK.jar
duncdrum commented

@adamretter why would a .xar need startup.xml for dynamically added java module?

@gmella your workaround is the save route for now, while we're looking into the issue. Would it be possible to have a look at you xar to see what it contains to inform exist about its jar?

gmella commented

@duncdrum yes please have a look on http://www.jmmc.fr/~mellag/files/jmmc-resources-0.23.xar and content/jmmc-astro.xql At the same time this package includes content/jmmc-oiexplorer.xql which relies on an existdb extension module. Second part runs smoothly (if declared properly ;) see exist#3004 ;) )

joewiz commented

@adamretter said during this week's Community Call that "the .xml file" referenced in step 2 of his instructions above is already present in the etc folder of eXist distributions. Here is a list:

  • etc/backup.xml
  • etc/client.xml
  • etc/export-gui.xml
  • etc/export.xml
  • etc/jmxclient.xml
  • etc/launcher.xml
  • etc/shutdown.xml
  • etc/startup.xml

So just add an entry to the file here whose name corresponds to the .sh/.bat file from the bin directory that you use to start eXist - following the other examples already in the xml file.

dariok commented

@joewiz That is correct and it works when using one of these scripts.
The problem, however, is that none of these .sh/.bat scripts is used to start eXist when using a docker container. So the open question is whether there is a default xml config file to use when starting eXist via java org.exist.start.Main.

adamretter commented

So just to confirm that when using Docker, AppassemblerBooter is NOT used.

AppassemblerBooter is called from the .sh/.bat files, and is the thing that reads the etc/*.xml files to determine which jar files to load.

AppAssemblerBooter is only used for a full-fat eXist-db distribution. For Docker we do something different and build eXist-db into a single Uber jar, which is loaded directly via the CLASSPATH Env.

So if you want to add additional Jars to eXist-db:

  1. For an eXist-db distribution, (i.e. with AppAssemblerBooter), add the jar files to $EXIST_HOME/lib and modify the XML file in $EXIST_HOME/etc to load that jar file via the $EXIST_HOME/bin/ *.sh/*.bat script that you use. For example, if you use $EXIST_HOME/bin/startup.sh you should modify $EXIST_HOME/etc/startup.xml.

  2. For an eXist-db Docker image, override the ENV CLASSPATH= in the Dockerfile to also contain your custom jar, e.g. ENV CLASSPATH=/exist/lib/exist.uber.jar:/path-to-your/your-lib.jar, and make sure your jar is available at /path-to-your/your-lib.jar by using a Docker volume or whatever you need.

duncdrum commented

or whatever you need

@adamretter yes, depending on when in the livecycle you are modifying the container /path-to-your/your-lib.jar is potentially ephemeral. Docker Volumes side-step this, docker commit e.g. on ci would be another way around this.

Based on the reports so far, I m still not sure if there is a bug with exist not finding jars, when they have been added to an image at build time. In which case docker exec … might be necessary to trigger a rescan of the classpath / jars.