Changes

Improvements to BlockStates
* Actually capture all the data of TileEntities. This is done by
creating a copy of the TileEntity. The methods of BlockState which
currently directly access the TileEntity reference will modify the data
of that TileEntity-snapshot instead.
* With the call to BlockState.update, the captured TileEntity data gets
applied to the current TileEntity in the world.
* Methods which trigger block specific actions will use the current
TileEntity from the world.
* CraftBlockState does not hand out the wrapped or the snapshot
TileEntity directly. Instead, it provides an applyTo method to copy the
data to a given TileEntity and a method to directly get a copy of the
TileEntity NBT data represented by the BlockState. CraftMetaBlockState
was updated to make use of that.
* Added #getSnapshotInventory() to bukkit which allows modifiying the
captured inventory snapshots of containers.
* Tried to clarify which methods only work if the BlockState is placed,
which methods require the block in the world to still be of the same
type (methods which trigger actions), and that .getInventory() directly
modifies the inventory of the block in the world if the BlockState is
placed and becomes invalid if the block type is changed.
Backwards compatibility
* If the BlockState acts as InventoryHolder, getInventory() will still
return the inventory directly backed by the TileEntity in the world
(like before), and not the snapshot inventory. This compromise should
reduce the potential of these changes to break existing plugins, or
craftbukkit's own use of BlockState.
* The snapshot's inventory can be accessed by a new method
getSnapshotInventory()
* In case the BlockState is not placed (if it was retrieved from the
MetaBlockState of an item), the getInventory() method will however
return the snapshot inventory. So that when the BlockState gets applied
back to the item, the inventory changes are properly included.
* With the changes to CraftMetaBlockState it is no longer required to
call the update method before passing a modified BlockState to the
CraftMetaBlockState. For backwards compatibility the update method will
simply return true for a non-placed BlockState, without actually doing
anything.
Impact on plugins
* Restoring blocks now actually works as expected, properly restoring
the TileEntity data, reglardless if the block changed its type in the
meantime.
* Plugins are now consistently required to call the update method in
order to apply changes to blocks. Though, regarding the Javadoc they
should have been required to do so anyways.
* New feature: Plugins can take and modify inventory snapshots.
* Breaking change: If a plugin gets the BlockState of a block in the
world, modifies the inventory returned by .getInventory(), and then
tries to use the same BlockState to apply the TileEntity data to an
ItemStack block meta, the ItemStack will use the snapshot inventory,
disregarding the changes made to the inventory returned by
.getInventory(). This is the compromise of .getInventory() returning the
inventory directly backed by the TileEntity in the world.
Other fixes related to BlockState:
* TileEntityContainer#getLocation() will run into a NPE if the
TileEntity is non-placed (ex. when getting the BlockState from a
CraftMetaBlockState).
* Beacon.getEntitiesInRange() would previously throw a NPE if called for
a non-placed BlockState. It was changed to now require to be placed and
use the current TileEntity in the world. If the TileEntity in the world
is no longer a beacon, it will return an empty list.
* EndGateway now supports setting and getting the exit location even for
non-placed EndGateways (inside BlockStateMeta) by using / returning a
location with world being null.