/*
 * @(#)DisposableResourceHolder.java
 *
 * Project:		JHotdraw - a GUI framework for technical drawings
 *				http://www.jhotdraw.org
 *				http://jhotdraw.sourceforge.net
 * Copyright:	© by the original author(s) and all contributors
 * License:		Lesser GNU Public License (LGPL)
 *				http://www.opensource.org/licenses/lgpl-license.html
 */
package org.jhotdraw.contrib.html;

/**
 * DisposableResourceHolder defines the interface for objects holding
 * disposable resources.<br>
 * A disposable resource is any kind of object that can be disposed of
 * according to a given disposal strategy.<BR>
 * DisposableResourceHolder keeps track of the last time the resource is
 * accessed to support ellapsed time ResourceDisposabilityStrategies.<br>
 * For example, if you are handling large images that you can regenerate
 * at will, the DisposableResourceHolder will hold the image, and if not
 * accessed for let's say 60 secs then it discards the image
 * (sets its reference to null) so that it can be GCed.<br>
 * Within the context of JHotDraw, HTMLTextAreaFigure uses
 * DisposableResourceHolders to handle the HTML generated image, but if the
 * figure is not displayed (out of the display area or in a background view) then
 * the image is disposed of after a while and the HTMLTextAreaFigure will regenerate
 * it the next time it is displayed.<br>
 * A resource may be locked so that its user can be sure it will not be
 * disposed of while in use. After finished using it it should be unlocked so as
 * to reintegrate it to the disposal strategy.
 *
 * @author    Eduardo Francos - InContext
 * @created   2 mai 2002
 * @version   <$CURRENT_VERSION$>
 * @see       DisposableResourceManager
 * @see       StandardDisposableResourceManager
 * @see       ResourceDisposabilityStrategy
 * @see       DisposableResourceManagerFactory
 * @see       StandardDisposableResourceHolder
 */
public interface DisposableResourceHolder {

	/**
	 * Gets the resource
	 *
	 * @return                          The resource value
	 * @exception NullPointerException  If the resource was disposed of
	 */
	public Object getResource() throws NullPointerException;

	/**
	 * Makes a clone the this
	 *
	 * @return   the clone
	 */
	public Object clone();

	/**
	 * Sets the resource
	 *
	 * @param resource  The new resource value
	 */
	public void setResource(Object resource);

	/**
	 * Sets the disposableDelay
	 *
	 * @param millis  The new disposableDelay value
	 */
	public void setDisposableDelay(long millis);

	/**
	 * Gets the disposableDelay
	 *
	 * @return   The disposableDelay value
	 */
	public long getDisposableDelay();

	/**
	 * Resets the disposing delay so as to restart the time counter
	 */
	public void resetDelay();

	/**
	 * Gets the lastTimeAccessed attribute of the DisposableResourceHolder object
	 *
	 * @return   The lastTimeAccessed value
	 */
	public long getLastTimeAccessed();

	/** Disposes of the resource immediately. */
	public void dispose();

	/**
	 * Returns true if the resource is still available
	 *
	 * @return   The resourceDirty value
	 */
	public boolean isAvailable();

	/**
	 * Locks the resource so it cannot be automatically disposed of until unlock
	 * is called.<br>
	 * Explicit disposing by calling dispose() is still possible though.
	 */
	public void lock();

	/**
	 * Unlocks the resource so it can be automatically disposed of again.<br>
	 * Explicit disposing by calling dispose() is still possible though.
	 */
	public void unlock();

	/**
	 * True if the resource is locked
	 *
	 * @return   The locked status
	 */
	public boolean isLocked();
}
