Bukkit-API  1.7.9-R0.2
The inofficial Bukkit-API
Inventory.java
1 package org.bukkit.inventory;
2 
3 import java.util.HashMap;
4 import java.util.List;
5 import java.util.ListIterator;
6 
7 import org.bukkit.Material;
10 
11 /**
12  * Interface to the various inventories. Behavior relating to {@link
13  * Material#AIR} is unspecified.
14  */
15 public interface Inventory extends Iterable<ItemStack> {
16 
17  /**
18  * Returns the size of the inventory
19  *
20  * @return The size of the inventory
21  */
22  public int getSize();
23 
24  /**
25  * Returns the maximum stack size for an ItemStack in this inventory.
26  *
27  * @return The maximum size for an ItemStack in this inventory.
28  */
29  public int getMaxStackSize();
30 
31  /**
32  * This method allows you to change the maximum stack size for an
33  * inventory.
34  * <p>
35  * <b>Caveats:</b>
36  * <ul>
37  * <li>Not all inventories respect this value.
38  * <li>Stacks larger than 127 may be clipped when the world is saved.
39  * <li>This value is not guaranteed to be preserved; be sure to set it
40  * before every time you want to set a slot over the max stack size.
41  * <li>Stacks larger than the default max size for this type of inventory
42  * may not display correctly in the client.
43  * </ul>
44  *
45  * @param size The new maximum stack size for items in this inventory.
46  */
47  public void setMaxStackSize(int size);
48 
49  /**
50  * Returns the name of the inventory
51  *
52  * @return The String with the name of the inventory
53  */
54  public String getName();
55 
56  /**
57  * Returns the ItemStack found in the slot at the given index
58  *
59  * @param index The index of the Slot's ItemStack to return
60  * @return The ItemStack in the slot
61  */
62  public ItemStack getItem(int index);
63 
64  /**
65  * Stores the ItemStack at the given index of the inventory.
66  *
67  * @param index The index where to put the ItemStack
68  * @param item The ItemStack to set
69  */
70  public void setItem(int index, ItemStack item);
71 
72  /**
73  * Stores the given ItemStacks in the inventory. This will try to fill
74  * existing stacks and empty slots as well as it can.
75  * <p>
76  * The returned HashMap contains what it couldn't store, where the key is
77  * the index of the parameter, and the value is the ItemStack at that
78  * index of the varargs parameter. If all items are stored, it will return
79  * an empty HashMap.
80  * <p>
81  * If you pass in ItemStacks which exceed the maximum stack size for the
82  * Material, first they will be added to partial stacks where
83  * Material.getMaxStackSize() is not exceeded, up to
84  * Material.getMaxStackSize(). When there are no partial stacks left
85  * stacks will be split on Inventory.getMaxStackSize() allowing you to
86  * exceed the maximum stack size for that material.
87  *
88  * @param items The ItemStacks to add
89  * @return A HashMap containing items that didn't fit.
90  * @throws IllegalArgumentException if items or any element in it is null
91  */
92  public HashMap<Integer, ItemStack> addItem(ItemStack... items) throws IllegalArgumentException;
93 
94  /**
95  * Removes the given ItemStacks from the inventory.
96  * <p>
97  * It will try to remove 'as much as possible' from the types and amounts
98  * you give as arguments.
99  * <p>
100  * The returned HashMap contains what it couldn't remove, where the key is
101  * the index of the parameter, and the value is the ItemStack at that
102  * index of the varargs parameter. If all the given ItemStacks are
103  * removed, it will return an empty HashMap.
104  *
105  * @param items The ItemStacks to remove
106  * @return A HashMap containing items that couldn't be removed.
107  * @throws IllegalArgumentException if items is null
108  */
109  public HashMap<Integer, ItemStack> removeItem(ItemStack... items) throws IllegalArgumentException;
110 
111  /**
112  * Returns all ItemStacks from the inventory
113  *
114  * @return An array of ItemStacks from the inventory.
115  */
116  public ItemStack[] getContents();
117 
118  /**
119  * Completely replaces the inventory's contents. Removes all existing
120  * contents and replaces it with the ItemStacks given in the array.
121  *
122  * @param items A complete replacement for the contents; the length must
123  * be less than or equal to {@link #getSize()}.
124  * @throws IllegalArgumentException If the array has more items than the
125  * inventory.
126  */
127  public void setContents(ItemStack[] items) throws IllegalArgumentException;
128 
129  /**
130  * Checks if the inventory contains any ItemStacks with the given
131  * materialId
132  *
133  * @param materialId The materialId to check for
134  * @return true if an ItemStack in this inventory contains the materialId
135  * @deprecated Magic value
136  */
137  @Deprecated
138  public boolean contains(int materialId);
139 
140  /**
141  * Checks if the inventory contains any ItemStacks with the given
142  * material.
143  *
144  * @param material The material to check for
145  * @return true if an ItemStack is found with the given Material
146  * @throws IllegalArgumentException if material is null
147  */
148  public boolean contains(Material material) throws IllegalArgumentException;
149 
150  /**
151  * Checks if the inventory contains any ItemStacks matching the given
152  * ItemStack.
153  * <p>
154  * This will only return true if both the type and the amount of the stack
155  * match.
156  *
157  * @param item The ItemStack to match against
158  * @return false if item is null, true if any exactly matching ItemStacks
159  * were found
160  */
161  public boolean contains(ItemStack item);
162 
163  /**
164  * Checks if the inventory contains any ItemStacks with the given
165  * materialId, adding to at least the minimum amount specified.
166  *
167  * @param materialId The materialId to check for
168  * @param amount The minimum amount to look for
169  * @return true if this contains any matching ItemStack with the given
170  * materialId and amount
171  * @deprecated Magic value
172  */
173  @Deprecated
174  public boolean contains(int materialId, int amount);
175 
176  /**
177  * Checks if the inventory contains any ItemStacks with the given
178  * material, adding to at least the minimum amount specified.
179  *
180  * @param material The material to check for
181  * @param amount The minimum amount
182  * @return true if amount is less than 1, true if enough ItemStacks were
183  * found to add to the given amount
184  * @throws IllegalArgumentException if material is null
185  */
186  public boolean contains(Material material, int amount) throws IllegalArgumentException;
187 
188  /**
189  * Checks if the inventory contains at least the minimum amount specified
190  * of exactly matching ItemStacks.
191  * <p>
192  * An ItemStack only counts if both the type and the amount of the stack
193  * match.
194  *
195  * @param item the ItemStack to match against
196  * @param amount how many identical stacks to check for
197  * @return false if item is null, true if amount less than 1, true if
198  * amount of exactly matching ItemStacks were found
199  * @see #containsAtLeast(ItemStack, int)
200  */
201  public boolean contains(ItemStack item, int amount);
202 
203  /**
204  * Checks if the inventory contains ItemStacks matching the given
205  * ItemStack whose amounts sum to at least the minimum amount specified.
206  *
207  * @param item the ItemStack to match against
208  * @param amount the minimum amount
209  * @return false if item is null, true if amount less than 1, true if
210  * enough ItemStacks were found to add to the given amount
211  */
212  public boolean containsAtLeast(ItemStack item, int amount);
213 
214  /**
215  * Returns a HashMap with all slots and ItemStacks in the inventory with
216  * given materialId.
217  * <p>
218  * The HashMap contains entries where, the key is the slot index, and the
219  * value is the ItemStack in that slot. If no matching ItemStack with the
220  * given materialId is found, an empty map is returned.
221  *
222  * @param materialId The materialId to look for
223  * @return A HashMap containing the slot index, ItemStack pairs
224  * @deprecated Magic value
225  */
226  @Deprecated
227  public HashMap<Integer, ? extends ItemStack> all(int materialId);
228 
229  /**
230  * Returns a HashMap with all slots and ItemStacks in the inventory with
231  * the given Material.
232  * <p>
233  * The HashMap contains entries where, the key is the slot index, and the
234  * value is the ItemStack in that slot. If no matching ItemStack with the
235  * given Material is found, an empty map is returned.
236  *
237  * @param material The material to look for
238  * @return A HashMap containing the slot index, ItemStack pairs
239  * @throws IllegalArgumentException if material is null
240  */
241  public HashMap<Integer, ? extends ItemStack> all(Material material) throws IllegalArgumentException;
242 
243  /**
244  * Finds all slots in the inventory containing any ItemStacks with the
245  * given ItemStack. This will only match slots if both the type and the
246  * amount of the stack match
247  * <p>
248  * The HashMap contains entries where, the key is the slot index, and the
249  * value is the ItemStack in that slot. If no matching ItemStack with the
250  * given Material is found, an empty map is returned.
251  *
252  * @param item The ItemStack to match against
253  * @return A map from slot indexes to item at index
254  */
255  public HashMap<Integer, ? extends ItemStack> all(ItemStack item);
256 
257  /**
258  * Finds the first slot in the inventory containing an ItemStack with the
259  * given materialId.
260  *
261  * @param materialId The materialId to look for
262  * @return The slot index of the given materialId or -1 if not found
263  * @deprecated Magic value
264  */
265  @Deprecated
266  public int first(int materialId);
267 
268  /**
269  * Finds the first slot in the inventory containing an ItemStack with the
270  * given material
271  *
272  * @param material The material to look for
273  * @return The slot index of the given Material or -1 if not found
274  * @throws IllegalArgumentException if material is null
275  */
276  public int first(Material material) throws IllegalArgumentException;
277 
278  /**
279  * Returns the first slot in the inventory containing an ItemStack with
280  * the given stack. This will only match a slot if both the type and the
281  * amount of the stack match
282  *
283  * @param item The ItemStack to match against
284  * @return The slot index of the given ItemStack or -1 if not found
285  */
286  public int first(ItemStack item);
287 
288  /**
289  * Returns the first empty Slot.
290  *
291  * @return The first empty Slot found, or -1 if no empty slots.
292  */
293  public int firstEmpty();
294 
295  /**
296  * Removes all stacks in the inventory matching the given materialId.
297  *
298  * @param materialId The material to remove
299  * @deprecated Magic value
300  */
301  @Deprecated
302  public void remove(int materialId);
303 
304  /**
305  * Removes all stacks in the inventory matching the given material.
306  *
307  * @param material The material to remove
308  * @throws IllegalArgumentException if material is null
309  */
310  public void remove(Material material) throws IllegalArgumentException;
311 
312  /**
313  * Removes all stacks in the inventory matching the given stack.
314  * <p>
315  * This will only match a slot if both the type and the amount of the
316  * stack match
317  *
318  * @param item The ItemStack to match against
319  */
320  public void remove(ItemStack item);
321 
322  /**
323  * Clears out a particular slot in the index.
324  *
325  * @param index The index to empty.
326  */
327  public void clear(int index);
328 
329  /**
330  * Clears out the whole Inventory.
331  */
332  public void clear();
333 
334  /**
335  * Gets a list of players viewing the inventory. Note that a player is
336  * considered to be viewing their own inventory and internal crafting
337  * screen even when said inventory is not open. They will normally be
338  * considered to be viewing their inventory even when they have a
339  * different inventory screen open, but it's possible for customized
340  * inventory screens to exclude the viewer's inventory, so this should
341  * never be assumed to be non-empty.
342  *
343  * @return A list of HumanEntities who are viewing this Inventory.
344  */
345  public List<HumanEntity> getViewers();
346 
347  /**
348  * Returns the title of this inventory.
349  *
350  * @return A String with the title.
351  */
352  public String getTitle();
353 
354  /**
355  * Returns what type of inventory this is.
356  *
357  * @return The InventoryType representing the type of inventory.
358  */
359  public InventoryType getType();
360 
361  /**
362  * Gets the block or entity belonging to the open inventory
363  *
364  * @return The holder of the inventory; null if it has no holder.
365  */
366  public InventoryHolder getHolder();
367 
368  @Override
369  public ListIterator<ItemStack> iterator();
370 
371  /**
372  * Returns an iterator starting at the given index. If the index is
373  * positive, then the first call to next() will return the item at that
374  * index; if it is negative, the first call to previous will return the
375  * item at index (getSize() + index).
376  *
377  * @param index The index.
378  * @return An iterator.
379  */
380  public ListIterator<ItemStack> iterator(int index);
381 }
HashMap< Integer,?extends ItemStack > all(int materialId)
HashMap< Integer, ItemStack > removeItem(ItemStack...items)
HashMap< Integer, ItemStack > addItem(ItemStack...items)
InventoryHolder getHolder()
void setContents(ItemStack[] items)
boolean contains(int materialId)
ItemStack getItem(int index)
List< HumanEntity > getViewers()
void setItem(int index, ItemStack item)
boolean containsAtLeast(ItemStack item, int amount)
int first(int materialId)