org.antlr.v4.runtime

Class RuntimeMetaData

java.lang.Object

org.antlr.v4.runtime.RuntimeMetaData

public class RuntimeMetaData
extends Object

This class provides access to the current version of the ANTLR 4 runtime library as compile-time and runtime constants, along with methods for checking for matching version numbers and notifying listeners in the case where a version mismatch is detected.

The runtime version information is provided by VERSION and getRuntimeVersion(). Detailed information about these values is provided in the documentation for each member.

The runtime version check is implemented by checkVersion(java.lang.String, java.lang.String). 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.

By default, the RuntimeMetaData.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 that custom listeners registered by a user will be notified even in the event the default listener throws an exception. This default listener may be removed by calling removeListener(org.antlr.v4.runtime.RuntimeMetaData.Listener) for RuntimeMetaData.DefaultListener.INSTANCE or clearListeners(). If required, it may be re-registered by calling addListener(org.antlr.v4.runtime.RuntimeMetaData.Listener).

Since:

4.3

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RuntimeMetaData.DefaultListener This class provides a default implementation of RuntimeMetaData.Listener which responds to mismatched versions by throwing the provided RuntimeMetaData.VersionMismatchException if the reported version mismatch indicates the versions differ by more than the major and minor version components.
static interface	RuntimeMetaData.Listener This interface defines a listener which handles notifications about mismatched ANTLR Tool and/or Runtime versions.
static class	RuntimeMetaData.VersionMismatchException 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.

Field Summary

Fields

Modifier and Type	Field and Description
static String	VERSION A compile-time constant containing the current version of the ANTLR 4 runtime library.

Constructor Summary

Constructors

Constructor and Description
RuntimeMetaData()

Method Summary

Methods

Modifier and Type	Method and Description
static void	addListener(RuntimeMetaData.Listener listener) Register a listener to receive notifications of mismatched ANTLR versions.
static void	checkVersion(String toolVersion, String compileTimeVersion) 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.
static void	clearListeners() Remove all listeners registered to receive notifications of mismatched ANTLR versions.
static String	getRuntimeVersion() Gets the currently executing version of the ANTLR 4 runtime library.
static boolean	removeListener(RuntimeMetaData.Listener listener) Remove a specific listener registered to receive notifications of mismatched ANTLR versions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSION

public static final String VERSION

A compile-time constant containing the current version of the ANTLR 4 runtime library.

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.

See Also:

Constant Field Values

Constructor Detail

RuntimeMetaData

public RuntimeMetaData()

Method Detail

addListener

public static void addListener(@NotNull
               RuntimeMetaData.Listener listener)

Register a listener to receive notifications of mismatched ANTLR versions. This method ensures that as long as RuntimeMetaData.DefaultListener.INSTANCE is registered as a listener, it will always be the last listener notified of mismatched versions.

Parameters:

listener - the listener to notify if mismatched ANTLR versions are detected

See Also:

checkVersion(java.lang.String, java.lang.String)

removeListener

public static boolean removeListener(@NotNull
                     RuntimeMetaData.Listener listener)

Remove a specific listener registered to receive notifications of mismatched ANTLR versions.

Parameters:

listener - the listener to remove

Returns:

true if the listener was removed; otherwise, false if the specified listener was not found in the list of registered listeners

clearListeners

public static void clearListeners()

Remove all listeners registered to receive notifications of mismatched ANTLR versions.

getRuntimeVersion

@NotNull
public static String getRuntimeVersion()

Gets the currently executing version of the ANTLR 4 runtime library.

This method provides runtime access to the VERSION field, as opposed to directly referencing the field as a compile-time constant.

Returns:

The currently executing version of the ANTLR 4 library

checkVersion

public static void checkVersion(@Nullable
                String toolVersion,
                @NotNull
                String compileTimeVersion)

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.

• The ANTLR Tool version used for code generation does not match the currently executing runtime version.
• The ANTLR Runtime version referenced at the time a parser was compiled does not match the currently executing runtime version.

Starting with ANTLR 4.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 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. A default instance of RuntimeMetaData.DefaultListener is notified unless it is explicitly removed.

Note that some breaking changes between releases could result in other types of runtime exceptions, such as a 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.

Parameters:

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.

compileTimeVersion - The version of the runtime the parser was compiled against. This should always be passed using a direct reference to VERSION.