/*
 * 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();
	}

}