org.gicentre.utils.network.traer.physics
Interface Force

All Known Implementing Classes:
AbstractForce, Attraction, Spring, TargetedForce, TwoBodyForce, UniversalForce

public interface Force

Interface specifying the basic mechanics of a Force. There are two basic skeletal implementations: a TargetedForce with specified targets, where the apply() method is used; and a UniversalForce that is applied to a Particle, where the apply(Particle) method is used.

The Spring force between two Particles is an example of the first form, while the universal free-fall Gravity is an example of the second form.

An intermediate skeletal implementation of this interface is provided in the AbstractForce class. Unless substantial extra behaviour associated with turning a Force on and off needs to be specified, in general users should extend the AbstractForce class instead of implementing this interface.

Since:
4.0
Author:
Jeffrey Traer Bernstein, Carl Pearson and minor modifications by Jo Wood.

Method Summary
 Force apply()
          Should apply this Force.
 Particle apply(Particle p)
          Should apply this Force to a Particle p.
 boolean isOff()
          Should return true if this force is off.
 boolean isOn()
          Should true if this force is on.
 Force turnOff()
          Should turn the Force off.
 Force turnOn()
          Should turn the Force on.
 Force turnOn(boolean isOn)
          Should set the Force to the argument isOn.
 

Method Detail

turnOff

Force turnOff()
Should turn the Force off. After calling this method, calls to isOff() should return true. Implementations of the Force interface should delegate this call to the turnOn(boolean) method, with a false argument.

Returns:
this Force, de-activated.

turnOn

Force turnOn()
Should turn the Force on. After calling this method, calls to isOn() should return true. Implementations of the Force interface should delegate this call to the turnOn(boolean) method, with a true argument.

Returns:
this Force, activated.

turnOn

Force turnOn(boolean isOn)
Should set the Force to the argument isOn. Subsequent calls to isOn() should return the value of isOn. Implementations of the Force interface should delegate turnOff() and turnOn() to this method.

Parameters:
isOn - the state to set the Force in.
Returns:
this Force, with appropriate activation condition.

isOn

boolean isOn()
Should true if this force is on. Should also consistently return !isOff(). Implementations of the Force interface should delegate the behaviour of one of these methods to the other, to ensure consistency.

Returns:
true if this force is on.

isOff

boolean isOff()
Should return true if this force is off. Should also consistently return !isOn(). Implementations of the Force interface should delegate the behaviour of one of these methods to the other, to ensure consistency.

Returns:
true if this force is off.

apply

Force apply()
            throws java.lang.UnsupportedOperationException,
                   java.lang.IllegalStateException
Should apply this Force.

Returns:
this Force
Throws:
java.lang.UnsupportedOperationException - if the implementing class uses apply(Particle) instead.
java.lang.IllegalStateException - optionally, if the Force is currently off.

apply

Particle apply(Particle p)
               throws java.lang.UnsupportedOperationException,
                      java.lang.IllegalStateException,
                      java.lang.NullPointerException
Should apply this Force to a Particle p.

Parameters:
p - the Particle to apply the Force to; may not be null
Returns:
the Particle p, after the Force is applied.
Throws:
java.lang.UnsupportedOperationException - if the implementing class uses apply() instead.
java.lang.IllegalStateException - optionally, if the Force is currently off, or if the Particle is fixed
java.lang.NullPointerException - if p == null


giCentre Utilities V.3.3, API documentation generated 6th April, 2013