Applied-Energistics-2/src/api/java/appeng/api/implementations/items/IStorageCell.java

/*
 * The MIT License (MIT)
 *
 * Copyright (c) 2013 AlgorithmX2
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

package appeng.api.implementations.items;

import javax.annotation.Nonnull;

import net.minecraft.item.ItemStack;

import appeng.api.storage.IStorageChannel;
import appeng.api.storage.cells.ICellHandler;
import appeng.api.storage.cells.ICellInventory;
import appeng.api.storage.cells.ICellWorkbenchItem;
import appeng.api.storage.data.IAEStack;

/**
 * Any item which implements this can be treated as an IMEInventory via
 * {@link ICellHandler#getCellInventory(ItemStack, appeng.api.storage.cells.ISaveProvider, IStorageChannel)}
 * or {@link ICellHandler#isCell(ItemStack)}. It automatically handles the
 * internals and NBT data, which is both nice, and bad for you!
 *
 * Good cause it means you don't have to do anything, bad because you have
 * little to no control over it.
 * 
 * Limited to {@link Integer} internally for most calculations. E.g. if the used
 * or remaining bytes would overflow {@link Integer#MAX_VALUE} the behaviour is
 * no longer specified. Even if {@link ICellInventory} is using {@link Long}.
 * 
 * The standard AE implementation also only provides 1-63 Types.
 */
public interface IStorageCell<T extends IAEStack<T>> extends ICellWorkbenchItem {

    /**
     * It wont work if the return is not a multiple of 8. The limit is
     * ({@link Integer#MAX_VALUE} + 1) / 8.
     *
     * @param cellItem item
     *
     * @return number of bytes
     */
    int getBytes(@Nonnull ItemStack cellItem);

    /**
     * Determines the number of bytes used for any type included on the cell.
     *
     * @param cellItem item
     *
     * @return number of bytes
     */
    int getBytesPerType(@Nonnull ItemStack cellItem);

    /**
     * Must be between 1 and 63, indicates how many types you want to store on the
     * item.
     *
     * @param cellItem item
     *
     * @return number of types
     */
    int getTotalTypes(@Nonnull ItemStack cellItem);

    /**
     * Allows you to fine tune which items are allowed on a given cell, if you don't
     * care, just return false; As the handler for this type of cell is still the
     * default cells, the normal AE black list is also applied.
     *
     * @param cellItem          item
     * @param requestedAddition requested addition
     *
     * @return true to preventAdditionOfItem
     */
    boolean isBlackListed(@Nonnull ItemStack cellItem, @Nonnull T requestedAddition);

    /**
     * Allows you to specify if this storage cell can be stored inside other storage
     * cells, only set this for special items like the matter cannon that are not
     * general purpose storage.
     *
     * @return true if the storage cell can be stored inside other storage cells,
     *         this is generally false, except for certain situations such as the
     *         matter cannon.
     */
    boolean storableInStorageCell();

    /**
     * Allows an item to selectively enable or disable its status as a storage cell.
     *
     * @param i item
     *
     * @return if the ItemStack should behavior as a storage cell.
     */
    boolean isStorageCell(@Nonnull ItemStack i);

    /**
     * @return drain in ae/t this storage cell will use.
     */
    double getIdleDrain();

    /**
     * @return the type of channel your cell should be part of
     */
    @Nonnull
    IStorageChannel<T> getChannel();
}