change error message for version mismatch

Author: david-beaumont

src/java.base/share/classes/jdk/internal/jimage/BasicImageReader.java

@@ -24,9 +24,7 @@
  */
 package jdk.internal.jimage;
 
-import java.io.ByteArrayInputStream;
 import java.io.IOException;
-import java.io.InputStream;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.nio.ByteBuffer;
@@ -41,6 +39,10 @@
 import java.util.stream.IntStream;
 import jdk.internal.jimage.decompressor.Decompressor;
 
+import static jdk.internal.jimage.BasicImageReader.ImageError.Reason.BAD_VERSION;
+import static jdk.internal.jimage.BasicImageReader.ImageError.Reason.CORRUPT_JIMAGE;
+import static jdk.internal.jimage.BasicImageReader.ImageError.Reason.INVALID_JIMAGE;
+
 /**
  * @implNote This class needs to maintain JDK 8 source compatibility.
  *
@@ -144,10 +146,10 @@ public Void run() {
             if (channel.read(headerBuffer, 0L) == headerSize) {
                 headerBuffer.rewind();
             } else {
-                throw new IOException("\"" + name + "\" is not an image file");
+                throw new ImageError(INVALID_JIMAGE, "\"" + name + "\" is not an image file");
             }
         } else if (headerBuffer.capacity() < headerSize) {
-            throw new IOException("\"" + name + "\" is not an image file");
+            throw new ImageError(INVALID_JIMAGE, "\"" + name + "\" is not an image file");
         }
 
         // Interpret the image file header
@@ -164,7 +166,7 @@ public Void run() {
 
         // Interpret the image index
         if (memoryMap.capacity() < indexSize) {
-            throw new IOException("The image file \"" + name + "\" is corrupted");
+            throw new ImageError(CORRUPT_JIMAGE, "The image file \"" + name + "\" is corrupted");
         }
         redirect = intBuffer(memoryMap, header.getRedirectOffset(), header.getRedirectSize());
         offsets = intBuffer(memoryMap, header.getOffsetsOffset(), header.getOffsetsSize());
@@ -191,14 +193,14 @@ private ImageHeader readHeader(IntBuffer buffer) throws IOException {
         ImageHeader result = ImageHeader.readFrom(buffer);
 
         if (result.getMagic() != ImageHeader.MAGIC) {
-            throw new IOException("\"" + name + "\" is not an image file");
+            throw new ImageError(INVALID_JIMAGE, "\"" + name + "\" is not an image file");
         }
 
         if (result.getMajorVersion() != ImageHeader.MAJOR_VERSION ||
-            result.getMinorVersion() != ImageHeader.MINOR_VERSION) {
-            throw new IOException("The image file \"" + name + "\" is not " +
-                "the correct version. Major: " + result.getMajorVersion() +
-                ". Minor: " + result.getMinorVersion());
+                result.getMinorVersion() != ImageHeader.MINOR_VERSION) {
+            throw new ImageError(BAD_VERSION, "The image file \"" + name + "\" is not " +
+                    "the correct version. Major: " + result.getMajorVersion() +
+                    ". Minor: " + result.getMinorVersion());
         }
 
         return result;
@@ -457,10 +459,31 @@ public ByteBuffer getResourceBuffer(ImageLocation loc) {
         return null;
     }
 
-    public InputStream getResourceStream(ImageLocation loc) {
-        Objects.requireNonNull(loc);
-        byte[] bytes = getResource(loc);
+    /**
+     * Specialized {@link IOException} thrown during construction which provides
+     * a semantic reason for failure.
+     */
+    public final static class ImageError extends IOException {
+        private static final long serialVersionUID = 6002259582237888214L;
+
+        public enum Reason {
+            /** The file being opened does not appear to be a jimage file. */
+            INVALID_JIMAGE,
+            /** The jimage file being opened is corrupted. */
+            CORRUPT_JIMAGE,
+            /** The jimage file being opened has the wrong version. */
+            BAD_VERSION,
+        }
+
+        private final Reason reason;
 
-        return new ByteArrayInputStream(bytes);
+        public ImageError(Reason reason, String message) {
+            super(message);
+            this.reason = reason;
+        }
+
+        public Reason getReason() {
+            return reason;
+        }
     }
 }

src/jdk.jlink/share/classes/jdk/tools/jimage/JImageTask.java

@@ -30,6 +30,7 @@
 import java.io.PrintWriter;
 import java.nio.file.FileSystem;
 import java.nio.file.Files;
+import java.nio.file.Path;
 import java.nio.file.PathMatcher;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -44,6 +45,7 @@
 import java.lang.classfile.MethodModel;
 
 import jdk.internal.jimage.BasicImageReader;
+import jdk.internal.jimage.BasicImageReader.ImageError.Reason;
 import jdk.internal.jimage.ImageHeader;
 import jdk.internal.jimage.ImageLocation;
 import jdk.tools.jlink.internal.ImageResourcesTree;
@@ -435,6 +437,22 @@ private void iterate(JImageAction jimageAction,
                     }
                 }
             } catch (IOException ioe) {
+                // Handle specific errors for which better advice can be given.
+                if (ioe instanceof BasicImageReader.ImageError err) {
+                    if (err.getReason() == Reason.BAD_VERSION) {
+                        Path p = file.toPath();
+                        if (p.endsWith(Path.of("lib", "modules"))) {
+                            // Looks like jimage tool is in the standard JDK directory.
+                            p = p.subpath(0, p.getNameCount() - 2).resolve("bin", "jimage");
+                            if (Files.isRegularFile(p)) {
+                                // Suggest what we hope is the correct tool path.
+                                throw TASK_HELPER.newBadArgs("err.bad.version.suggest", file, p);
+                            }
+                        }
+                        throw TASK_HELPER.newBadArgs("err.bad.version", file);
+                    }
+                }
+                // Non-specific error during processing.
                 throw TASK_HELPER.newBadArgs("err.invalid.jimage", file, ioe.getMessage());
             }
         }

src/jdk.jlink/share/classes/jdk/tools/jimage/resources/jimage.properties

@@ -31,20 +31,20 @@ main.usage=\
 Usage: {0} <extract | info | list | verify> <options> jimage...\n\
 \n\
 \  extract  - Extract all jimage entries and place in a directory specified\n\
-\             by the --dir=<directory> (default='.') option.\n\
+\             by the --dir=<directory> (default=''.'') option.\n\
 \n\
 \  info     - Prints detailed information contained in the jimage header.\n\
 \n\
 \  list     - Prints the names of all the entries in the jimage.  When used with\n\
 \             --verbose, list will also print entry size and offset attributes.\n\
 \n\
-\  verify   - Reports on any .class entries that don't verify as classes.\n\
+\  verify   - Reports on any .class entries that don''t verify as classes.\n\
 \n\
 Possible options include:
 
 main.usage.extract=\
 \  extract  - Extract all jimage entries and place in a directory specified\n\
-\             by the --dir=<directory> (default='.') option.
+\             by the --dir=<directory> (default=''.'') option.
 
 main.usage.info=\
 \  info     - Prints detailed information contained in the jimage header.
@@ -54,7 +54,7 @@ main.usage.list=\
 \             --verbose, list will also print entry size and offset attributes.
 
 main.usage.verify=\
-\  verify   - Reports errors on any .class entries that don't verify as classes.
+\  verify   - Reports errors on any .class entries that don''t verify as classes.
 
 error.prefix=Error:
 warn.prefix=Warning:
@@ -101,3 +101,12 @@ err.no.jimage=no jimage provided
 err.option.unsupported={0} not supported: {1}
 err.unknown.option=unknown option: {0}
 err.cannot.create.dir=cannot create directory {0}
+
+err.bad.version=Unable to open {0}: mismatched file version\n\
+\  Use ''<JAVA_HOME>/bin/jimage'' for the JDK associated with this jimage file.
+
+# Apart from the trailing line (and newline before it), this message should
+# be identical to 'err.bad.version'.
+err.bad.version.suggest=Unable to open {0}: mismatched file version\n\
+\  Use ''<JAVA_HOME>/bin/jimage'' for the JDK associated with this jimage file.\n\
+\  Found candidate tool: {1}