Data Holders

A data holder is an in-memory container for a player's snapshot data. Each adapter stores its data object in the holder using a Key. The holder acts as a type-safe key-value map.

DataHolder Interface

com.astralrealms.sync.model.holder.DataHolder

The base interface for all data holders. Extends Unique (requires a UUID uniqueId() getter).

Methods

`findByKey`

<T> Optional<T> findByKey(Key key)

Retrieves data stored under the given adapter key. The return type is unchecked — use only with the correct generic type for that key.

Key key = Key.key("myplugin", "stats");
Optional<MyStats> stats = holder.findByKey(key);

`findByClass`

<T> Optional<T> findByClass(Class<T> clazz)

Searches all stored data values and returns the first one that is an instance of clazz. Useful when you know the data type but not the key.

Optional<MyStats> stats = holder.findByClass(MyStats.class);

`getOrCreate`

<T> T getOrCreate(Key key, T defaultValue)

Returns the data stored under key, or stores and returns defaultValue if none exists. Useful for lazy initialization.

MyStats stats = holder.getOrCreate(
    Key.key("myplugin", "stats"),
    new MyStats()
);

`put`

<T> void put(Key key, T value)

Stores a data value under the given key. Overwrites any existing value.

`remove`

void remove(Key key)

Removes the data stored under key.

`data`

@Unmodifiable Map<Key, Object> data()

Returns an unmodifiable snapshot of all stored data. Useful for iteration.

`uniqueId`

UUID uniqueId()

Returns the player UUID this holder belongs to.

OnlineSaveUser

com.astralrealms.sync.model.holder.OnlineSaveUser

The concrete DataHolder implementation for online players. Returned by SyncAPI.findHolderById().

Extends OfflineSaveUser with two additional members:

Additional Methods

`player`

Player player()

Returns the Bukkit Player instance. Always non-null while the player is online.

`hasFinishedLoading`

boolean hasFinishedLoading()
void hasFinishedLoading(boolean value)

Indicates whether the load cycle has completed. AstralSync sets this to true just before firing PlayerDataLoadedEvent. Save operations are blocked until this returns true.

Always check this before reading data outside of event listeners:

SyncAPI.findHolderById(player.getUniqueId())
    .filter(h -> h instanceof OnlineSaveUser u && u.hasFinishedLoading())
    .ifPresent(holder -> {
        // safe to read
    });

OfflineSaveUser

com.astralrealms.sync.model.holder.OfflineSaveUser

The base implementation for player data holders. Used directly for offline player contexts (e.g. rollback operations). Uses ConcurrentHashMap for thread-safe access.

You will rarely interact with OfflineSaveUser directly — prefer OnlineSaveUser via SyncAPI.findHolderById() for online players.

24 April 2026