001 package org.bukkit.inventory;
002
003 import java.util.HashMap;
004 import java.util.List;
005 import java.util.ListIterator;
006
007 import org.bukkit.Material;
008 import org.bukkit.entity.HumanEntity;
009 import org.bukkit.event.inventory.InventoryType;
010
011 /**
012 * Interface to the various inventories. Behavior relating to {@link
013 * Material#AIR} is unspecified.
014 */
015 public interface Inventory extends Iterable<ItemStack> {
016
017 /**
018 * Returns the size of the inventory
019 *
020 * @return The size of the inventory
021 */
022 public int getSize();
023
024 /**
025 * Returns the maximum stack size for an ItemStack in this inventory.
026 *
027 * @return The maximum size for an ItemStack in this inventory.
028 */
029 public int getMaxStackSize();
030
031 /**
032 * This method allows you to change the maximum stack size for an
033 * inventory.
034 * <p>
035 * <b>Caveats:</b>
036 * <ul>
037 * <li>Not all inventories respect this value.
038 * <li>Stacks larger than 127 may be clipped when the world is saved.
039 * <li>This value is not guaranteed to be preserved; be sure to set it
040 * before every time you want to set a slot over the max stack size.
041 * <li>Stacks larger than the default max size for this type of inventory
042 * may not display correctly in the client.
043 * </ul>
044 *
045 * @param size The new maximum stack size for items in this inventory.
046 */
047 public void setMaxStackSize(int size);
048
049 /**
050 * Returns the name of the inventory
051 *
052 * @return The String with the name of the inventory
053 */
054 public String getName();
055
056 /**
057 * Returns the ItemStack found in the slot at the given index
058 *
059 * @param index The index of the Slot's ItemStack to return
060 * @return The ItemStack in the slot
061 */
062 public ItemStack getItem(int index);
063
064 /**
065 * Stores the ItemStack at the given index of the inventory.
066 *
067 * @param index The index where to put the ItemStack
068 * @param item The ItemStack to set
069 */
070 public void setItem(int index, ItemStack item);
071
072 /**
073 * Stores the given ItemStacks in the inventory. This will try to fill
074 * existing stacks and empty slots as well as it can.
075 * <p>
076 * The returned HashMap contains what it couldn't store, where the key is
077 * the index of the parameter, and the value is the ItemStack at that
078 * index of the varargs parameter. If all items are stored, it will return
079 * an empty HashMap.
080 * <p>
081 * If you pass in ItemStacks which exceed the maximum stack size for the
082 * Material, first they will be added to partial stacks where
083 * Material.getMaxStackSize() is not exceeded, up to
084 * Material.getMaxStackSize(). When there are no partial stacks left
085 * stacks will be split on Inventory.getMaxStackSize() allowing you to
086 * exceed the maximum stack size for that material.
087 *
088 * @param items The ItemStacks to add
089 * @return A HashMap containing items that didn't fit.
090 * @throws IllegalArgumentException if items or any element in it is null
091 */
092 public HashMap<Integer, ItemStack> addItem(ItemStack... items) throws IllegalArgumentException;
093
094 /**
095 * Removes the given ItemStacks from the inventory.
096 * <p>
097 * It will try to remove 'as much as possible' from the types and amounts
098 * you give as arguments.
099 * <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 }