RuntimeExecutor class abstract interface

Defines an interface for executing runtime operations in a Dart environment, providing a high-level abstraction for dynamic object creation, method invocation, and field manipulation.

RuntimeExecutor is designed for scenarios where compile-time type knowledge is insufficient or unavailable, such as:

  • Dependency injection frameworks that dynamically instantiate classes.
  • Serialization/deserialization engines that read and write object state generically.
  • Plugin systems, code generators, or runtime reflection frameworks like Jetleaf, where type information and behavior must be resolved dynamically.

This interface allows implementers to provide a uniform mechanism for:

  1. Dynamic instantiation: Create new objects, including those with named constructors, without static type references.
  2. Dynamic method invocation: Call methods on instances at runtime, supplying positional and named arguments, with proper exception handling if a method cannot be resolved.
  3. Dynamic field access: Read and write instance fields dynamically, supporting both public and internal fields if the implementation allows.

The interface ensures that all operations can throw descriptive, domain-specific exceptions (e.g., ConstructorNotFoundException, MethodNotFoundException, FieldAccessException, FieldMutationException) to clearly signal runtime failures.

Key Design Principles:

  • Type safety when possible: Returns typed results (T in newInstance) while allowing dynamic invocation where needed.
  • Consistency across Dart platforms: Works on Dart VM, Flutter, or server environments depending on implementation strategy (reflection, mirrors, or generated code).
  • Extensibility: Can be extended to support advanced runtime scenarios, such as caching constructors/methods or enforcing runtime constraints.

Example usage:

final executor = MyRuntimeExecutor();

// Create a new instance dynamically
var instance = executor.newInstance<MyClass>('namedConstructor', args: [42], namedArgs: {'flag': true});

// Invoke a method dynamically
var result = executor.invokeMethod(instance, 'compute', args: [10]);

// Get a field value
var age = executor.getValue(instance, 'age');

// Set a field value
executor.setValue(instance, 'age', 30);

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

getValue<T>(T instance, String name) → Object?
Retrieves the value of a field from the specified instance.
invokeMethod<T>(T instance, String method, ExecutableArgument argument) → Object?
Invokes a method on a given object instance at runtime.
newInstance<T>(String name, ExecutableArgument argument, ConstructorDeclaration constructor, [Type? returnType]) → T
Dynamically creates a new instance of type T using the specified constructor.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
setValue<T>(T instance, String name, Object? value) → void
Sets the value of a field on the specified instance at runtime.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited