Position.java

/*
 * Copyright (c) 2005-2010 KOM – Multimedia Communications Lab
 *
 * This file is part of PeerfactSim.KOM.
 * 
 * PeerfactSim.KOM 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
 * any later version.
 * 
 * PeerfactSim.KOM 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 PeerfactSim.KOM.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

package de.tud.kom.p2psim.api.common;

import de.tudarmstadt.maki.simonstrator.api.common.Transmitable;
import de.tudarmstadt.maki.simonstrator.api.component.sensor.location.Location;

/**
 * The common interface for positions within PeerfactSim, this hides the
 * business logic of a PositionVector in util.position.
 * 
 * You should consider extending PositionVector for your implementations.
 * 
 * @author Bjoern Richerzhagen
 * @version 1.0, 05/26/2011
 * @deprecated please consider using {@link Location} instead!
 */
@Deprecated
public interface Position extends Transmitable, Cloneable, Location {

	/**
	 * Get the distance of this position compared to any other Position, if they
	 * have the same number of dimensions and are compatible.
	 * 
	 * @param position
	 * @return
	 */
	public double getDistance(Position position);

	/**
	 * Calculates the angle <b>in rad</b> from the current position to the
	 * target.
	 * 
	 * @param target
	 * @return An angle in rad between -PI and PI, where 0 is "East", or the
	 *         direction of the positive x-Axis
	 */
	public double getAngle(Position target);

	/**
	 * This method should be consistent with the getDistance and
	 * getAngle-methods. It returns a Position that has the given distance and
	 * angle from the current position.
	 * 
	 * @param distance
	 * @param angle
	 *            an angle in rad between -PI and PI, where 0 is the direction
	 *            of the positive x-Axis and angles are incremented
	 *            counter-clockwise (mathematical)
	 * @return
	 */
	public Position getTarget(double distance, double angle);

	/**
	 * CLone a Position, ensuring there is no information propagation due to
	 * Java. Consider a clone() as some kind of snapshot of the current state of
	 * the cloned position. It is very important to call clone() in scenarios
	 * with moving hosts!
	 * 
	 * @return
	 */
	public Position clone();

}