public interface Inventory extends Iterable<Inventory>, Nameable
TODO Flesh out javadoc from proposal document. For now, see proposal doc here: https://github.com/SpongePowered/SpongeAPI/pull/443
Modifier and Type | Method and Description |
---|---|
int |
capacity()
The maximum number of stacks the Inventory can hold.
|
void |
clear()
Clears this inventory if it is clearable.
|
boolean |
contains(ItemStack stack)
Checks for whether the given stack is contained in this Inventory.
|
boolean |
contains(ItemType type)
Checks for whether there is a stack in this Inventory with the given
ItemType.
|
<T extends Inventory> |
first()
Return the first child inventory, effectively the same as
Inventory::iterator().next() but more convenient when we are
expecting a result set with only a single entry. |
int |
getMaxStackSize()
Returns the maximum size of any stack in this Inventory.
|
<T extends InventoryProperty<?,?>> |
getProperties(Class<T> property)
Gets all properties of the specified type defined directly on this
Inventory.
|
<T extends InventoryProperty<?,?>> |
getProperties(Inventory child,
Class<T> property)
Returns all properties matching the supplied type defined in
this inventory for the specified (immediate) sub-inventory.
|
<T extends InventoryProperty<?,?>> |
getProperty(Class<T> property,
Object key)
Gets a property with the specified key defined directly on this Inventory
if one is defined.
|
<T extends InventoryProperty<?,?>> |
getProperty(Inventory child,
Class<T> property,
Object key)
Gets the property with the specified key defined in this
inventory for the specified (immediate) sub-inventory.
|
boolean |
isEmpty()
Returns true if this Inventory contains no children.
|
<T extends Inventory> |
next()
Return the next sibling inventory, allows traversing the inventory
hierarchy without using an iterator.
|
boolean |
offer(ItemStack stack)
Try to put an ItemStack into this Inventory.
|
Inventory |
parent()
|
Optional<ItemStack> |
peek()
Get without removing the first available stack from this Inventory.
|
Optional<ItemStack> |
peek(int limit)
Uses the same semantics as
poll(int) but does not remove the
items from the inventory. |
Optional<ItemStack> |
poll()
Get and remove the first available stack from this Inventory.
|
Optional<ItemStack> |
poll(int limit)
Get and remove up to
limit items of the type in the first
available stack in this Inventory from all stacks in this Inventory. |
<T extends Inventory> |
query(Class<?>... types)
Query this inventory for inventories matching any of the supplied types.
|
<T extends Inventory> |
query(InventoryProperty<?,?>... props)
Query this inventory for inventories which match any of the supplied
properties.
|
<T extends Inventory> |
query(ItemStack... types)
Query this inventory for inventories containing any stacks which match
the supplied stack operands.
|
<T extends Inventory> |
query(ItemType... types)
Query this inventory for inventories containing any of the supplied item
types.
|
<T extends Inventory> |
query(Object... args)
Query this inventory by dynamically inspecting each operand.
|
<T extends Inventory> |
query(String... names)
Query this inventory for inventories matching any of the supplied titles.
|
<T extends Inventory> |
query(Translatable... names)
Query this inventory for inventories matching any of the supplied titles.
|
InventoryOperationResult |
set(ItemStack stack)
Forcibly put the supplied stack into this inventory.
|
void |
setMaxStackSize(int size)
Sets the maximum stack size of any stack in this ItemList.
|
int |
size()
The number of stacks currently in the Inventory.
|
<T extends Inventory> |
slots()
Returns an iterable view of all
Slot s (leaf nodes) in this
Inventory. |
int |
totalItems()
Returns the number total number of individual items in this
inventory.
|
forEach, iterator, spliterator
@Nullable Inventory parent()
<T extends Inventory> Iterable<T> slots()
Slot
s (leaf nodes) in this
Inventory.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typing<T extends Inventory> T first()
Inventory::iterator().next()
but more convenient when we are
expecting a result set with only a single entry. Also use type specifier
to allow easy pseudo-duck-typing. If no children, then returns
this
.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingthis
<T extends Inventory> T next()
EmptyInventory
.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingEmptyInventory
if
there are no further siblingsOptional<ItemStack> poll()
'Available' has a different meaning for different inventory types. In
a single-slot inventory this has a fixed implication. However larger and
more complex inventories are at liberty to implement whatever logic they
wish to back this method. If an inventory cannot provide a meaningful
implementation of this method then it should return
Optional.absent()
instead.
For consumers, this means that just because an inventory doesn't return anything here, this does not imply that the inventory is empty, just that a more specific query is required to obtain items from it.
Optional.absent()
if
unavailable or unsupportedOptional<ItemStack> poll(int limit)
Get and remove up to limit
items of the type in the first
available stack in this Inventory from all stacks in this Inventory. If
no stack is available then Optional.absent()
is returned (as per
the usual behaviour of poll()
, otherwise a new ItemStack
is returned containing the removed items, the contents of the stack in
the inventory are reduced by the number of items consumed. Note that this
method attempts to consume items into the ouput up to limit
,
which may consume items from an abitrary number of internal slots.
For example, assume an inventory containing 4 slots contains stacks as follows:
[Stone x10] [Dirt x3] [Arrows x9] [Stone x32]
Calling poll(16)
on this inventory will consume Stone
from the Inventory (because the first stack contains stone), and
will then consume the remaining 6 items from the 4th slot.
It is intended that this method is used in conjunction with a query which returns a set of slots containing a specific item type:
Optional<ItemStack> q = inv.query(ItemTypes.DIRT).poll(1);
Optional<ItemStack> peek()
poll()
.Optional.absent()
if
unavailable or unsupportedOptional<ItemStack> peek(int limit)
poll(int)
but does not remove the
items from the inventory. The ItemStack
returned is thus a
new ItemStack containing a copy of the items in inventory. Use
this method only if you wish to determine whether a call to
poll(int)
is likely to succeed.
Note that items returned from peek
are 'live' items, this
means that they are a direct view of the ItemStack stored in the
inventory and mutating them will affect the items in the inventory
directly
boolean offer(ItemStack stack)
Queue
, this method returns true if the Inventory
accepted the stack and false if not, the size of the supplied stack is
reduced by the number of items successfully consumed by the Inventory.
Unlike set(org.spongepowered.api.item.inventory.ItemStack)
, this method's general contract does not permit
items in the Inventory to be replaced. However trying to insert items
that an Inventory cannot accept is not an error condition, the size of
the supplied stack will simply not be reduced if no items are consumed by
the Inventory.
stack
- A stack of items to attempt to insert into the Inventory,
note that upon successful insertion the supplied ItemStack itself
will be mutated and returned with size reduced by the number of
items successfully consumed by the InventoryInventoryOperationResult set(ItemStack stack)
The general contract of this method is to prioritise insertion of the supplied items over items already in the Inventory. However the Inventory may still reject the supplied items if they are of an unsupported type for the target (for example trying to insert non-fuel items into a fuel slot) or if the number of items is larger than the total capacity of the inventory and not all items from the supplied stack can be consumed.
For Slot
s, the supplied stack is generally consumed and the
existing contents ejected (at the discretion of the target Inventory).
For multi-slot inventories the insertion order is up to the target
inventory to decide, and does not have to match the traversal order of
the leaf nodes as supplied by slots()
, although this is
generally recommended. Inventories should document their specific
insertion logic where the insertion order differs from the traversal
order.
Consumers should inspect the returned InventoryOperationResult
and act accordingly. Ejected items should generally be "thrown" into the
world or deposited into another Inventory (depending on the operation in
question. The supplied stack is not adjusted, any rejected items are
returned in the operation result struct.
stack
- the stack to insert into the Inventory, will be mutated by
the number of items successfully consumedvoid clear()
int size()
Slot
s and always 0 for EmptyInventory
s.int totalItems()
int capacity()
Slot
s and always 0 for EmptyInventory
s.boolean isEmpty()
peek()
, poll()
, offer(org.spongepowered.api.item.inventory.ItemStack)
and
set(org.spongepowered.api.item.inventory.ItemStack)
semantics even if it has no internal storage of its own.boolean contains(ItemStack stack)
!inv.query(stack).isEmpty();
stack
- The stack to check forboolean contains(ItemType type)
!inv.query(stack)
.isEmpty();
type
- The type to search forint getMaxStackSize()
void setMaxStackSize(int size)
size
- The new maximum stack size<T extends InventoryProperty<?,?>> Collection<T> getProperties(Inventory child, Class<T> property)
T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingchild
- the child inventory to inspectproperty
- the type of property to query for<T extends InventoryProperty<?,?>> Collection<T> getProperties(Class<T> property)
inv.getParent().getProperty(inv, property);
but for
top-level inventories may include properties defined on the inventory
directly.T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingproperty
- the type of property to query for<T extends InventoryProperty<?,?>> Optional<T> getProperty(Inventory child, Class<T> property, Object key)
T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingchild
- the child inventory to inspectproperty
- the type of property to query forkey
- Property key to search for<T extends InventoryProperty<?,?>> Optional<T> getProperty(Class<T> property, Object key)
inv.getParent().getProperty(inv, property, key);
but for
top-level inventories may include properties defined on the inventory
directly.T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingproperty
- the type of property to query forkey
- Property key to search for<T extends Inventory> T query(Class<?>... types)
instanceof
check against each child
inventory. Logical OR
is applied between operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingtypes
- inventory types (interfaces or classes) to query for<T extends Inventory> T query(ItemType... types)
Slot
leaf nodes in the
inventory and will always return a collection containing only
Slot
instances. Logical OR
is applied between
operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingtypes
- item types to query for<T extends Inventory> T query(ItemStack... types)
Slot
leaf nodes in the inventory and will always return a collection
containing only Slot
instances. Logical OR
is
applied between operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingtypes
- items to query for, the size of the stacks is ignored if the
stack size is set to -1, otherwise the stack sizes must match the
supplied stacks exactly<T extends Inventory> T query(InventoryProperty<?,?>... props)
equals
method of each property is called on
each child inventory which has the supplied property. Logical
OR
is applied between operands. This method is effectively
the same as calling query(java.lang.Class<?>...)
with an
Property.Operator
of
Property.Operator.EQUAL
.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingprops
- inventory properties to query for<T extends Inventory> T query(Translatable... names)
OR
is applied between operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingnames
- the names of the inventories to search for<T extends Inventory> T query(String... names)
OR
is applied between operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingnames
- the names of the inventories to search for<T extends Inventory> T query(Object... args)
Query this inventory by dynamically inspecting each operand. Each operand in turn is checked for a match against the other query methods, and if a matching method is found the query is performed using the operand. This is repeated until all operands are consumed and allows a union of multiple query types to be aggregated into a single view.
For operands with no matching type, the behaviour is determined by the individual inventory. A naive match may be obtained by calling .equals() against the child inventory passing the unknown operand as an argument.
T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingargs
- search parameters