org.spongepowered.api.world

Class Location<E extends Extent>

java.lang.Object

org.spongepowered.api.world.Location<E>

Type Parameters:

E - The type of extent containing this location

All Implemented Interfaces:

DataHolder, DataSerializable, PropertyHolder, CompositeValueStore<DataHolder,DataManipulator<?,?>>, ValueContainer<DataHolder>

public final class Location<E extends Extent>
extends Object
implements DataHolder

A position within a particular Extent.

This class is primarily a helper class to represent a location in a particular Extent. The methods provided are proxy methods to ones on Extent.

Each instance can be used to either represent a block or a location on a continuous coordinate system. Internally, positions are stored using doubles. When a block-related method is used, the components of the position are each rounded to an integer.

Locations are immutable. Methods that change the properties of the location create a new instance.

Constructor Summary

Constructors

Constructor and Description
Location(E extent, double x, double y, double z) Create a new instance.
Location(E extent, int x, int y, int z) Create a new instance.
Location(E extent, com.flowpowered.math.vector.Vector3d position) Create a new instance.
Location(E extent, com.flowpowered.math.vector.Vector3i blockPosition) Create a new instance.

Method Summary

Modifier and Type	Method and Description
Location<E>	add(double x, double y, double z) Add vector components to the position on this instance, returning a new Location instance.
Location<E>	add(com.flowpowered.math.vector.Vector3d v) Add another Vector3d to the position on this instance, returning a new Location instance.
Location<E>	add(com.flowpowered.math.vector.Vector3i v) Add another Vector3i to the position on this instance, returning a new Location instance.
ScheduledBlockUpdate	addScheduledUpdate(int priority, int ticks) Adds a new ScheduledBlockUpdate to this block.
Location<E>	asHighestLocation() Gets the highest Location at this location.
Location<E>	copy() Creates a clone copy of this ValueContainer as a new ValueContainer such that all the BaseValues are safely duplicated to the new instance.
DataTransactionResult	copyFrom(DataHolder that) Performs an absolute copy of all Values and ValueContainers to this CompositeValueStore such that any overlapping Values are offered for replacement.
DataTransactionResult	copyFrom(DataHolder that, MergeFunction strategy) Performs an absolute copy of all Values and ValueContainers to this CompositeValueStore such that any overlapping Values are offered for replacement.
Entity	createEntity(EntityType type) Create an entity instance at the given position.
BlockSnapshot	createSnapshot() Gets a snapshot of this block at the current point in time.
boolean	equals(Object other)
<T extends DataManipulator<?,?>> Optional<T>	get(Class<T> containerClass) Gets the desired ValueContainer of type H if the ValueContainer is compatible.
<T> Optional<T>	get(Key<? extends BaseValue<T>> key) Attempts to get the underlying value backed by a BaseValue linked to the provided Key.
Collection<Property<?,?>>	getApplicableProperties() Gets an immutable collection of all known Propertys pertaining to this PropertyHolder.
BiomeType	getBiome() Gets the block at this location.
com.flowpowered.math.vector.Vector3i	getBiomePosition() Gets the underlying biome position.
BlockState	getBlock() Gets the BlockState for this position.
com.flowpowered.math.vector.Vector3i	getBlockPosition() Gets the underlying block position.
Location<E>	getBlockRelative(Direction direction) Gets the location next to this one in the given direction.
BlockType	getBlockType() Gets the base type of block.
int	getBlockX() Gets the floored X component of this instance's position.
int	getBlockY() Gets the floored Y component of this instance's position.
int	getBlockZ() Gets the floored Z component of this instance's position.
com.flowpowered.math.vector.Vector3i	getChunkPosition() Gets the underlying chunk position.
Collection<DataManipulator<?,?>>	getContainers() Gets an copied collection of all known ValueContainers belonging to this CompositeValueStore.
int	getContentVersion() Gets the content version of this DataSerializable.
E	getExtent() Gets the underlying extent.
Set<Key<?>>	getKeys() Gets all applicable Keys for this ValueContainer.
Optional<LocatableBlock>	getLocatableBlock() Gets a LocatableBlock if the parent Extent of this Location is a World.
<T extends DataManipulator<?,?>> Optional<T>	getOrCreate(Class<T> containerClass) Gets the desired ValueContainer of type H if the ValueContainer is compatible.
com.flowpowered.math.vector.Vector3d	getPosition() Gets the underlying position.
<T extends Property<?,?>> Optional<T>	getProperty(Class<T> propertyClass) Attempts to retrieve a specific Property type of this PropertyHolder.
Location<E>	getRelative(Direction direction) Gets the location next to this one in the given direction.
Collection<ScheduledBlockUpdate>	getScheduledUpdates() Gets a list of ScheduledBlockUpdates on this block.
Optional<TileEntity>	getTileEntity() Gets the associated TileEntity on this block.
<T,V extends BaseValue<T>> Optional<V>	getValue(Key<V> key) Gets the BaseValue for the given Key.
Set<ImmutableValue<?>>	getValues() Gets all applicable BaseValues associated with this ValueContainer.
double	getX() Gets the X component of this instance's position.
double	getY() Gets the Y component of this instance's position.
double	getZ() Gets the Z component of this instance's position.
boolean	hasBiome() Returns true if this location has a biome at its getBiomePosition().
boolean	hasBlock() Returns true if this location has a block at its getBlockPosition() ()}.
int	hashCode()
boolean	hasTileEntity() Checks for whether the block at this position contains tile entity data.
boolean	inExtent(Extent extent) Returns true if this location is in the given extent.
boolean	isAvailable() Gets if the Extent this location refers to is still loaded and available.
<T> T	map(BiFunction<E,com.flowpowered.math.vector.Vector3d,T> mapper) Calls the mapper function on the extent and position.
<T> T	mapBiome(BiFunction<E,com.flowpowered.math.vector.Vector3i,T> mapper) Calls the mapper function on the extent and biome position.
<T> T	mapBlock(BiFunction<E,com.flowpowered.math.vector.Vector3i,T> mapper) Calls the mapper function on the extent and block position.
<T> T	mapChunk(BiFunction<E,com.flowpowered.math.vector.Vector3i,T> mapper) Calls the mapper function on the extent and chunk position.
<T> DataTransactionResult	offer(BaseValue<T> value) Offers the given BaseValue as defined by the provided Key such that a DataTransactionResult is returned for any successful, rejected, and replaced BaseValues from this CompositeValueStore.
DataTransactionResult	offer(DataManipulator<?,?> valueContainer) Offers the given ValueContainer such that all of the available BaseValues from the given ValueContainer are offered to this CompositeValueStore.
DataTransactionResult	offer(DataManipulator<?,?> valueContainer, MergeFunction function) Offers the given ValueContainer such that all of the available BaseValues from the given ValueContainer are offered to this CompositeValueStore.
DataTransactionResult	offer(Iterable<DataManipulator<?,?>> valueHolders) Offers all provided ValueContainers to this CompositeValueStore much like CompositeValueStore.offer(ValueContainer) except all in a single batch.
DataTransactionResult	offer(Iterable<DataManipulator<?,?>> values, MergeFunction function) Offers all provided ValueContainers to this CompositeValueStore much like CompositeValueStore.offer(ValueContainer) except all in a single batch.
<T> DataTransactionResult	offer(Key<? extends BaseValue<T>> key, T value) Offers the given value as defined by the provided Key such that a DataTransactionResult is returned for any successful, rejected, and replaced BaseValues from this CompositeValueStore.
DataTransactionResult	remove(BaseValue<?> value) Attempts to remove the provided BaseValue.
DataTransactionResult	remove(Class<? extends DataManipulator<?,?>> containerClass) Attempts to remove all Values associated with the class of the provided ValueContainer class.
DataTransactionResult	remove(Key<?> key) Attempts to remove the data associated with the provided Key.
boolean	removeBlock() Remove the block at this position by replacing it with BlockTypes.AIR.
void	removeScheduledUpdate(ScheduledBlockUpdate update) Removes a ScheduledBlockUpdate from this block.
boolean	restoreSnapshot(BlockSnapshot snapshot, boolean force, BlockChangeFlag flag) Replace the block at this position with a copy of the given snapshot.
boolean	setBlock(BlockState state) Replace the block at this position with a new state.
boolean	setBlock(BlockState state, BlockChangeFlag flag) Replace the block at this position with a new state.
Location<E>	setBlockPosition(com.flowpowered.math.vector.Vector3i position) Create a new instance with a new block position.
boolean	setBlockType(BlockType type) Replace the block type at this position by a new type.
boolean	setBlockType(BlockType type, BlockChangeFlag flag) Replace the block type at this position by a new type.
Location<E>	setExtent(E extent) Create a new instance with a new extent.
Location<E>	setPosition(com.flowpowered.math.vector.Vector3d position) Create a new instance with a new position.
void	setRawData(DataView container) Attempts to set all data of this DataHolder according to the DataContainer's held information.
Collection<Entity>	spawnEntities(Iterable<? extends Entity> entities) Similar to spawnEntity(Entity) except where multiple entities can be attempted to be spawned with a customary Cause.
boolean	spawnEntity(Entity entity) Spawns an Entity using the already set properties (extent, position, rotation) and applicable DataManipulators with the specified Cause for spawning the entity.
Location<E>	sub(double x, double y, double z) Subtract vector components to the position on this instance, returning a new Location instance.
Location<E>	sub(com.flowpowered.math.vector.Vector3d v) Subtract another Vector3d to the position on this instance, returning a new Location instance.
Location<E>	sub(com.flowpowered.math.vector.Vector3i v) Subtract another Vector3i to the position on this instance, returning a new Location instance.
boolean	supports(Class<? extends DataManipulator<?,?>> holderClass) Checks if the given Class of type ValueContainer is supported by this CompositeValueStore.
boolean	supports(Key<?> key) Checks if the given Key is supported by this ValueContainer.
DataContainer	toContainer() Serializes this object into a comprehensible DataContainer.
String	toString()
<T> DataTransactionResult	transform(Key<? extends BaseValue<T>> key, Function<T,T> 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 this CompositeValueStore.
DataTransactionResult	undo(DataTransactionResult result) Attempts to "revert" a DataTransactionResult such that any of the DataTransactionResult.getReplacedData() are offered back, and any DataTransactionResult.getSuccessfulData() are removed if they were not the same types as any exising in the replaced values.
boolean	validateRawData(DataView container) Validates the container with known data required to set the raw data to this DataHolder.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.spongepowered.api.data.value.mutable.CompositeValueStore

require, tryOffer, tryOffer, tryOffer, tryOffer

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

getOrElse, getOrNull, require, supports

Constructor Detail

Location

public Location(E extent,
                com.flowpowered.math.vector.Vector3d position)

Create a new instance.

Parameters:

extent - The extent

position - The position

Location

public Location(E extent,
                double x,
                double y,
                double z)

Create a new instance.

Parameters:

extent - The extent

x - The X-axis position

y - The Y-axis position

z - The Z-axis position

Location

public Location(E extent,
                com.flowpowered.math.vector.Vector3i blockPosition)

Create a new instance.

Parameters:

extent - The extent

blockPosition - The position

Location

public Location(E extent,
                int x,
                int y,
                int z)

Create a new instance.

Parameters:

extent - The extent

x - The X-axis position

y - The Y-axis position

z - The Z-axis position

Method Detail

isAvailable

public boolean isAvailable()

Gets if the Extent this location refers to is still loaded and available.

Returns:

true if this extent is available.

getExtent

public E getExtent()

Gets the underlying extent.

If the referenced Extent has been unloaded, this will throw an exception.

Returns:

The extent, if available

Throws:

IllegalStateException - If the Extent has been unloaded and is no longer available.

getPosition

public com.flowpowered.math.vector.Vector3d getPosition()

Gets the underlying position.

Returns:

The underlying position

getBlockPosition

public com.flowpowered.math.vector.Vector3i getBlockPosition()

Gets the underlying block position.

Returns:

The underlying block position

getChunkPosition

public com.flowpowered.math.vector.Vector3i getChunkPosition()

Gets the underlying chunk position.

Returns:

The underlying chunk position

getBiomePosition

public com.flowpowered.math.vector.Vector3i getBiomePosition()

Gets the underlying biome position.

Returns:

The underlying biome position

getX

public double getX()

Gets the X component of this instance's position.

Returns:

The x component

getY

public double getY()

Gets the Y component of this instance's position.

Returns:

The y component

getZ

public double getZ()

Gets the Z component of this instance's position.

Returns:

The z component

getBlockX

public int getBlockX()

Gets the floored X component of this instance's position.

Returns:

The floored x component

getBlockY

public int getBlockY()

Gets the floored Y component of this instance's position.

Returns:

The floored y component

getBlockZ

public int getBlockZ()

Gets the floored Z component of this instance's position.

Returns:

The floored z component

inExtent

public boolean inExtent(Extent extent)

Returns true if this location is in the given extent. This is implemented as an Object.equals(Object) check.

Parameters:

extent - The extent to check

Returns:

Whether this location is in the extent

hasBiome

public boolean hasBiome()

Returns true if this location has a biome at its getBiomePosition().

Returns:

Whether or not there is a biome at this location.

hasBlock

public boolean hasBlock()

Returns true if this location has a block at its getBlockPosition() ()}.

Returns:

Whether or not there is a block at this location.

getLocatableBlock

public Optional<LocatableBlock> getLocatableBlock()

Gets a LocatableBlock if the parent Extent of this Location is a World.

Returns:

The locatable block of this location, if available

setExtent

public Location<E> setExtent(E extent)

Create a new instance with a new extent.

Parameters:

extent - The new extent

Returns:

A new instance

setPosition

public Location<E> setPosition(com.flowpowered.math.vector.Vector3d position)

Create a new instance with a new position.

Parameters:

position - The new position

Returns:

A new instance

setBlockPosition

public Location<E> setBlockPosition(com.flowpowered.math.vector.Vector3i position)

Create a new instance with a new block position.

Parameters:

position - The new position

Returns:

A new instance

sub

public Location<E> sub(com.flowpowered.math.vector.Vector3d v)

Subtract another Vector3d to the position on this instance, returning a new Location instance.

Parameters:

v - The vector to subtract

Returns:

A new instance

sub

public Location<E> sub(com.flowpowered.math.vector.Vector3i v)

Subtract another Vector3i to the position on this instance, returning a new Location instance.

Parameters:

v - The vector to subtract

Returns:

A new instance

sub

public Location<E> sub(double x,
                       double y,
                       double z)

Subtract vector components to the position on this instance, returning a new Location instance.

Parameters:

x - The x component

y - The y component

z - The z component

Returns:

A new instance

add

public Location<E> add(com.flowpowered.math.vector.Vector3d v)

Add another Vector3d to the position on this instance, returning a new Location instance.

Parameters:

v - The vector to add

Returns:

A new instance

add

public Location<E> add(com.flowpowered.math.vector.Vector3i v)

Add another Vector3i to the position on this instance, returning a new Location instance.

Parameters:

v - The vector to add

Returns:

A new instance

add

public Location<E> add(double x,
                       double y,
                       double z)

Add vector components to the position on this instance, returning a new Location instance.

Parameters:

x - The x component

y - The y component

z - The z component

Returns:

A new instance

map

public <T> T map(BiFunction<E,com.flowpowered.math.vector.Vector3d,T> mapper)

Calls the mapper function on the extent and position.

Type Parameters:

T - The return type of the mapper

Parameters:

mapper - The mapper

Returns:

The results of the mapping

mapBlock

public <T> T mapBlock(BiFunction<E,com.flowpowered.math.vector.Vector3i,T> mapper)

Calls the mapper function on the extent and block position.

Type Parameters:

T - The return type of the mapper

Parameters:

mapper - The mapper

Returns:

The results of the mapping

mapChunk

public <T> T mapChunk(BiFunction<E,com.flowpowered.math.vector.Vector3i,T> mapper)

Calls the mapper function on the extent and chunk position.

Type Parameters:

T - The return type of the mapper

Parameters:

mapper - The mapper

Returns:

The results of the mapping

mapBiome

public <T> T mapBiome(BiFunction<E,com.flowpowered.math.vector.Vector3i,T> mapper)

Calls the mapper function on the extent and biome position.

Type Parameters:

T - The return type of the mapper

Parameters:

mapper - The mapper

Returns:

The results of the mapping

getRelative

public Location<E> getRelative(Direction direction)

Gets the location next to this one in the given direction. Always moves by a unit amount, even diagonally.

Parameters:

direction - The direction to move in

Returns:

The location in that direction

getBlockRelative

public Location<E> getBlockRelative(Direction direction)

Gets the location next to this one in the given direction. Always moves by a block amount, even diagonally.

Direction.Division.SECONDARY_ORDINAL directions are not a valid argument. These will throw an exception.

Parameters:

direction - The direction to move in

Returns:

The location in that direction

Throws:

IllegalArgumentException - If the direction is a Direction.Division.SECONDARY_ORDINAL

getBiome

public BiomeType getBiome()

Gets the block at this location.

Returns:

The biome at this location

getBlockType

public BlockType getBlockType()

Gets the base type of block.

The type does not include block data such as the contents of inventories.

Returns:

The type of block

getBlock

public BlockState getBlock()

Gets the BlockState for this position.

Returns:

The block state

hasTileEntity

public boolean hasTileEntity()

Checks for whether the block at this position contains tile entity data.

Returns:

True if the block at this position has tile entity data, false otherwise

getTileEntity

public Optional<TileEntity> getTileEntity()

Gets the associated TileEntity on this block.

Returns:

The associated tile entity, if available

setBlock

public boolean setBlock(BlockState state)

Replace the block at this position with a new state.

This will remove any extended block data at the given position.

Parameters:

state - The new block state

Returns:

True if the block change was successful

setBlock

public boolean setBlock(BlockState state,
                        BlockChangeFlag flag)

Replace the block at this position with a new state.

This will remove any extended block data at the given position.

Parameters:

state - The new block state

flag - The various change flags controlling some interactions

Returns:

True if the block change was successful

setBlockType

public boolean setBlockType(BlockType type)

Replace the block type at this position by a new type.

This will remove any extended block data at the given position.

Parameters:

type - The new type

Returns:

True if the block change was successful

setBlockType

public boolean setBlockType(BlockType type,
                            BlockChangeFlag flag)

Replace the block type at this position by a new type.

This will remove any extended block data at the given position.

Parameters:

type - The new type

flag - The various change flags controlling some interactions

Returns:

True if the block change was successful

restoreSnapshot

public boolean restoreSnapshot(BlockSnapshot snapshot,
                               boolean force,
                               BlockChangeFlag flag)

Replace the block at this position with a copy of the given snapshot.

Changing the snapshot afterwards will not affect the block that has been placed at this location.

Parameters:

snapshot - The snapshot

force - If true, forces block state to be set even if the BlockType does not match the snapshot one.

flag - The various change flags controlling some interactions

Returns:

True if the snapshot restore was successful

removeBlock

public boolean removeBlock()

Remove the block at this position by replacing it with BlockTypes.AIR.

This will remove any extended block data at the given position.

Returns:

True if the block change was successful

createEntity

public Entity createEntity(EntityType type)

Create an entity instance at the given position.

Creating an entity does not spawn the entity into the world. An entity created means the entity can be spawned at the given location. If Optional.empty() was returned, the entity is not able to spawn at the given location. Furthermore, this allows for the Entity to be customized further prior to traditional "ticking" and processing by core systems.

Parameters:

type - The type

Returns:

An entity, if one was created

Throws:

IllegalArgumentException - If the position or entity type is not valid to create

IllegalStateException - If a constructor cannot be found

See Also:

EntityUniverse.createEntity(EntityType, Vector3d)

spawnEntity

public boolean spawnEntity(Entity entity)

Spawns an Entity using the already set properties (extent, position, rotation) and applicable DataManipulators with the specified Cause for spawning the entity.

Note that for the Cause to be useful in the expected SpawnEntityEvent, a SpawnType should be provided in the EventContext for other plugins to understand and have finer control over the event.

The requirements involve that all necessary setup of states and data is already preformed on the entity retrieved from the various EntityUniverse.createEntity(EntityType,Vector3d) methods. Calling this will make the now-spawned entity able to be processed by various systems.

If the entity was unable to spawn, the entity is not removed, but it should be taken note that there can be many reasons for a failure.

Parameters:

entity - The entity to spawn

Returns:

True if successful, false if not

See Also:

EntityUniverse.spawnEntity(Entity)

spawnEntities

public Collection<Entity> spawnEntities(Iterable<? extends Entity> entities)

Similar to spawnEntity(Entity) except where multiple entities can be attempted to be spawned with a customary Cause. The recommended use is to easily process the entity spawns without interference with the cause tracking system.

Parameters:

entities - The entities which spawned correctly, or empty if none

Returns:

True if any of the entities were successfully spawned

See Also:

EntityUniverse.spawnEntities(Iterable)

asHighestLocation

public Location<E> asHighestLocation()

Gets the highest Location at this location.

Returns:

The highest location at this location

See Also:

Extent.getHighestPositionAt(Vector3i)

remove

public DataTransactionResult remove(Class<? extends DataManipulator<?,?>> containerClass)

Description copied from interface: CompositeValueStore

Attempts to remove all Values associated with the class of the provided ValueContainer class. All values that were successfully removed will be provided in DataTransactionResult.getReplacedData(). If the data can not be removed, the result will be an expected DataTransactionResult.Type.FAILURE.

Specified by:

remove in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

containerClass - The container class

Returns:

The transaction result

remove

public DataTransactionResult remove(BaseValue<?> value)

Description copied from interface: CompositeValueStore

Attempts to remove the provided BaseValue. All values that were successfully removed will be provided in DataTransactionResult.getReplacedData(). If the data can not be removed, the result will be an expected DataTransactionResult.Type.FAILURE.

Specified by:

remove in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

value - The value to remove

Returns:

The transaction result

remove

public DataTransactionResult remove(Key<?> key)

Description copied from interface: CompositeValueStore

Attempts to remove the data associated with the provided Key. All values that were successfully removed will be provided in DataTransactionResult.getReplacedData(). If the data can not be removed, the result will be an expected DataTransactionResult.Type.FAILURE.

Specified by:

remove in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

key - The key of the data

Returns:

The transaction result

createSnapshot

public BlockSnapshot createSnapshot()

Gets a snapshot of this block at the current point in time.

A snapshot is disconnected from the Extent that it was taken from so changes to the original block do not affect the snapshot.

Returns:

A snapshot

getScheduledUpdates

public Collection<ScheduledBlockUpdate> getScheduledUpdates()

Gets a list of ScheduledBlockUpdates on this block.

Returns:

A list of ScheduledBlockUpdates on this block

addScheduledUpdate

public ScheduledBlockUpdate addScheduledUpdate(int priority,
                                               int ticks)

Adds a new ScheduledBlockUpdate to this block.

Parameters:

priority - The priority of the scheduled update

ticks - The ticks until the scheduled update should be processed

Returns:

The newly created scheduled update

removeScheduledUpdate

public void removeScheduledUpdate(ScheduledBlockUpdate update)

Removes a ScheduledBlockUpdate from this block.

Parameters:

update - The ScheduledBlockUpdate to remove

getProperty

public <T extends Property<?,?>> Optional<T> getProperty(Class<T> propertyClass)

Description copied from interface: PropertyHolder

Attempts to retrieve a specific Property type of this PropertyHolder. If the property is not applicable, Optional.empty() is returned.

properties can define various immutable information about a PropertyHolder that is dependent on the instance of the holder. As properties cannot be changed, the PropertyHolder can not change the information about its own properties either.

Specified by:

getProperty in interface PropertyHolder

Type Parameters:

T - The type of property

Parameters:

propertyClass - The property class

Returns:

The property, if available

getApplicableProperties

public Collection<Property<?,?>> getApplicableProperties()

Description copied from interface: PropertyHolder

Gets an immutable collection of all known Propertys pertaining to this PropertyHolder.

properties can not be changed such that the property is attached to the instance of the residing PropertyHolder.

Specified by:

getApplicableProperties in interface PropertyHolder

Returns:

An immutable collection of all known properties

validateRawData

public boolean validateRawData(DataView container)

Description copied from interface: DataHolder

Validates the container with known data required to set the raw data to this DataHolder. If the container is incomplete or contains invalid data, false is returned.

This validation should be checked prior to calling DataHolder.setRawData(DataView) to avoid exceptions.

Specified by:

validateRawData in interface DataHolder

Parameters:

container - The raw data to validate

Returns:

True if the data is valid

setRawData

public void setRawData(DataView container)
                throws InvalidDataException

Description copied from interface: DataHolder

Attempts to set all data of this DataHolder according to the DataContainer's held information. Using this to modify known DataManipulator is unsupported and if the data is invalid, an InvalidDataException is thrown.

This setter is used to provide setting custom data that is not represented by the Data API, including forge mods and other unknown data. Attempts at validating known DataManipulators contained in the data container are made with the assumption that all necessary data exists.

Specified by:

setRawData in interface DataHolder

Parameters:

container - A container containing all raw data to set on this data holder

Throws:

InvalidDataException - If the container is missing or has invalid data that this holder will refuse

getContentVersion

public int getContentVersion()

Description copied from interface: DataSerializable

Gets the content version of this DataSerializable. The version may differ between instances of plugins and implementations such that the DataView from DataSerializable.toContainer() may include different information, or remove other information as they are no longer deemed necessary. The version goes hand in hand with DataContentUpdater as it is required when there exists any DataView of this DataSerializable with an "older" version.

Specified by:

getContentVersion in interface DataSerializable

Returns:

The version of the content being serialized

toContainer

public DataContainer toContainer()

Description copied from interface: DataSerializable

Serializes this object into a comprehensible DataContainer.

Specified by:

toContainer in interface DataSerializable

Returns:

A newly created DataContainer

get

public <T extends DataManipulator<?,?>> Optional<T> get(Class<T> containerClass)

Description copied from interface: CompositeValueStore

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.

Specified by:

get in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Type Parameters:

T - The type of ValueContainer

Parameters:

containerClass - The container class

Returns:

The value container, if available

get

public <T> Optional<T> get(Key<? extends BaseValue<T>> key)

Description copied from interface: ValueContainer

Attempts to get the underlying value backed by a BaseValue linked to the provided Key. If the Key is not supported, Optional.empty() is returned. It is important to check for support of a Key by either calling ValueContainer.supports(BaseValue) or ValueContainer.supports(Key).

Specified by:

get in interface ValueContainer<DataHolder>

Type Parameters:

T - The type of value

Parameters:

key - The key linking the

Returns:

The value, if available

getOrCreate

public <T extends DataManipulator<?,?>> Optional<T> getOrCreate(Class<T> containerClass)

Description copied from interface: CompositeValueStore

Gets the desired ValueContainer of type H if the ValueContainer is compatible. If insufficient data is available to provide a ValueContainer with all Values 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.get(DisplayNameData.class ).get().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 some default values can be generated to create the desired ValueContainer.

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

Specified by:

getOrCreate in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Type Parameters:

T - The type of ValueContainer

Parameters:

containerClass - The container class

Returns:

The value container, if compatible

offer

public <T> DataTransactionResult offer(Key<? extends BaseValue<T>> key,
                                       T value)

Description copied from interface: CompositeValueStore

Offers the given value as defined by the provided Key such that a DataTransactionResult is returned for any successful, rejected, and replaced BaseValues from this CompositeValueStore.

Specified by:

offer in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Type Parameters:

T - The type of value

Parameters:

key - The key to the value to set

value - The value to set

Returns:

The transaction result

offer

public DataTransactionResult offer(Iterable<DataManipulator<?,?>> valueHolders)

Description copied from interface: CompositeValueStore

Offers all provided ValueContainers to this CompositeValueStore much like CompositeValueStore.offer(ValueContainer) except all in a single batch. The end result of the values successfully offered, rejected, and replaced are stored in the returned DataTransactionResult.

Specified by:

offer in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

valueHolders - The values to set

Returns:

The transaction result

offer

public DataTransactionResult offer(Iterable<DataManipulator<?,?>> values,
                                   MergeFunction function)

Description copied from interface: CompositeValueStore

Offers all provided ValueContainers to this CompositeValueStore much like CompositeValueStore.offer(ValueContainer) except all in a single batch. The end result of the values successfully offered, rejected, and replaced are stored in the returned DataTransactionResult. Any merge conflicts are resolved through the MergeFunction.

Specified by:

offer in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

values - The values to set

function - The function to resolve the values

Returns:

The transaction result

offer

public <T> DataTransactionResult offer(BaseValue<T> value)

Description copied from interface: CompositeValueStore

Offers the given BaseValue as defined by the provided Key such that a DataTransactionResult is returned for any successful, rejected, and replaced BaseValues from this CompositeValueStore.

Specified by:

offer in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Type Parameters:

T - The type of the element wrapped by the value

Parameters:

value - The value to set

Returns:

The transaction result

offer

public DataTransactionResult offer(DataManipulator<?,?> valueContainer)

Description copied from interface: CompositeValueStore

Offers the given ValueContainer such that all of the available BaseValues from the given ValueContainer are offered to this CompositeValueStore. The end result of the values successfully offered, rejected, and replaced are stored in the returned DataTransactionResult.

Specified by:

offer in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

valueContainer - The value to set

Returns:

The transaction result

offer

public DataTransactionResult offer(DataManipulator<?,?> valueContainer,
                                   MergeFunction function)

Description copied from interface: CompositeValueStore

Offers the given ValueContainer such that all of the available BaseValues from the given ValueContainer are offered to this CompositeValueStore. The end result of the values successfully offered, rejected, and replaced are stored in the returned DataTransactionResult. Any overlaps of data are merged via the MergeFunction.

Specified by:

offer in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

valueContainer - The value to set

function - The merge function

Returns:

The transaction result

undo

public DataTransactionResult undo(DataTransactionResult result)

Description copied from interface: CompositeValueStore

Attempts to "revert" a DataTransactionResult such that any of the DataTransactionResult.getReplacedData() are offered back, and any DataTransactionResult.getSuccessfulData() are removed if they were not the same types as any exising in the replaced values.

Specified by:

undo in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

result - The result to undo

Returns:

The result of the undo

supports

public boolean supports(Class<? extends DataManipulator<?,?>> holderClass)

Description copied from interface: CompositeValueStore

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

Specified by:

supports in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

holderClass - The container class

Returns:

True if the class is supported

supports

public boolean supports(Key<?> key)

Description copied from interface: ValueContainer

Checks if the given Key is supported by this ValueContainer.

Specified by:

supports in interface ValueContainer<DataHolder>

Parameters:

key - The key to check

Returns:

True if the key and value backed by the key is supported

transform

public <T> DataTransactionResult transform(Key<? extends BaseValue<T>> key,
                                           Function<T,T> function)

Description copied from interface: CompositeValueStore

Applies a transformation on the provided BaseValue such that the return value of Function.apply(Object) will become the end resulting value set into this CompositeValueStore. It is not necessary that the input is actually present, in which case the Keyed data is compatible, but not necessarily present. Writing a Function to properly handle the potential for a null input is required for this method to execute without exception.

Specified by:

transform in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Type Parameters:

T - The type of value

Parameters:

key - The key linked to

function - The function to manipulate the value

Returns:

The end resulting value

copyFrom

public DataTransactionResult copyFrom(DataHolder that)

Description copied from interface: CompositeValueStore

Performs an absolute copy of all Values and ValueContainers to this CompositeValueStore such that any overlapping Values are offered for replacement. The result is provided as a DataTransactionResult.

Specified by:

copyFrom in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

that - The other CompositeValueStore to copy values from

Returns:

The transaction result

copyFrom

public DataTransactionResult copyFrom(DataHolder that,
                                      MergeFunction strategy)

Description copied from interface: CompositeValueStore

Performs an absolute copy of all Values and ValueContainers to this CompositeValueStore such that any overlapping Values are offered for replacement. The result is provided as a DataTransactionResult.

Specified by:

copyFrom in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Parameters:

that - The other CompositeValueStore to copy values from

strategy - The function to resolve merge conflicts

Returns:

The transaction result

getContainers

public Collection<DataManipulator<?,?>> getContainers()

Description copied from interface: CompositeValueStore

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

Specified by:

getContainers in interface CompositeValueStore<DataHolder,DataManipulator<?,?>>

Returns:

A collection of copied ValueContainers originating from this value store

getValue

public <T,V extends BaseValue<T>> Optional<V> getValue(Key<V> key)

Description copied from interface: ValueContainer

Gets the BaseValue for the given Key.

Specified by:

getValue in interface ValueContainer<DataHolder>

Type Parameters:

T - The type of the return type

V - The type of value

Parameters:

key - The key linked to the BaseValue

Returns:

The value, if available

copy

public Location<E> copy()

Description copied from interface: ValueContainer

Creates a clone copy of this ValueContainer as a new ValueContainer such that all the BaseValues are safely duplicated to the new instance.

Specified by:

copy in interface ValueContainer<DataHolder>

Returns:

The new copy

getKeys

public Set<Key<?>> getKeys()

Description copied from interface: ValueContainer

Gets all applicable Keys for this ValueContainer. Changes can not be made to the set to alter the ValueContainer, nor can the BaseValues be changed with the provided ImmutableSet.

Specified by:

getKeys in interface ValueContainer<DataHolder>

Returns:

An immutable set of known Keys

getValues

public Set<ImmutableValue<?>> getValues()

Description copied from interface: ValueContainer

Gets all applicable BaseValues associated with this ValueContainer. As the data backed by the values are copied, any modifications to the BaseValues will not be reflected onto this ValueContainer.

Specified by:

getValues in interface ValueContainer<DataHolder>

Returns:

An immutable set of copied values

toString

public String toString()

Overrides:

toString in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object other)

Overrides:

equals in class Object