+ * The runtime version information is provided by {@link #VERSION} and + * {@link #getRuntimeVersion()}. Detailed information about these values is + * provided in the documentation for each member.
* - * public class+ * The runtime version check is implemented by {@link #checkVersion}. Detailed + * information about incorporating this call into user code, as well as its use + * in generated code, is provided in the documentation for the method.
* - * This way, previous versions of target X that are incompatible (e.g., 4.1 and 4.2) will result in - * a warning emitted through the appropriate channel for that target. This can be a msg to stderr or - * an exception; it's up to the target developer. I have decided to throw an exception for Java target - * as a message might not be seen if the parser were embedded in a server or something. + *+ * By default, the {@link DefaultListener#INSTANCE} listener is automatically + * registered. As long as the default listener is registered, it will always be + * the last listener notified in the event of a version mismatch. This behavior + * ensures the exception it throws will not prevent {@link #checkVersion} from + * notifying custom listeners registered by a user. This default listener may be + * removed by calling {@link #removeListener} for + * {@link DefaultListener#INSTANCE} or {@link #clearListeners}. If required, it + * may be re-registered by calling {@link #addListener}.
*/ public class RuntimeMetaData { - public static class ANTLRVersionMismatchException extends RuntimeException { - public String generatedCodeVersion; - public String runtimeLibVersion; + /** + * This class provides detailed information about a mismatch between the + * version of the tool a parser was generated with, the version of the + * runtime a parser was compiled against, and/or the currently executing + * version of the runtime. + * + * @see #checkVersion + */ + public static class VersionMismatchException extends RuntimeException { + /** + * The version of the ANTLR 4 Tool a parser was generated with. This + * value may be {@code null} if {@link #checkVersion} was called from + * user-defined code instead of a call automatically included in the + * generated parser. + */ + @Nullable + public final String generatingToolVersion; + /** + * The version of the ANTLR 4 Runtime library the parser and/or user + * code was compiled against. + */ + @NotNull + public final String compileTimeRuntimeVersion; - public ANTLRVersionMismatchException(String message, String generatedCodeVersion, String runtimeLibVersion) { - super(message); - this.generatedCodeVersion = generatedCodeVersion; - this.runtimeLibVersion = runtimeLibVersion; - } + /** + * Constructs a new instance of the {@link VersionMismatchException} + * class with the specified detailed information about a mismatch + * between ANTLR tool and runtime versions used by a parser. + * + * @param message the detail message. The detail message is saved for + * later retrieval by the {@link #getMessage()} method. + * @param generatingToolVersion The version of the ANTLR 4 Tool a parser + * was generated with, or {@code null} if the version check was not part + * of the automatically-generated parser code + * @param compileTimeRuntimeVersion The version of the ANTLR 4 Runtime + * library the code was compiled against + */ + VersionMismatchException(@NotNull String message, @Nullable String generatingToolVersion, @NotNull String compileTimeRuntimeVersion) { + super(message); + this.generatingToolVersion = generatingToolVersion; + this.compileTimeRuntimeVersion = compileTimeRuntimeVersion; + } + } - @Override - public String getMessage() { - return super.getMessage()+": code version "+generatedCodeVersion+" != runtime version "+runtimeLibVersion; - } - } + /** + * This interface defines a listener which handles notifications about + * mismatched ANTLR Tool and/or Runtime versions. + */ + public interface Listener { + /** + * Report a version mismatch which was detected by + * {@link #checkDetails}. + * + *+ * Implementations of this method may, but are not required to, throw + * the provided exception. Note that if a registered listener throws the + * provided exception during the handling of this event, the following + * will be impacted:
+ * + *+ * This compile-time constant value allows generated parsers and other + * libraries to include a literal reference to the version of the ANTLR 4 + * runtime library the code was compiled against.
+ * + *+ * During development (between releases), this value contains the + * expected next release version. For official releases, the value + * will be the actual published version of the library.
+ */ + public static final String VERSION = "4.2.3"; + + /** + * Gets the currently executing version of the ANTLR 4 runtime library. + * + *+ * This method provides runtime access to the {@link #VERSION} field, as + * opposed to directly referencing the field as a compile-time constant.
+ * + * @return The currently executing version of the ANTLR 4 library + */ + @NotNull + public static String getRuntimeVersion() { + return VERSION; + } + + /** + * This method provides the ability to detect mismatches between the version + * of ANTLR 4 used to generate a parser, the version of the ANTLR runtime a + * parser was compiled against, and the version of the ANTLR runtime which + * is currently executing. + * + *+ * The version check is designed to detect the following two specific + * scenarios.
+ * + *+ * Starting with ANTLR 4.2.3, the code generator emits a call to this method + * using two constants in each generated lexer and parser: a hard-coded + * constant indicating the version of the tool used to generate the parser + * and a reference to the compile-time constant {@link #VERSION}. At + * runtime, this method is called during the initialization of the generated + * parser to detect mismatched versions, and notify the registered listeners + * prior to creating instances of the parser.
+ * + *+ * This method does not perform any detection or filtering of semantic + * changes between tool and runtime versions. It simply checks for a simple + * version match and notifies the registered listeners any time a difference + * is detected.
+ * + *+ * Note that some breaking changes between releases could result in other + * types of runtime exceptions, such as a {@link LinkageError}, prior to + * calling this method. In these cases, the underlying version mismatch will + * not be reported to the listeners. This method is primarily intended to + * notify users of potential semantic changes between releases that do not + * result in binary compatibility problems which would be detected by the + * class loader. As with semantic changes, changes which break binary + * compatibility between releases are mentioned in the release notes + * accompanying the affected release.
+ * + *+ * Additional note for target developers: The version check + * implemented by this class is designed to address specific compatibility + * concerns that may arise during the execution of Java applications. Other + * targets should consider the implementation of this method in the context + * of that target's known execution environment, which may or may not + * resemble the design provided for the Java target.
+ * + * @param toolVersion The version of the tool used to generate a parser. + * This value may be null when called from user code that was not generated + * by, and does not reference, the ANTLR 4 Tool itself. + * @param compileTimeVersion The version of the runtime the parser was + * compiled against. This should always be passed using a direct reference + * to {@link #VERSION}. + */ + public static void checkVersion(@Nullable String toolVersion, @NotNull String compileTimeVersion) { + boolean report = false; + String message = null; + if (toolVersion != null && !VERSION.equals(toolVersion)) { + report = true; + message = String.format("ANTLR Tool version %s used for code generation does not match the current runtime version %s", toolVersion, VERSION); + } + else if (!VERSION.equals(compileTimeVersion)) { + report = true; + message = String.format("ANTLR Runtime version %s used for parser compilation does not match the current runtime version %s", compileTimeVersion, VERSION); + } + + if (report) { + VersionMismatchException ex = new VersionMismatchException(message, toolVersion, compileTimeVersion); + for (Listener listener : listeners) { + listener.reportVersionMismatch(ex); + } + } + } } diff --git a/tool/resources/org/antlr/v4/tool/templates/codegen/Java/Java.stg b/tool/resources/org/antlr/v4/tool/templates/codegen/Java/Java.stg index f6286f0f6..edd53bd3d 100644 --- a/tool/resources/org/antlr/v4/tool/templates/codegen/Java/Java.stg +++ b/tool/resources/org/antlr/v4/tool/templates/codegen/Java/Java.stg @@ -214,7 +214,7 @@ Parser(parser, funcs, atn, sempredFuncs, superClass) ::= << Parser_(parser, funcs, atn, sempredFuncs, ctor, superClass) ::= << @SuppressWarnings({"all", "warnings", "unchecked", "unused", "cast"}) public class