/*
 * Copyright 2011-2023 MicroEJ Corp. All rights reserved.
 * This library is provided in source code for use, modification and test, subject to license terms.
 * Any modification of the source code will break MicroEJ Corp. warranties on the whole library.
 */
package ej.bon;

import java.util.Hashtable;
import java.util.NoSuchElementException;

/**
 * This class gives access to the global immutable objects pool.
 * <p>
 * Immutable objects are persistent and normally reside in read-only-memory,
 * such as flash memory.
 * <p>
 * The method {@link #get(String)} allows to retrieve an object from the pool
 * using its ID.
 */
public class Immutables {

    /**
     * Retrieves the object that match the the given ID in the immutable objects
     * pool.
     * <p>
     * If no object can be found with such ID, a {@link NoSuchElementException} is
     * thrown.
     *
     * @param ID
     *            the ID of the immutable object to get
     * @return the immutable object matching the ID
     * @throws NoSuchElementException
     *             if the ID is not found
     * @throws ImmutablesError
     *             if an internal error occurred during immutable access
     */
    public static Object get(String ID) {
        throw new RuntimeException();
    }

    /**
     * Maps the given ID to the given object in the immutable objects pool.
     * <p>
     * The object can be retrieved by calling the get method with an ID that is
     * equal to the original ID.
     *
     * @param ID
     *            the ID of the immutable object to set
     * @param object
     *            the object to set immutable
     * @throws NullPointerException
     *             if given object is <code>null</code>
     * @throws OutOfMemoryError
     *             if the immutable memory is full
     * @see #freeMemory()
     */
    @Deprecated
    public static void put(String ID, Object object) {
        throw new RuntimeException();
    }

    /**
     * Maps all the mappings in the given table in the immutable objects pool.
     *
     * @param table
     *            the table that contains the objects to set immutable
     * @throws NullPointerException
     *             if given table is <code>null</code>
     * @throws ClassCastException
     *             if an ID is not a {@link String}
     * @throws OutOfMemoryError
     *             if the immutable memory is full
     * @see #freeMemory()
     * @see #put(String, Object)
     */
    @Deprecated
    public static void putAll(Hashtable table) {
        throw new RuntimeException();
    }

    /**
     * Gets whether or not the given object is in the immutable objects pool or not.
     *
     * @param object
     *            the object to check
     * @return <code>true</code> if the given object is immutable,
     *         <code>false</code> otherwise
     * @throws NullPointerException
     *             if given object is <code>null</code>
     */
    public static boolean isImmutable(Object object) {
        throw new RuntimeException();
    }

    /**
     * Returns an array with the IDs of all the objects in the pool.
     *
     * @return all the immutable objects ID.
     * @see #get(String)
     */
    public static String[] allIDs() {
        throw new RuntimeException();
    }

    /**
     * Returns the amount of free immutable memory still available.
     *
     * @return the amount of free immutable memory
     */
    public static long freeMemory() {
        throw new RuntimeException();
    }

    /**
     * Returns the total amount of immutable memory.
     * <p>
     * Note that the amount of memory required to hold an object of any given type
     * may be implementation-dependent.
     *
     * @return the total amount of immutable memory
     */
    public static long totalMemory() {
        throw new RuntimeException();
    }
}