org.jruby.runtime

Class MethodFactory

java.lang.Object

org.jruby.runtime.MethodFactory

Direct Known Subclasses:

InvocationMethodFactory, ReflectionMethodFactory

public abstract class MethodFactory
extends Object

MethodFactory is used to generate "invokers" or "method handles" given a target class, method name, and other characteristics. In order to bind methods into Ruby's reified class hierarchy, we need a way to treat individual methods as objects. Implementers of this class provide that functionality.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MethodFactory.MethodDefiningCallback Deprecated.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	CAN_LOAD_BYTECODE A test to see if we can load bytecode dynamically, so we know whether InvocationMethodFactory will work.
static Class[]	COMPILED_METHOD_PARAMS A Class[] representing the signature of compiled Ruby method.

Constructor Summary

Constructors

Constructor and Description
MethodFactory()

Method Summary

Methods

Modifier and Type	Method and Description
static MethodFactory	createFactory(ClassLoader classLoader) Based on optional properties, create a new MethodFactory.
abstract DynamicMethod	getAnnotatedMethod(RubyModule implementationClass, JavaMethodDescriptor desc) Based on an annotated Java method object, generate a method handle using the annotation and the target signature.
abstract DynamicMethod	getAnnotatedMethod(RubyModule implementationClass, List<JavaMethodDescriptor> desc) Based on a list of annotated Java methods, generate a method handle using the annotation and the target signatures.
abstract CompiledBlockCallback	getBlockCallback(String method, String file, int line, Object scriptObject) Get a CompiledBlockCallback for the specified block
abstract CompiledBlockCallback19	getBlockCallback19(String method, String file, int line, Object scriptObject) Get a CompiledBlockCallback for the specified block
byte[]	getBlockCallback19Offline(String method, String file, int line, String classPath) Get a CompiledBlockCallback for the specified block, returning the bytes but not loading the class.
byte[]	getBlockCallbackOffline(String method, String file, int line, String classPath) Get a CompiledBlockCallback for the specified block, returning the bytes but not loading the class.
abstract DynamicMethod	getCompiledMethod(RubyModule implementationClass, String rubyName, String javaName, Arity arity, Visibility visibility, StaticScope scope, Object scriptObject, CallConfiguration callConfig, ISourcePosition position, String parameterDesc) Get a new method handle based on the target JRuby-compiled method.
abstract DynamicMethod	getCompiledMethodLazily(RubyModule implementationClass, String rubyName, String javaName, Arity arity, Visibility visibility, StaticScope scope, Object scriptObject, CallConfiguration callConfig, ISourcePosition position, String parameterDesc) Like getCompiledMethod, but postpones any heavy lifting involved in creating the method until first invocation.
byte[]	getCompiledMethodOffline(String rubyName, String javaName, String classPath, String invokerPath, Arity arity, StaticScope scope, CallConfiguration callConfig, String filename, int line) Like getCompiledMethod, but produces the actual bytes for the compiled method handle rather than loading and constructing it.

Methods inherited from class java.lang.Object

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

Field Detail

COMPILED_METHOD_PARAMS

public static final Class[] COMPILED_METHOD_PARAMS

A Class[] representing the signature of compiled Ruby method.

CAN_LOAD_BYTECODE

public static final boolean CAN_LOAD_BYTECODE

A test to see if we can load bytecode dynamically, so we know whether InvocationMethodFactory will work.

Constructor Detail

MethodFactory

public MethodFactory()

Method Detail

createFactory

public static MethodFactory createFactory(ClassLoader classLoader)

Based on optional properties, create a new MethodFactory. By default, this will create a code-generation-based InvocationMethodFactory. If security restricts code generation, ReflectionMethodFactory will be used. If we are dumping class definitions, DumpingInvocationMethodFactory will be used. See MethodFactory's static initializer for more details.

Parameters:

classLoader - The classloader to use for searching for and dynamically loading code.

Returns:

A new MethodFactory.

getCompiledMethod

public abstract DynamicMethod getCompiledMethod(RubyModule implementationClass,
                              String rubyName,
                              String javaName,
                              Arity arity,
                              Visibility visibility,
                              StaticScope scope,
                              Object scriptObject,
                              CallConfiguration callConfig,
                              ISourcePosition position,
                              String parameterDesc)

Get a new method handle based on the target JRuby-compiled method. Because compiled Ruby methods have additional requirements and characteristics not typically found in Java-based methods, this is provided as a separate way to define such method handles.

Parameters:

implementationClass - The class to which the method will be bound.

rubyName - The Ruby method name to which the method will bind

javaName - The name of the method

arity - The Arity of the method

visibility - The method's visibility on the target type.

scope - The methods static scoping information.

scriptObject - An instace of the target compiled method class.

callConfig - The call configuration to use for this method.

position - The position to use when generating traceable handles.

Returns:

A new method handle for the target compiled method.

getCompiledMethodOffline

public byte[] getCompiledMethodOffline(String rubyName,
                              String javaName,
                              String classPath,
                              String invokerPath,
                              Arity arity,
                              StaticScope scope,
                              CallConfiguration callConfig,
                              String filename,
                              int line)

Like getCompiledMethod, but produces the actual bytes for the compiled method handle rather than loading and constructing it. This can be used to generate all the handles ahead of time, as when doing a full system precompile.

Parameters:

rubyName - The Ruby method name to which the method will bind

javaName - The name of the method

classPath - The path-like (with / instead of .) name of the class

invokerPath - The path-line name of the invoker to generate

arity - The Arity of the method

scope - The methods static scoping information.

callConfig - The call configuration to use for this method.

position - The position to use when generating traceable handles.

Returns:

getCompiledMethodLazily

public abstract DynamicMethod getCompiledMethodLazily(RubyModule implementationClass,
                                    String rubyName,
                                    String javaName,
                                    Arity arity,
                                    Visibility visibility,
                                    StaticScope scope,
                                    Object scriptObject,
                                    CallConfiguration callConfig,
                                    ISourcePosition position,
                                    String parameterDesc)

Like getCompiledMethod, but postpones any heavy lifting involved in creating the method until first invocation. This helps reduce the cost of starting up AOT-compiled code, by spreading out the heavy lifting across the run rather than causing all method handles to be immediately instantiated.

Parameters:

implementationClass - The class to which the method will be bound.

rubyName - The Ruby method name to which the method will bind

javaName - The name of the method

arity - The Arity of the method

visibility - The method's visibility on the target type.

scope - The methods static scoping information.

scriptObject - An instace of the target compiled method class.

callConfig - The call configuration to use for this method.

Returns:

A new method handle for the target compiled method.

getAnnotatedMethod

public abstract DynamicMethod getAnnotatedMethod(RubyModule implementationClass,
                               List<JavaMethodDescriptor> desc)

Based on a list of annotated Java methods, generate a method handle using the annotation and the target signatures. The annotation and signatures will be used to dynamically generate the appropriate call logic for the handle. This differs from the single-method version in that it will dispatch multiple specific-arity paths to different target methods.

Parameters:

implementationClass - The target class or module on which the method will be bound.

descs - A list of JavaMethodDescriptors describing the target methods

Returns:

A method handle for the target object.

getAnnotatedMethod

public abstract DynamicMethod getAnnotatedMethod(RubyModule implementationClass,
                               JavaMethodDescriptor desc)

Based on an annotated Java method object, generate a method handle using the annotation and the target signature. The annotation and signature will be used to dynamically generate the appropriate call logic for the handle.

Parameters:

implementationClass - The target class or module on which the method will be bound.

desc - A JavaMethodDescriptor describing the target method

Returns:

A method handle for the target object.

getBlockCallback

public abstract CompiledBlockCallback getBlockCallback(String method,
                                     String file,
                                     int line,
                                     Object scriptObject)

Get a CompiledBlockCallback for the specified block

Parameters:

method - The name of the method

scriptObject - The object in which the method can be found

Returns:

A new CompiledBlockCallback for the method

getBlockCallback19

public abstract CompiledBlockCallback19 getBlockCallback19(String method,
                                         String file,
                                         int line,
                                         Object scriptObject)

Get a CompiledBlockCallback for the specified block

Parameters:

method - The name of the method

scriptObject - The object in which the method can be found

Returns:

A new CompiledBlockCallback for the method

getBlockCallbackOffline

public byte[] getBlockCallbackOffline(String method,
                             String file,
                             int line,
                             String classPath)

Get a CompiledBlockCallback for the specified block, returning the bytes but not loading the class. This is used for offline generation of the callback class file.

Parameters:

method - The name of the method

classPath - The /-based name of the class containing the method

Returns:

The bytes of the class

getBlockCallback19Offline

public byte[] getBlockCallback19Offline(String method,
                               String file,
                               int line,
                               String classPath)

Get a CompiledBlockCallback for the specified block, returning the bytes but not loading the class. This is used for offline generation of the callback class file. This version generates a 1.9-compatible callback.

Parameters:

method - The name of the method

classPath - The /-based name of the class containing the method

Returns:

The bytes of the class