Package org.robolectric.internal.bytecode

Interface ClassHandler

All Known Implementing Classes:

ShadowWrangler

public interface ClassHandler

This interface is used by Robolectric when instrumented classes are created and interacted with.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ClassHandler.Plan	An execution plan, which can be invoked to satisfy a requested method call.

Method Summary

Modifier and Type	Method	Description
void	classInitializing(Class clazz)	Called by Robolectric when an instrumented class is first loaded into a sandbox and is ready to be statically initialized.
MethodHandle	findShadowMethodHandle(Class<?> theClass, String name, MethodType methodType, boolean isStatic)	Called by Robolectric when an instrumented method is invoked.
MethodHandle	getShadowCreator(Class<?> theClass)	Called by Robolectric to determine how to create and initialize a shadow object when a new instance of an instrumented class has been instantiated.
Object	initializing(Object instance)	Called by Robolectric when a new instance of an instrumented class has been created and is ready to be initialized (but only on JVMs which don't support the invokedynamic instruction).
Object	intercept(String signature, Object instance, Object[] params, Class<?> theClass)	Called by Robolectric when an intercepted method is invoked.
ClassHandler.Plan	methodInvoked(String signature, boolean isStatic, Class<?> theClass)	Called by Robolectric when an instrumented method is invoked.
<T extends Throwable> T	stripStackTrace(T throwable)	Removes Robolectric noise from stack traces.

Method Detail

classInitializing

void classInitializing(Class clazz)

Called by Robolectric when an instrumented class is first loaded into a sandbox and is ready to be statically initialized.

This happens *in place of* any static initialization that may be performed by the class being loaded. The class will have a method named __staticInitializer__ which may be invoked to perform its normal initialization from <clinit>.

Parameters:

clazz - the class being loaded

initializing

Object initializing(Object instance)

Called by Robolectric when a new instance of an instrumented class has been created and is ready to be initialized (but only on JVMs which don't support the invokedynamic instruction).

This happens before constructor code executes on the new instance.

Implementations may return an object which will be associated with the new instance and passed along on future calls to methodInvoked(String, boolean, Class).

Parameters:

instance - the newly-created instance

Returns:

a data value to be associated with the new instance

See Also:

for newer JVMs

methodInvoked

ClassHandler.Plan methodInvoked(String signature,
                                boolean isStatic,
                                Class<?> theClass)

Called by Robolectric when an instrumented method is invoked.

Implementations should return an ClassHandler.Plan, which will be invoked with details about the current instance and parameters.

Implementations may also return null, in which case the method's original code will be executed.

Parameters:

signature - the JVM internal-format signature of the method being invoked (e.g. android/view/View/measure(II)V)

isStatic - true if the method is static

theClass - the class on which the method is declared

Returns:

an execution plan, or null if the original method's code should be executed

See Also:

for newer JVMs

getShadowCreator

MethodHandle getShadowCreator(Class<?> theClass)

Called by Robolectric to determine how to create and initialize a shadow object when a new instance of an instrumented class has been instantiated. (but only on JVMs which support the invokedynamic instruction).

The returned MethodHandle will be invoked after the new object has been allocated but before its constructor code is executed.

Note that this is not directly analogous to initializing(Object); the return value from this method will be cached and used again for other instantiations of instances of the same class.

Parameters:

theClass - the instrumented class

Returns:

a data value to be associated with the new instance

See Also:

for older JVMs, for invalidating the returned

findShadowMethodHandle

MethodHandle findShadowMethodHandle(Class<?> theClass,
                                    String name,
                                    MethodType methodType,
                                    boolean isStatic)
                             throws IllegalAccessException

Called by Robolectric when an instrumented method is invoked.

Implementations should return an MethodHandle, which will be invoked with details about the current instance and parameters.

Implementations may also return null, in which case the method's original code will be executed.

Parameters:

theClass - the class on which the method is declared

name - the name of the method

methodType - the method type

isStatic - true if the method is static

Returns:

a method handle to invoke, or null if the original method's code should be executed

Throws:

IllegalAccessException

See Also:

for older JVMs, for invalidating the returned

intercept

Object intercept(String signature,
                 Object instance,
                 Object[] params,
                 Class<?> theClass)
          throws Throwable

Called by Robolectric when an intercepted method is invoked.

Unlike instrumented methods, calls to intercepted methods are modified in place by Robolectric in the calling code. This is useful when the method about to be invoked doesn't exist in the current JVM (e.g. because of Android differences).

Parameters:

signature - the JVM internal-format signature of the method being invoked (e.g. android/view/View/measure(II)V)

instance - the instance on which the method would have been invoked

params - the parameters to the method

theClass - the class on which the method is declared

Returns:

the value to be returned

Throws:

Throwable - if anything bad happens

stripStackTrace

<T extends Throwable> T stripStackTrace(T throwable)

Removes Robolectric noise from stack traces.

Type Parameters:

T - the type of exception

Parameters:

throwable - the exception to be stripped

Returns:

the stripped stack trace