Output interfaces

Closes #9 (closed)

Architecture overview

• The HamsterGameAdapter contains all ouput and input functionality
  • it provides an observable version of the territory
  • it provides a observable version of the log
  • it provides a HamsterGameController, which has methods to stop, pause, resume, undo and redo
  • it allows adding / removing input interfaces
• There is a one-to-one relation between the adapter and the HamsterGame. The hamster game handles the internal game logic and provides methods for the user to interact with the hamster game, while the adapter contains all functionality which i/o components need, for example a UI or a test framework
• for all internal classes, an "Observable"- interface exists.
  • This makes it possible to add functionality to ReadOnly internal classes, which should not be visible to the user, e.g. the grain count property of a ReadOnlyHamster.
  • Imho, it is also better to provide just interfaces to i/o components - it makes it way easier to change the internals whithout breaking these components
• There is now not only one input interface, but many
  • Each interface's method is called when a input is requested (on a different thread). The main thread waits until at least one interface returned a value. After that, each other interface is notified that the input request is aborted
  • This functionality was added that e.g. a user can use different UIs. The user only wants to input the input one time, the other input requests should be aborted after the first input.
  • If more than one interface returns a value, only the first input is used (all others are ignored).

Breaking changes

• The HamsterGame does not provide the GameLog and the GameCommandStack any longer. These two classes are located in packages which are not exported, so a normal user may be confused by these methods. These objects were used by the UI, however the HamsterGameAdapter now provides that functionality
• The InputInterface now has an additional abort method. This is necessary because input can be aborted. The InputInterface now also must be thread safe (with limitation, see InputInterface)
• The HamsterGame now has no method to open the javafx UI. This functionality was moved to JavaFXUI, so that HamsterGame is independed from the chosen UI (reduce coupling of the modules). The new displayInNewGameWindowmethod is also easier to use (this is important because this enables developers to chose the UI without knowledge of the hamster simulator internal by just calling a single method), because it
  • automatically starts javafx
  • adds the InputInterface if necessary
  • opens the scene
• On HamsterGame, the InputInterface functionality was moved to the adapter
• Mode was moved to de.unistuttgart.iste.rss.oo.hamstersimulator.datatypes because it should be visible to the user

Limitations

• If the user does not use java modules in his/her project, the HamsterGameAdapter can be misused, because the user can cast the objects which are returned from the adapter api to its "Game"- equivalents (e.g. ObservableHamster to GameHamster). These classes contain functionality which is not meant to be used by e.g. a UI (creating CommandSpecifications, executing CommandSpecifications).
  • It would be possible to prevent this by - instead of using interfaces - using wrapper objects for all internal objects. This approach was not used because the Hamster itself is basically a wrapper of the GameHamster class - a wrapper for a wrapper object is not reasonable imho
  • The leaked functionality is not critical. The user already has access to the Hamster, so moving a Hamster by manually creating CommandSpecifications does not make any sense. Additionally, because of the architecture of the hamster simulatior, commands can only executed in its intended way, so it should not be possible to break the undo / redo functionality
  • The only information which should not be visible to the user is the grain count of a hamster. However, it is way easier to hust put down all grains, and then pick them up again.
  • If a project uses the java module system, the exploid is not possible. So to prevent the exploit, it is sufficient to check that the module-info was not removed

Documentation

• All added methods / classes are fully documented
• Some changed methods are now documented
• All methods which are meant to be used by students also have jml
• Some internal methods which are public, but not meant to be used by students do not have jml (mostly getters for properties)