public abstract class Shape extends Object
DynamicObjectLibrary
to do a simple shape check to determine the contents of an object
and do fast, constant-time property accesses.
Shapes are shared between objects that assume the same shape if they follow the same shape transitions, like adding the same properties in the same order, starting from a common root shape. Shape transitions are automatically, weakly cached.
Dynamic objects start off with an initial shape that has no instance properties (but may have
constant properties that are stored in the shape). Initial shapes are created via
Shape.newBuilder()
.
DynamicObject
,
Shape.newBuilder()
,
Property
Modifier and Type | Class and Description |
---|---|
static class |
Shape.Builder
Builder class to construct initial
Shape instances. |
static class |
Shape.DerivedBuilder
Builder class to construct derived
Shape instances. |
Modifier | Constructor and Description |
---|---|
protected |
Shape()
Constructor for subclasses.
|
Modifier and Type | Method and Description |
---|---|
boolean |
allPropertiesMatch(Predicate<Property> predicate)
Tests if all properties in the shape match the provided predicate.
|
abstract boolean |
check(DynamicObject subject)
Checks whether the given object's shape is identical to this shape.
|
Object |
getDynamicType()
Get the shape's dynamic object type identifier.
|
int |
getFlags()
Returns the language-specific shape flags previously set using
DynamicObjectLibrary.setShapeFlags(DynamicObject, int) or
Shape.Builder.shapeFlags(int) . |
abstract List<Object> |
getKeyList()
Get a list of all property keys in insertion order.
|
abstract Iterable<Object> |
getKeys()
Get all property keys in insertion order.
|
abstract Property |
getLastProperty()
Get the last property.
|
Class<? extends DynamicObject> |
getLayoutClass()
Get the shape's layout class.
|
abstract Assumption |
getLeafAssumption()
Get an assumption that the shape is a leaf.
|
abstract Iterable<Property> |
getProperties()
An
Iterable over the shape's properties in insertion order. |
abstract Property |
getProperty(Object key)
Get a property entry by key.
|
Assumption |
getPropertyAssumption(Object key)
Gets a stable property assumption for the given property key.
|
abstract int |
getPropertyCount()
Returns the number of properties in this shape.
|
abstract List<Property> |
getPropertyList()
Get a list of all properties that this Shape stores.
|
abstract List<Property> |
getPropertyListInternal(boolean ascending)
Returns all (also hidden) property objects in this shape.
|
abstract Shape |
getRoot()
Get the root shape.
|
abstract Object |
getSharedData()
Get the shape's shared data.
|
abstract Assumption |
getValidAssumption()
Get an assumption that the shape is valid.
|
protected boolean |
hasInstanceProperties()
Returns
true if this shape has instance properties (i.e., stored in the object). |
abstract boolean |
hasProperty(Object key)
Check whether the shape has a property with the given key.
|
abstract boolean |
isLeaf()
Check whether this shape is a leaf in the transition graph, i.e.
|
boolean |
isShared()
Returns
true if this shape is marked as shared. |
abstract boolean |
isValid()
Check whether this shape is valid.
|
PropertyGetter |
makePropertyGetter(Object key)
Makes a property getter for this shape and the given property key, if it exists.
|
Shape |
makeSharedShape()
Make a shared variant of this shape, to allow safe usage of this object between threads.
|
static Shape.Builder |
newBuilder()
Creates a new initial shape builder.
|
static Shape.DerivedBuilder |
newBuilder(Shape baseShape)
Creates a new derived shape builder that allows changing a root shape's flags and dynamic
type and adding constant properties.
|
protected Shape |
setDynamicType(Object dynamicType)
Returns a copy of the shape, with the dynamic object type identifier set to
dynamicType . |
protected Shape |
setFlags(int newFlags)
Returns a copy of the shape, with the shape flags set to
newFlags . |
abstract Shape |
tryMerge(Shape other)
Try to merge two related shapes to a more general shape that has the same properties and can
store at least the values of both shapes.
|
public static Shape.Builder newBuilder()
public static Shape.DerivedBuilder newBuilder(Shape baseShape)
baseShape
- the shape to be modifiedShape.newBuilder()
public abstract Property getProperty(Object key)
key
- the identifier to look upnull
if not foundpublic abstract Iterable<Property> getProperties()
Iterable
over the shape's properties in insertion order.public abstract List<Property> getPropertyList()
HiddenKey
are not included.public abstract List<Property> getPropertyListInternal(boolean ascending)
ascending
- desired order (true
for insertion order, false
for reverse
insertion order)public abstract List<Object> getKeyList()
HiddenKey
are not included.public abstract Iterable<Object> getKeys()
public abstract Assumption getValidAssumption()
public abstract boolean isValid()
public abstract Assumption getLeafAssumption()
public abstract boolean isLeaf()
public abstract boolean hasProperty(Object key)
public abstract Property getLastProperty()
public int getFlags()
DynamicObjectLibrary.setShapeFlags(DynamicObject, int)
or
Shape.Builder.shapeFlags(int)
. If no shape flags were explicitly set, the default of
0 is returned.
These flags may be used to tag objects that possess characteristics that need to be queried
efficiently on fast and slow paths. For example, they can be used to mark objects as frozen.protected Shape setFlags(int newFlags)
newFlags
.newFlags
- the new shape flags; an int value in the range from 0 to 255 (inclusive)IllegalArgumentException
- if the flags value is not in the supported rangeShape.Builder.shapeFlags(int)
public abstract int getPropertyCount()
public Object getDynamicType()
protected Shape setDynamicType(Object dynamicType)
dynamicType
.dynamicType
- the new dynamic object type identifierNullPointerException
- if the argument is null.Shape.Builder.dynamicType(Object)
public abstract Shape getRoot()
public abstract boolean check(DynamicObject subject)
public Class<? extends DynamicObject> getLayoutClass()
Shape.Builder.layout(Class)
public abstract Object getSharedData()
Shape.Builder.sharedData(Object)
public abstract Shape tryMerge(Shape other)
public boolean isShared()
true
if this shape is marked as shared.public Shape makeSharedShape()
Note: Where possible, avoid using this method and use
DynamicObjectLibrary.markShared(DynamicObject)
instead.
Shape.isShared()
,
DynamicObjectLibrary.markShared(DynamicObject)
protected boolean hasInstanceProperties()
true
if this shape has instance properties (i.e., stored in the object).public Assumption getPropertyAssumption(Object key)
resetShape
.
Only applicable if property assumptions are enabled for this shape, otherwise always returns an invalid assumption.
key
- the property key of interestShape.Builder.propertyAssumptions(boolean)
public boolean allPropertiesMatch(Predicate<Property> predicate)
true
and does not evaluate the predicate.true
if the all properties match the predicate, else false
public PropertyGetter makePropertyGetter(Object key)
null
.
Note that the returned PropertyGetter
only accepts objects of this particular
Shape
.key
- the identifier to look upPropertyGetter
, or null
if the property was not found in this shape