Bukkit/CraftBukkit — pull request #518 by rmichela (2011-10-26 06:45:23+00:00)
Title: Added a Metadata framework for Entities and Blocks

This metadata implementation has the following features:

1. All metadata is lazy. Metadata values are not actually computed
until another plugin requests them. Memory and CPU are conserved by not
computing and storing unnecessary metadata values.

2. All metadata is cached. Once a metadata value is computed its value
is cached in the metadata store to prevent further unnecessary
computation. An invalidation mechanism is provided to flush the cache
and force recompilation of metadata values.

3. All metadata is stored in basic data types. Convenience methods in
the MetadataValue class allow for the conversion of metadata data types
when possible. Restricting metadata to basic data types prevents the
accidental linking of large object graphs into metadata. Metadata is
persistent across the lifetime of the application and adding large
object graphs would damage garbage collector performance.

4. Metadata access is thread safe. Care has been taken to protect the
internal data structures and access them in a thread safe manner.

5. Metadata is exposed for all objects that descend from Entity and
Block. All Entity metadata is stored at the Server level and all Block
metadata is stored at the World level.

6. Metadata is NOT keyed on references to original objects - instead
metadata is keyed off of unique fields within those objects. Doing this
allows metadata to exist for blocks that are in chunks not currently in
memory. Additionally, Player objects are keyed off of player name so
that Player metadata remains consistent between logins.

7. Metadata convenience methods have been added to all Entities,
Blocks, and BlockStates allowing direct access to an individual
instance's metadata.