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.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jeffrey Traer Bernstein, Carl Pearson and minor modifications by Jo Wood.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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`