Defines a contract for objects that expose a fully-qualified, stable name within the Jetleaf type and metadata system.
A qualified name uniquely identifies an entity across:
- Packages
- Libraries
- Runtime and build-time reflection contexts
Unlike simple names (e.g. User), a qualified name encodes ownership
and location, ensuring there are no collisions even when multiple entities
share the same simple identifier.
What a Qualified Name Represents
A qualified name typically combines:
- The package URI
- The library path
- The declared symbol name
Example format:
package:example/src/my_pod.dart.MyPod
This format is intentionally:
- Deterministic — same input yields the same identifier
- Stable — safe for caching, hashing, and persistence
- Globally unique within a Jetleaf runtime
Why This Matters
Qualified names are used as the primary identity key for:
- Class and declaration lookups
- Runtime ↔ source linking
- Cache keys and garbage collection
- Equality and hash code derivation
Many Jetleaf systems assume that:
a.getQualifiedName() == b.getQualifiedName()
implies the two objects represent the same semantic entity.
Example
class MyPod implements QualifiedName {
@override
String getQualifiedName() =>
'package:example/src/my_pod.dart.MyPod';
}
void main() {
final pod = MyPod();
print(pod.getQualifiedName());
// → package:example/src/my_pod.dart.MyPod
}
Equality Contract
Implementations mix in EqualsAndHashCode, meaning:
- Equality must be derived from the qualified name
- Hash codes must remain stable across executions
This allows qualified-name-based objects to be safely used in:
- Sets
- Maps
- Caches
Implementation Notes
Implementors should ensure:
- The returned value is never empty
- The value does not change over time
- The value is safe to use as a cache or lookup key
- Mixed-in types
- Implementers
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
-
equalizedProperties(
) → List< Object?> -
Mixin-style contract for value-based equality,
hashCode, andtoString.inherited -
getQualifiedName(
) → String - Returns the fully-qualified identifier for this object.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited