org.spongepowered.api.data.value.immutable

Interface ImmutableValueStore<I extends ImmutableValueStore<I,H>,H extends ValueContainer<?>>

Type Parameters:

I - The type of immutable value store, for self referencing

H - The type of ValueContainer to restrict accessing of values to

All Superinterfaces:

ValueContainer<I>

All Known Subinterfaces:

BlockSnapshot, BlockState, EntitySnapshot, FluidStackSnapshot, ImmutableDataHolder<T>, ItemStackSnapshot, LocatableBlock, LocatableSnapshot<T>

public interface ImmutableValueStore<I extends ImmutableValueStore<I,H>,H extends ValueContainer<?>>
extends ValueContainer<I>

Represents a ValueContainer that is immutable once created and contains a various bundle of ValueContainers of type declared by the extension that can be managed separately from this immutable value store.

Method Summary

Modifier and Type	Method and Description
<T extends H> Optional<T>	get(Class<T> containerClass) Gets the desired ValueContainer of type H if the ValueContainer is compatible.
List<H>	getContainers() Gets an copied collection of all known ValueContainers belonging to this ImmutableValueStore.
<T extends H> Optional<T>	getOrCreate(Class<T> containerClass) Gets the desired ValueContainer of type H if the ValueContainer is compatible.
I	merge(I that) Attempts to merge the ImmutableValues from this ImmutableValueStore and the given ImmutableValueStore to produce a new instance of the merged result.
I	merge(I that, MergeFunction function) Attempts to merge the ImmutableValues from this ImmutableValueStore and the given ImmutableValueStore to produce a new instance of the merged result.
boolean	supports(Class<? extends H> containerClass) Checks if the given Class of type ValueContainer is supported by this ImmutableValueStore.
<E> Optional<I>	transform(Key<? extends BaseValue<E>> key, Function<E,E> function) Applies a transformation on the provided BaseValue such that the return value of Function.apply(Object) will become the end resulting value set into the newly created ImmutableValueStore.
Optional<I>	with(BaseValue<?> value) Offers the given value as defined by the provided Key such that if the Key is supported, a new ImmutableValueStore is created.
Optional<I>	with(H valueContainer) Offers the given ValueContainer such that all of the available BaseValues from the given ValueContainer are offered to the newly created ImmutableValueStore.
Optional<I>	with(Iterable<H> valueContainers) Gets an altered copy of this ImmutableValueStore with the given DataManipulator modified data.
<E> Optional<I>	with(Key<? extends BaseValue<E>> key, E value) Creates a new ImmutableValueStore with the provided value by Key.
Optional<I>	without(Class<? extends H> containerClass) Gets an altered copy of this ImmutableValueStore without the given ValueContainer class.

Methods inherited from interface org.spongepowered.api.data.value.ValueContainer

copy, get, getKeys, getOrElse, getOrNull, getValue, getValues, require, supports, supports

Method Detail

get

<T extends H> Optional<T> get(Class<T> containerClass)

Gets the desired ValueContainer of type H if the ValueContainer is compatible. Since the return type is an Optional, a short way of checking compatibility and presence of the requested data is to mimic the following:

// MyCompositeValueStore extends CompositeValueStore<MyCompositeValueStore, DataManipulator<?>>
MyCompositeValueStore valueStore;
final Optional<DisplayNameData> displayOptional = valueStore.get(DisplayNameData.class);
if (displayOptional.isPresent()) {
// We know that we have a present DataManipulator and it's supported
System.out.println( displayOptional.get().displayName().get().toString());
}

This is the equivalent to performing the following:

MyCompositeValueStore valueStore;
if (valueStore.supports(DisplayNameData.class)) {
System.out.println(valueStore.getOrNull(DisplayNameData.class ).displayName().get().toString());
}

The advantage of this returning an Optional is that the ValueContainer may be unsupported, the required data missing and ignoring the possibility of nulls, it is a guarantee that if the Optional.isPresent() is true, the ValueContainer not only is supported, but there is already pre- existing data for the ValueContainer.

If it is necessary to ignore the Optional, Optional.orElse(Object) can be used to return a potentially null ValueContainer.

Type Parameters:

T - The type of ValueContainer

Parameters:

containerClass - The container class

Returns:

The value container, if available

getOrCreate

<T extends H> Optional<T> getOrCreate(Class<T> containerClass)

Gets the desired ValueContainer of type H if the ValueContainer is compatible. If insufficient data is available to provide a ValueContainer with all ImmutableValues preset, a new instance of the ValueContainer is returned with "default" values. Since the return type is an Optional, a short way of checking compatibility and presence of the requested data is to mimic the following:

// MyCompositeValueStore extends CompositeValueStore<MyCompositeValueStore, DataManipulator<?>>
MyCompositeValueStore valueStore;
final Optional<DisplayNameData> displayOptional = valueStore.getOrCreate(DisplayNameData.class);
if (displayOptional.isPresent()) {
// We know that we have a present DataManipulator and it's supported
System.out.println(displayOptional.get().displayName().get().toString());
}

This is the equivalent to performing the following:

MyCompositeValueStore valueStore;
if (valueStore.supports(DisplayNameData.class)) {
System.out.println(valueStore.getOrNull(DisplayNameData.class ).displayName().get().toString());
}

The advantage of this returning an Optional is that the ValueContainer may be unsupported, the required data missing and ignoring the possibility of nulls, it is a guarantee that if the Optional.isPresent() is true, the ValueContainer not only is supported, but there is already pre- existing data for the ValueContainer.

If it is necessary to ignore the Optional, Optional.orElse(Object) can be used to return a potentially null ValueContainer.

Type Parameters:

T - The type of ValueContainer

Parameters:

containerClass - The container class

Returns:

The value container, if compatible

supports

boolean supports(Class<? extends H> containerClass)

Checks if the given Class of type ValueContainer is supported by this ImmutableValueStore.

Parameters:

containerClass - The container class

Returns:

True if the class is supported

transform

<E> Optional<I> transform(Key<? extends BaseValue<E>> key,
                          Function<E,E> function)

Applies a transformation on the provided BaseValue such that the return value of Function.apply(Object) will become the end resulting value set into the newly created ImmutableValueStore.

Type Parameters:

E - The type of value

Parameters:

key - The key linked to

function - The function to manipulate the value

Returns:

The newly created immutable value store

with

<E> Optional<I> with(Key<? extends BaseValue<E>> key,
                     E value)

Creates a new ImmutableValueStore with the provided value by Key. If the key is supported by this value store, the returned value store will be present.

Type Parameters:

E - The type of value

Parameters:

key - The key to the value to set

value - The value to set

Returns:

The new immutable value store

with

Optional<I> with(BaseValue<?> value)

Offers the given value as defined by the provided Key such that if the Key is supported, a new ImmutableValueStore is created.

Parameters:

value - The value to set

Returns:

The new immutable value store

with

Optional<I> with(H valueContainer)

Offers the given ValueContainer such that all of the available BaseValues from the given ValueContainer are offered to the newly created ImmutableValueStore.

Parameters:

valueContainer - The value to set

Returns:

The transaction result

with

Optional<I> with(Iterable<H> valueContainers)

Gets an altered copy of this ImmutableValueStore with the given DataManipulator modified data. If the data is not compatible for any reason, Optional.empty() is returned.

This does not alter the current ImmutableValueStore.

Parameters:

valueContainers - The new manipulator containing data

Returns:

A new immutable value store with the given value holders

without

Optional<I> without(Class<? extends H> containerClass)

Gets an altered copy of this ImmutableValueStore without the given ValueContainer class. If the data represented by the manipulator can not exist without a "default state" of the ValueContainer, the ValueContainer is reset to the "default" state.

Parameters:

containerClass - The value holders to ignore

Returns:

A new immutable data holder without the given manipulator

merge

I merge(I that)

Attempts to merge the ImmutableValues from this ImmutableValueStore and the given ImmutableValueStore to produce a new instance of the merged result.

Parameters:

that - The other immutable value store to gather values from

Returns:

The new immutable value store instance

merge

I merge(I that,
        MergeFunction function)

Attempts to merge the ImmutableValues from this ImmutableValueStore and the given ImmutableValueStore to produce a new instance of the merged result. Any overlapping ValueContainers are merged through the MergeFunction.

Parameters:

that - The other immutable value store to gather values from

function - The function to resolve merge conflicts

Returns:

The new immutable value store instance

getContainers

List<H> getContainers()

Gets an copied collection of all known ValueContainers belonging to this ImmutableValueStore. An individual ValueContainer can be used for data processing for various purposes.

Returns:

A collection of copied ValueContainers originating from this value store