0

Can anyone please post detailed, step-by-step instructions how to install Saxon (10 HE) and how to run a transformation from the command line in MacOS (10.13.6)?

I have installed Java on my computer.
I have downloaded the SaxonHE10-6J.zip file from SourceForge.
Based on the recommendation here I have placed the saxon-he-10.6.jar in the myUserName/Library/Java/Extensions folder.
I then opened the Terminal application and entered a command based on this answer:

java -jar saxon-he-10.6.jar -'/Users/myUserName/Documents/path/to/mystylesheet.xsl' -s:'/Users/myUserName/Documents/path/to/some.xml'

This results in:

Unable to access jarfile saxon-he-10.6.jar

All my attempts, including moving the .jar file to the /Library/Java/Extensions directory or including a full path to the .jar file within the command failed with the same error message.

Please note that I am not a Java developer and I do not intend to use this in an application. All I want is to be able to perform an occasional transformation.

I should also note that the locations of my XML and XSLT files may change from one case to another. I would like to be able to keep the .jar file in a constant location and supply the paths to the XML and XSLT files as required - IOW, I want to have a command template where I only need to change the 2 filepaths (and possibly add some options to the transformation).

What do I need to do?

Martin Honnen
  • 160,499
  • 6
  • 90
  • 110
y.arazim
  • 866
  • 2
  • 10
  • Are you able to or have you managed to run other Java applications before using `java -jar`? Is that approach failing for Saxon or in general? I would the `java -jar ` mechanism expect to work if you provide the full file path of the jar, wherever you put it. Note that `-'/Users/myUserName/Documents/path/to/mystylesheet.xsl'` seems wrong, you want `xsl:filetoxsl.xsl`. – Martin Honnen Oct 14 '21 at 19:51
  • I tried *again* providing the full path to the .jar file and NOW it works. Thank you very much! Now, you wouldn't know how to do the same for Xalan 2.7.2 by any chance? Also, do I need the other files included in the Saxon download (e.g. `jline-2.14.6.jar`)? – y.arazim Oct 14 '21 at 21:19
  • You don't need the `jline-2.14.6.jar` unless you use the Gizmo utility. – Michael Kay Oct 14 '21 at 21:49
  • I guess I spoke too soon. I have moved the downloaded folder to another location and now I am getting `Error: Could not find or load main class net.sf.saxon.Transform Caused by: java.lang.ClassNotFoundException: net.sf.saxon.Transform`. – y.arazim Oct 14 '21 at 22:13
  • The questions about the various files should be answered in https://www.saxonica.com/html/documentation10/about/gettingstarted/gettingstartedjava.html and https://www.saxonica.com/html/documentation10/about/installationjava/jarfiles.html, running `java -cp` versus `java -jar` in https://www.saxonica.com/html/documentation10/using-xsl/commandline/ – Martin Honnen Oct 15 '21 at 05:55
  • @MartinHonnen Some good soul had removed my comment thanking you for your help, making me appear very rude! I am not a rude person, so again thank you. – y.arazim Oct 18 '21 at 12:22

2 Answers2

6

Eventually I got it working. Although these are not exactly the detailed, step-by-step instructions I was hoping for, I will summarize here what I have learned so far. Hopefully this will save someone the hours of frustration I had to go through.

  • Make sure you have Java installed on your computer. If not, download from Oracle and install.

  • Download Saxon from SourceForge. Unzip and place it anywhere on your hard disk, except:

    • do not place it in /Library/Java/Extensions or in myUserName/Library/Java/Extensions;
    • do not place it within a folder whose name contains a / (see below for description).

  • To initiate a transformation, make your command:

    java -jar 'path/to/saxon-he-10.6.jar' -xsl:'path/to/mystylesheet.xsl' -s:'path/to/some.xml'

  • Alternatively, you can use:

    java -cp 'path/to/saxon-he-10.6.jar' net.sf.saxon.Transform -xsl:'path/to/mystylesheet.xsl' -s:'path/to/some.xml'

    This form can be also used to run XQuery by changing net.sf.saxon.Transform to net.sf.saxon.Query.

  • For adding more options and/or parameters to your command, see the instructions given here:
    https://www.saxonica.com/html/documentation10/using-xsl/commandline/
    but do not follow the instructions at the top of the page regarding the form of the basic command.

Corrections/additions are most welcome.

Description of the problem with folder name containing /:

  1. Put all 3 files (saxon-he-10.6.jar, mystylesheet.xsl and some.xml in a folder named XML/RSS in my Documents folder;

  2. Ran the following command:

    java -jar '/Users/myUserName/Documents/XML:RSS/saxon-he-10.6.jar' -xsl:'/Users/myUserName/Documents/XML:RSS/mystylesheet.xsl' -s:'/Users/myUserName/Documents/XML:RSS/some.xml'

    Received the following error:

    Error: Could not find or load main class net.sf.saxon.Transform Caused by: java.lang.ClassNotFoundException: net.sf.saxon.Transform

  3. Moved only the .jar file to the parent folder and ran the following command:

    java -jar '/Users/myUserName/Documents/saxon-he-10.6.jar' -xsl:'/Users/myUserName/Documents/XML:RSS/mystylesheet.xsl' -s:'/Users/myUserName/Documents/XML:RSS/some.xml'

    Result: successful transformation.

  4. Moved the .jar file back, renamed the folder to XMLRSS and ran the following command:

    java -jar '/Users/myUserName/Documents/XMLRSS/saxon-he-10.6.jar' -xsl:'/Users/myUserName/Documents/XMLRSS/mystylesheet.xsl' -s:'/Users/myUserName/Documents/XMLRSS/some.xml'

    Result: successful transformation.

y.arazim
  • 866
  • 2
  • 10
  • Why are you replacing the "/" by ":"? Why is the "/" between "XML" and "RSS" different from the other "/" characters in the folder path, which you retained? What happens when you set the -jar option to '/Users/myUserName/Documents/XML/RSS/saxon-he-10.6.jar'? – Michael Kay Oct 20 '21 at 06:36
  • @MichaelKay The `/` character is legal in the Macintosh operation system where the separating character for path expressions is `:`. When it comes to the underpinning Unix foundation (where the command line operates) the 2 characters need to be swapped. I used the built-in scripting application to give me the `quoted form of POSIX path of file "Macintosh HD:Users:myUserName:Documents:XML/RSS:saxon-he-10.6.jar"` and the above is the result. – y.arazim Oct 20 '21 at 07:14
  • To answer your question, if the path were as you suggest, I would get `Unable to access jarfile saxon-he-10.6.jar` because it would be looking for a folder named `XML` containing a folder named `RSS` containing the .jar file. The paths I have used are correct, otherwise the XML and XSLT files would not be found. – y.arazim Oct 20 '21 at 07:14
  • Well, I never knew that you could use "/" in a filename other than as a path separator, or escape it by writing it as colon. And it looks as if when it comes to Java, you can't. – Michael Kay Oct 20 '21 at 08:33
  • @MichaelKay I think you are focusing on a non-essential detail. For the current purpose, the folder's name is `XML:RSS`. That is a legal name in Unix and I believe in Java too. Still, when the .jar file is placed in this folder, the command fails. – y.arazim Oct 20 '21 at 08:56
  • Well, your evidence suggests it doesn't work, and I'm not surprised; you can try raising a Java bug with Oracle, but I doubt you'll get very far. Note that in the -cp option a colon is treated as a separator between multiple filenames (like in the PATH environment variable), so it obviously can't be used as a character within a filename in that context. – Michael Kay Oct 20 '21 at 12:02
  • I don't think the colon should be a problem when the filepaths are enclosed in quotes. In any case, I don't intend to spend any more time on this. As I said, I am not a Java developer and my problem is solved. I thought you would be concerned about this since it affects you more than it does me. – y.arazim Oct 20 '21 at 12:32
  • 1
    No, it doesn't concern me in the slightest. It's the first time in 20 years of using Java that I've seen someone try to do this, and the fact that Java doesn't allow it is exactly what I would have expected. – Michael Kay Oct 20 '21 at 15:25
  • I don't see why you would expect a perfectly valid filepath to produce an error. And perhaps you don't know how many people have given up on Saxon in frustration (as I almost did). But if you don't care, then why should I. – y.arazim Oct 20 '21 at 16:08
  • 1
    Well, I can't change Java, so there's no point in my worrying about it. And if I could do anything to make the Java command line more usable, this would be quite low down my list. – Michael Kay Oct 20 '21 at 17:23
2

I don't ever use it myself: however myUserName/Library/Java/Extensions is special as far as the classpath is concerned (you don't need to put JAR files in this directory on the classpath), but it's not special as far as the -jar option is concerned - that needs to be an absolute or relative filename in the normal way and has nothing to do with the classpath.

If you've chosen to put the JAR file in this magic location, then I would use the command java net.sf.saxon.Transform options to pick Saxon up from the classpath rather than identifying the -jar location directly.

There are good reasons for NOT putting Saxon in this magic location, however; one reason is it will affect applications that don't actually want to use Saxon (they might be written to use some other XSLT processor, and you might not actually be aware that they use XSLT at all, until they stop working).

Michael Kay
  • 156,231
  • 11
  • 92
  • 164
  • Ok, but if I don't put the .jar file there, then I am faced with a mystery: if I leave it in my Downloads folder, and provide the path in the command, then it works. But if I move it to another location within my Documents folder, it produces the error shown in the comment above. AFAICT, the only difference is that the new path has folders with spaces in their names. But the path is quoted, so it should not make any difference? – y.arazim Oct 14 '21 at 22:41
  • I think I may have have discovered the reason. One of my folders is named `XML/RSS`. On the command line this is expressed as `XML:RSS`. I moved the .jar file further and further down, and it stopped working when I hit this folder. Could this be the case? But how can this be possible, when the same folder is also used in the path to my XSLT and XML files? Can the same path be valid for a text file but invalid for a .jar file? – y.arazim Oct 15 '21 at 01:52
  • I would also like to know what is the difference (if any) between `java -jar 'path/to/saxon-he-10.6.jar' -xsl:'path/to/mystylesheet.xsl' -s:'path/to/some.xml'` and `java -cp 'path/to/saxon-he-10.6.jar' net.sf.saxon.Transform -xsl:'path/to/mystylesheet.xsl' -s:'path/to/some.xml'`. – y.arazim Oct 15 '21 at 01:57
  • `-jar` loads a specific JAR file and executes its main entry point, which for the Saxon JAR file is net.sf.saxon.Transform. -cp lists multiple JARs or directories to include on the classpath, and you must then specify an explicit entry point, for example `net.sf.saxon.Transform` or `net.sf.saxon.Query`. – Michael Kay Oct 15 '21 at 08:29
  • Thank you for this. You did not address the issue with the error apparently caused by `/` in folder name. The error message suggests this is a Saxon bug. If the .jar file is moved, the error goes away - despite the fact that the XML and XSLT files remain within the same folder. – y.arazim Oct 16 '21 at 09:06
  • You'll have to explain that problem in more detail. Please raise a new question, explaining exactly what you did and exactly how it failed. – Michael Kay Oct 16 '21 at 22:51
  • I thought I did explain it quite clearly. Simply, when I placed the .jar file in a folder named `XML/RSS` I received this message: `Error: Could not find or load main class net.sf.saxon.Transform Caused by: java.lang.ClassNotFoundException: net.sf.saxon.Transform`. I could not find explanation for this behavior other than the `/` in folder's name. I am not interested in posting a new question. I thought you would want to know about this because it seems like a bug in Saxon. And it is very relevant to *this* question because it affects the instruction where to put (or not to put) the .jar file. – y.arazim Oct 17 '21 at 04:12
  • Firstly, you haven't explained it clearly: you haven't given the full command line you used. Secondly, I'm afraid your diagnosis is incorrect. The message comes from Java, not from Saxon, and it simply means that Java couldn't find the Saxon software. If Saxon can't be found, there's no way this could be a bug in Saxon. Finally, your conjecture that it has something to do with the "/" seems both unfounded and improbable. – Michael Kay Oct 17 '21 at 17:18
  • When the .jar file could not be found, the message was `Unable to access jarfile saxon-he-10.6.jar`. Maybe there is a bug in Java. My "conjecture" is based on the fact that when I renamed the folder or moved the .jar file to another location, the problem went away. If you have another explanation for this, I am all ears. – y.arazim Oct 17 '21 at 19:03
  • Oh, and the command was in the form of `java -jar '/Users/myUserName/Documents/XML:RSS/saxon-he-10.6.jar' -xsl:'/Users/myUserName/Documents/XML:RSS/mystylesheet.xsl' -s:'/Users/myUserName/Documents/XML:RSS/some.xml'`. If Java couldn't find the Saxon software, how did it know it was looking for `main class net.sf.saxon.Transform`? – y.arazim Oct 17 '21 at 19:43
  • This is no way to make progress. You're telling us about different things you tried at different times and that failed in different ways. Start again from the beginning with a new question that describes one problem, explains exactly what you did and exactly how it failed. – Michael Kay Oct 18 '21 at 11:14
  • I have added a precise description how to reproduce this behavior to my answer. – y.arazim Oct 18 '21 at 12:13