Class Message

java.lang.Object
com.oracle.truffle.api.library.Message
public abstract class Message extends Object
Represents a description of library message. A message description refers to one public method in a library subclass. Messages may be resolved dynamically by calling resolveExact(Class, String, Class[]) with a known library class, message name and parameter types. Message instances provide meta-data about the simple and qualified name of the message, return type, receiver type, parameter types and library name. Message instances are used to invoke library messages or implement library messages reflectively using the reflection library.

Message instances are globally unique and can safely be compared by identity. In other words, if the same message is resolveExact(Class, String, Class[]) resolved} twice the same instance will be returned. Since they are shared message instances must not be used as locks to avoid deadlocks.

Note: This class is intended to be sub-classed by generated code only and must *not* be sub-classed by user-code.

Since:
19.0
See Also:

  • Constructor Details

    • Message

      protected Message(Class<? extends Library> libraryClass, String messageName, int id, Class<?> returnType, Class<?>... parameterTypes)
      Since:
      22.0

    • Message

      protected Message(Class<? extends Library> libraryClass, String messageName, int id, boolean deprecated, Class<?> returnType, Class<?>... parameterTypes)
      Since:
      23.0

  • Method Details

    • getId

      public final int getId()
      Returns a unique message id within a library.
      Returns:
      a non-negative message id or -1 if the message is not assigned a unique id.
      Since:
      22.0

    • getQualifiedName

      public final String getQualifiedName()
      Returns a qualified and unique name of this message. The qualified name is specified as getLibraryName() + "." + getSimpleName(). The returned name is interned can can safely be compared by identity. The returned name is never null.
      Since:
      19.0
      See Also:

    • getSimpleName

      public final String getSimpleName()
      Returns the simple name of this message. The simple name is unique per library and equals the method name of the method in the library specification class. The returned name is interned can can safely be compared by identity. The returned name is never null.
      Since:
      19.0

    • getLibraryName

      public final String getLibraryName()
      Returns the name of the library of this message. The name of the library is specified as the name of the library class. The returned name is never null.
      Since:
      19.0

    • getReturnType

      public final Class<?> getReturnType()
      Returns the return type of the message. The return type can be useful for reflective invocations of the message.
      Since:
      19.0

    • getReceiverType

      public final Class<?> getReceiverType()
      Returns the receiver type of the message. The receiver type is always the same as the first parameter type. In many cases the receiver type of a message is Object. However, it possible for libraries to restrict the receiver type to sub-types. The receiver type may be useful for reflective invocations of the message.
      Since:
      19.0

    • getParameterTypes

      public final List<Class<?>> getParameterTypes()
      Returns all parameter types including the receiver type of the message. The returned immutable parameter types list corresponds to the Method.getParameterTypes() parameter types of the declared library method. The parameter types may be useful for reflective invocations of the message.
      Since:
      19.0

    • getParameterType

      public final Class<?> getParameterType(int index)
      Just like getParameterTypes() but returns the parameter of a given index in a partial evaluation safe way.
      Since:
      21.3

    • getParameterCount

      public final int getParameterCount()
      Returns the number of parameters including the receiver type.
      Since:
      19.0

    • isDeprecated

      public final boolean isDeprecated()
      Returns true if this message is deprecated.
      Since:
      23.0

    • getLibraryClass

      public final Class<? extends Library> getLibraryClass()
      Returns the library class of this message. The library class may be used to resolve other messages of the same library.
      Since:
      19.0

    • getFactory

      public final LibraryFactory<?> getFactory()
      Since:
      19.0

    • clone

      protected final Object clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException
      Since:
      19.0

    • toString

      public final String toString()
      Overrides:
      toString in class Object
      Since:
      19.0

    • resolve

      @Deprecated(since="25.1") public static Message resolve(Class<? extends Library> libraryClass, String messageName)
      Deprecated.
      since 25.1, use resolveExact(Class, String, Class...) instead. Since library messages can now be deprecated and replaced, they need to be resolved with argument types.
      Since:
      19.0

    • resolve

      @Deprecated(since="25.1") public static Message resolve(Class<? extends Library> libraryClass, String messageName, boolean fail)
      Deprecated.
      since 25.1, use resolveExact(Class, String, boolean, Class...) instead. Since library messages can now be deprecated and replaced, they need to be resolved with argument types.
      Since:
      19.0

    • resolveExact

      public static Message resolveExact(Class<? extends Library> libraryClass, String messageName, Class<?>... argumentTypes)
      Resolves a message globally for a given library class, message name and argument types. The message name corresponds to the method name of the library message. The returned message always returns the same instance for a combination of library class, message and argument types. The provided library class and message name must not be null. If the library or message is invalid or not found an IllegalArgumentException is thrown.
      Parameters:
      libraryClass - the class of the library this message is contained in.
      messageName - the simple name of this message.
      Since:
      25.1

    • resolveExact

      public static Message resolveExact(Class<? extends Library> libraryClass, String messageName, boolean fail, Class<?>... argumentTypes)
      Resolves a message globally for a given library class and message name. The message name corresponds to the method name of the library message. The returned message always returns the same instance for a combination of library class, message and argument types. The provided library class and message name must not be null.
      Parameters:
      libraryClass - the class of the library this message is contained in.
      messageName - the simple name of this message.
      fail - whether to fail with an IllegalArgumentException or return null if the message was not found.
      argumentTypes - the parameter types of the message
      Since:
      25.1