/*
 *  @(#)TextAreaFigure.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 CH.ifa.draw.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   1.0
 * @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();
}