package ballWorlds;

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

/**
 * A BallManager manages the Balls in a World. It can add or remove Balls from
 * its World, and it can return various lists of Balls in its World, e.g. the
 * Balls in its World that intersect a given Ball.
 * 
 * @author David Mutchler, Salman Azhar, Curt Clifton and others, January 2005.
 *         Modified September 2008, September 2009.
 */
public interface BallManager {

	/**
	 * Adds the given Ball to this World.
	 * 
	 * @param ballToAdd
	 *            the Ball to add to this World.
	 */
	public void addBall(Ball ballToAdd);

	/**
	 * Removes the given Ball from this World.
	 * 
	 * @param ballToRemove
	 *            the Ball to remove from this World.
	 */
	public void removeBall(Ball ballToRemove);

	/**
	 * Returns the Ball in this World that is nearest the given point. Returns
	 * null if there are no Balls at all in this World.
	 * 
	 * @param p
	 *            the point for which to find the nearest Ball.
	 * @return the Ball in this World that is nearest the given point.
	 */
	public Ball nearestBall(Point2D p);

	/**
	 * Returns a Ball that intersects the given Ball, or null if no Ball
	 * intersects the given Ball.
	 * 
	 * @param ballToCheckForIntersections
	 *            Ball to check for intersection with other Balls.
	 * @return a Ball that intersects this Ball, or null if no Ball intersects
	 *         this Ball.
	 */
	public Ball intersectingBall(Ball ballToCheckForIntersections);

	/**
	 * Returns a List<Ball> that contains all the Balls in this World that
	 * intersect the given Ball
	 * 
	 * <p>
	 * Each call to this method returns a fresh List<Ball> object that contains
	 * all the Ball objects in this World that intersect the given Ball
	 * independently from any other List<Ball> objects in use at the same time.
	 * This allows the caller to safely iterate through this List<Ball> without
	 * fear of it being concurrently modified by other Threads (and possibly
	 * generating a ConcurrentModification exception).
	 * 
	 * @param ballToCheckForIntersections
	 *            Ball to check for intersection with other Balls.
	 * @return a List that contains all the Balls in this World that intersect
	 *         the given Ball.
	 */
	public List<Ball> intersectingBalls(Ball ballToCheckForIntersections);

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