package ballWorlds;

import java.awt.geom.Point2D;
import java.util.List;

/**
 * A WorldDescriber is an object that can describe (return) attributes about
 * itself like its middle point, its Color and Shape (inherited from Drawable),
 * and how an object that has gone outside of this World should bounce.
 * 
 * @author David Mutchler, Salman Azhar, Curt Clifton and others, January 2005.
 *         Modified September 2008, September 2009.
 */
public interface WorldDescriber extends Drawable {

	/**
	 * Returns a Point2D that is at the middle of this World.
	 * 
	 * @return a Point2D that is at the middle of this World.
	 */
	public Point2D middleOfWorld();

	/**
	 * Returns a Point2D that is a random point in this World.
	 * 
	 * @return a Point2D that is a random point in this World.
	 */
	public Point2D randomPointInWorld();

	/**
	 * Returns true if the given point's x-coordinate is inside this World.
	 * 
	 * @param p
	 *            the point whose x-coordinate is to be checked.
	 * @return true if the given point's x-coordinate is inside this World.
	 */
	public boolean isInsideWorldX(Point2D p);

	/**
	 * Returns true if the given point's y-coordinate is inside this World.
	 * 
	 * @param p
	 *            the point whose y-coordinate is to be checked.
	 * @return true if the given point's y-coordinate is inside this World.
	 */
	public boolean isInsideWorldY(Point2D p);

	/**
	 * Returns a random other World (or this World if it is the only one).
	 * 
	 * @return a random other World (or this World if it is the only one).
	 */
	public World getAnotherWorld();

	/**
	 * Returns a List<World> that contains all the Worlds in the Universe. Each
	 * call to this method returns a fresh List<World> object that contains all
	 * the World objects known to this World independently from any other
	 * List<World> objects in use at the same time. This allows the caller to
	 * safely iterate through this List<World> without fear of it being
	 * concurrently modified by other Threads (and possibly generating a
	 * ConcurrentModification exception).
	 * 
	 * @return a List that contains all the Worlds in this Universe.
	 */
	public List<World> getAllWorlds();
}