me.lucko.helper.metadata

Interface MetadataMap

public interface MetadataMap

A map which holds MetadataKeys, and maps them to persistent or transient (expiring / weak) values. Transient values will only be removed during map maintenance, which occurs during a housekeeping task running every minute. Method signatures for the has(MetadataKey) and equivalent remain accurate though.

See Also:

TransientValue

Method Summary

Modifier and Type	Method and Description
com.google.common.collect.ImmutableMap<MetadataKey<?>,Object>	asMap() Returns an immutable view of the backing map
void	cleanup() Removes expired TransientValues from this map.
void	clear() Clears the map
static MetadataMap	create()
<T> void	forcePut(MetadataKey<T> key, T value) Adds a metadata key and corresponding value into this map, removing any previous value if present.
<T> void	forcePut(MetadataKey<T> key, TransientValue<T> value) Adds a metadata key and corresponding value into this map, removing any previous value if present.
<T> Optional<T>	get(MetadataKey<T> key) Gets an optional value for the given key.
<T> T	getOrDefault(MetadataKey<T> key, T def) Gets a value for the given key, or returns the default if one isn't present.
<T> T	getOrNull(MetadataKey<T> key) Gets a value for the given key, or null if one isn't present.
<T> T	getOrPut(MetadataKey<T> key, Supplier<? extends T> def) Gets a value for the given key, or puts and returns the default if one isn't present.
<T> T	getOrPutExpiring(MetadataKey<T> key, Supplier<? extends TransientValue<T>> def) Gets a value for the given key, or puts and returns the default if one isn't present.
boolean	has(MetadataKey<?> key) Returns if this map contains the given key, and the types of each key match.
<T> boolean	ifPresent(MetadataKey<T> key, Consumer<? super T> action) Attempts to get a value for the given key, and applies the action is present.
boolean	isEmpty() Returns if the map is empty
<T> void	put(MetadataKey<T> key, T value) Adds a metadata key and corresponding value into this map, removing any previous value if present.
<T> void	put(MetadataKey<T> key, TransientValue<T> value) Adds a metadata key and corresponding value into this map, removing any previous value if present.
<T> boolean	putIfAbsent(MetadataKey<T> key, T value) Adds a metadata key and corresponding value into this map, only if an existing key is not present.
<T> boolean	putIfAbsent(MetadataKey<T> key, TransientValue<T> value) Adds a metadata key and corresponding value into this map, only if an existing key is not present.
boolean	remove(MetadataKey<?> key) Removes the given key from this map

Method Detail

create

@Nonnull
static MetadataMap create()

put

<T> void put(@Nonnull
             MetadataKey<T> key,
             @Nonnull
             T value)

Adds a metadata key and corresponding value into this map, removing any previous value if present. If a MetadataKey with the same id is already contained within this map, a ClassCastException will be thrown if they do not share the same type, and the existing value will remain.

Type Parameters:

T - the value type

Parameters:

key - the key to put

value - the value to map against (non null)

Throws:

ClassCastException - if any existing key with the same id has a differing type to the key being add

put

<T> void put(@Nonnull
             MetadataKey<T> key,
             @Nonnull
             TransientValue<T> value)

Adds a metadata key and corresponding value into this map, removing any previous value if present. If a MetadataKey with the same id is already contained within this map, a ClassCastException will be thrown if they do not share the same type, and the existing value will remain.

Type Parameters:

T - the value type

Parameters:

key - the key to put

value - the value to map against (non null)

Throws:

ClassCastException - if any existing key with the same id has a differing type to the key being add

forcePut

<T> void forcePut(@Nonnull
                  MetadataKey<T> key,
                  @Nonnull
                  T value)

Adds a metadata key and corresponding value into this map, removing any previous value if present. Unlike put(MetadataKey, Object), the existing value if present does not need to have the same type.

Type Parameters:

T - the value type

Parameters:

key - the key to put

value - the value to map against (non null)

forcePut

<T> void forcePut(@Nonnull
                  MetadataKey<T> key,
                  @Nonnull
                  TransientValue<T> value)

Adds a metadata key and corresponding value into this map, removing any previous value if present. Unlike put(MetadataKey, Object), the existing value if present does not need to have the same type.

Type Parameters:

T - the value type

Parameters:

key - the key to put

value - the value to map against (non null)

putIfAbsent

<T> boolean putIfAbsent(@Nonnull
                        MetadataKey<T> key,
                        @Nonnull
                        T value)

Adds a metadata key and corresponding value into this map, only if an existing key is not present.

Type Parameters:

T - the value type

Parameters:

key - the key to put

value - the value to map against (non null)

Returns:

true if there wasn't an existing key, and the key was added

putIfAbsent

<T> boolean putIfAbsent(@Nonnull
                        MetadataKey<T> key,
                        @Nonnull
                        TransientValue<T> value)

Adds a metadata key and corresponding value into this map, only if an existing key is not present.

Type Parameters:

T - the value type

Parameters:

key - the key to put

value - the value to map against (non null)

Returns:

true if there wasn't an existing key, and the key was added

get

@Nonnull
<T> Optional<T> get(@Nonnull
                             MetadataKey<T> key)

Gets an optional value for the given key.

Type Parameters:

T - the value type

Parameters:

key - the metadata key to get

Returns:

an optional containing the value

Throws:

ClassCastException - if there is a key held in the map with the same id but differing type to the given key.

ifPresent

<T> boolean ifPresent(@Nonnull
                      MetadataKey<T> key,
                      @Nonnull
                      Consumer<? super T> action)

Attempts to get a value for the given key, and applies the action is present.

Type Parameters:

T - the value type

Parameters:

key - the metadata key to lookup

action - the action to apply

Returns:

true if the action was applied

Throws:

ClassCastException - if there is a key held in the map with the same id but differing type to the given key.

getOrNull

@Nullable
<T> T getOrNull(@Nonnull
                          MetadataKey<T> key)

Gets a value for the given key, or null if one isn't present.

Type Parameters:

T - the value type

Parameters:

key - the metadata key to get

Returns:

the value, or null if no key is present.

Throws:

ClassCastException - if there is a key held in the map with the same id but differing type to the given key.

getOrDefault

@Nonnull
<T> T getOrDefault(@Nonnull
                            MetadataKey<T> key,
                            @Nullable
                            T def)

Gets a value for the given key, or returns the default if one isn't present.

Type Parameters:

T - the value type

Parameters:

key - the metadata key to get

def - the default value

Returns:

the value, or the default if no key is present.

Throws:

ClassCastException - if there is a key held in the map with the same id but differing type to the given key.

getOrPut

@Nonnull
<T> T getOrPut(@Nonnull
                        MetadataKey<T> key,
                        @Nonnull
                        Supplier<? extends T> def)

Gets a value for the given key, or puts and returns the default if one isn't present.

Type Parameters:

T - the value type

Parameters:

key - the metadata key to get

def - the default value

Returns:

the value, or the supplied value if no key is present.

Throws:

ClassCastException - if there is a key held in the map with the same id but differing type to the given key.

getOrPutExpiring

@Nonnull
<T> T getOrPutExpiring(@Nonnull
                                MetadataKey<T> key,
                                @Nonnull
                                Supplier<? extends TransientValue<T>> def)

Gets a value for the given key, or puts and returns the default if one isn't present.

Type Parameters:

T - the value type

Parameters:

key - the metadata key to get

def - the default value

Returns:

the value, or the supplied value if no key is present.

Throws:

ClassCastException - if there is a key held in the map with the same id but differing type to the given key.

has

boolean has(@Nonnull
            MetadataKey<?> key)

Returns if this map contains the given key, and the types of each key match.

Parameters:

key - the key to check for

Returns:

true if this map contains the key

remove

boolean remove(@Nonnull
               MetadataKey<?> key)

Removes the given key from this map

Parameters:

key - the key to remove

Returns:

true if a value was removed from the map

clear

void clear()

Clears the map

asMap

@Nonnull
com.google.common.collect.ImmutableMap<MetadataKey<?>,Object> asMap()

Returns an immutable view of the backing map

Returns:

an immutable view of the backing map

isEmpty

boolean isEmpty()

Returns if the map is empty

Returns:

true if the map is empty

cleanup

void cleanup()

Removes expired TransientValues from this map.

Note that this method does need to be explicitly called - as cleanup happens naturally over time.