/*
 * This file is part of l2jserver <l2jserver.com>.
 *
 * l2jserver is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * l2jserver is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with l2jserver.  If not, see <http://www.gnu.org/licenses/>.
 */
package com.l2jserver.model;

import com.l2jserver.model.id.ID;
import com.l2jserver.service.database.DatabaseService;

/**
 * Base model. Each object model must implement this interface to be able to be
 * inserted into the database.
 * 
 * @param <T>
 *            the {@link ID} type used to represent this {@link Model}
 * 
 * @author <a href="http://www.rogiel.com">Rogiel</a>
 */
public interface Model<T extends ID<?>> {
	/**
	 * @return the object ID
	 */
	T getID();

	/**
	 * Please note that the ID can only be set one time. Once it has been set,
	 * it cannot be changed and a {@link IllegalStateException} will be thrown
	 * if trying to change the ID.
	 * 
	 * @param ID
	 *            the object ID to set
	 * @throws IllegalStateException
	 *             if the ID was already set
	 */
	void setID(T ID) throws IllegalStateException;

	/**
	 * Each object has an desire. Desires express what the
	 * {@link DatabaseService} should do with the object. The service
	 * automatically keep tracks of every database object (and release them when
	 * they are garbage collected).
	 * 
	 * @return the database object desire
	 */
	ObjectDesire getObjectDesire();

	/**
	 * Each object has an desire. Desires express what the
	 * {@link DatabaseService} should do with the object. The service
	 * automatically keep tracks of every database object (and release them when
	 * they are garbage collected).
	 * 
	 * @param desire
	 *            the database object desire to set
	 */
	void setObjectDesire(ObjectDesire desire);

	/**
	 * Indicated what the object wants to do in the database. It indicates
	 * whether the object should be inserted, updated or deleted from the
	 * database.
	 * 
	 * @author <a href="http://www.rogiel.com">Rogiel</a>
	 */
	public enum ObjectDesire {
		/**
		 * Don't do anything
		 */
		NONE,
		/**
		 * Insert a new object into database.
		 * <p>
		 * If the primary key is auto generated by the database a clone of this
		 * object will be created.<br>
		 * If the primary key is <b>not</b> auto generated by the database, an
		 * database exception will occur.
		 */
		INSERT,
		/**
		 * Updates the object in the database.
		 * <p>
		 * If the object is not in the database nothing will happen.
		 */
		UPDATE,
		/**
		 * Deletes the object from the database.
		 * <p>
		 * If tge object is not in the database nothing will happen.
		 */
		DELETE;
	}
}