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:
- Dynamic instantiation: Create new objects, including those with named constructors, without static type references.
- Dynamic method invocation: Call methods on instances at runtime, supplying positional and named arguments, with proper exception handling if a method cannot be resolved.
- 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 (
TinnewInstance) 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
Tusing 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