com.oracle.truffle.api.library

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 Message.resolve(Class, String) with a known library class and message name. 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 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:

ReflectionLibrary, Library

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Message(Class<? extends Library> libraryClass, String messageName, int id, boolean deprecated, Class<?> returnType, Class<?>... parameterTypes)
protected	Message(Class<? extends Library> libraryClass, String messageName, int id, Class<?> returnType, Class<?>... parameterTypes)

Method Summary

Modifier and Type	Method and Description
protected Object	clone()
boolean	equals(Object obj)
LibraryFactory<?>	getFactory()
int	getId() Returns a unique message id within a library.
Class<? extends Library>	getLibraryClass() Returns the library class of this message.
String	getLibraryName() Returns the name of the library of this message.
int	getParameterCount() Returns the number of parameters including the receiver type.
Class<?>	getParameterType(int index) Just like Message.getParameterTypes() but returns the parameter of a given index in a partial evaluation safe way.
List<Class<?>>	getParameterTypes() Returns all parameter types including the receiver type of the message.
String	getQualifiedName() Returns a qualified and unique name of this message.
Class<?>	getReceiverType() Returns the receiver type of the message.
Class<?>	getReturnType() Returns the return type of the message.
String	getSimpleName() Returns the simple name of this message.
int	hashCode()
boolean	isDeprecated() Returns true if this message is deprecated.
static Message	resolve(Class<? extends Library> libraryClass, String messageName) Resolves a message globally for a given library class and message name.
static Message	resolve(Class<? extends Library> libraryClass, String messageName, boolean fail) Resolves a message globally for a given library class and message name.
String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

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 Detail

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:

Message.getSimpleName(), Message.getLibraryName()

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 Message.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

equals

public final boolean equals(Object obj)

Overrides:

equals in class Object

Since:

19.0

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

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

public static Message resolve(Class<? extends Library> libraryClass,
                              String messageName)

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 and message. 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:

19.0

resolve

public static Message resolve(Class<? extends Library> libraryClass,
                              String messageName,
                              boolean fail)

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 and message. 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.

Since:

19.0