Exercise 2 (Packages, Polymorphism) - Deadline is April 14th

This exercise will be open until April 14th.

On March 26th we discuss your model and implementation strategy, if you want. We will meet as usual, but there will be no lecture. You are free to join for discussing your implementation strategies. Please do not hesitate to ask if questions arise or if you need some help, but:

1. Read the guidance twice.
   
2. Show me a draft of your model.
3. Explain your ideas.

You are allowed to use all the language features and API classes which are available from the Java version 1.7 / JDK 7.
(If you are unsure, look at the API documentation or API source-code. You can find the information in the JavaDoc comment.)

Task

• Design a model and write a Java program to simulate an ecosystem.
  
• The ecosystem consists of a river containing three types of animals, bears and otter and fish.
• Each animal is either male or female.
• All the animals in the river might move in a random direction.
• If two animals are about to collide then:
• If it is a bear and another species, then the bear eats the other animal.
• If it is an otter and a fish, then the otter eats the fish.
• If the animals are of the same species but different gender, then they give birth to new animals of that type.
• Fish give birth to 7 new fish.
• Otter give birth to 3 new otter.
• Bears give birth to 2 new bear.
  
• If two fish of the same gender are about to collide, then they will not move. They stay where they are.
• If two otter of the same gender are about to collide, then they will not move. They stay where they are.
• If two bears of the same gender collide, then they fight. The stronger one wins and the weaker bear vanishes.
  
• Each bear has a random strength. If two bears are equally strong, then the bear which is about to move wins. (He has the advantage of the attacker.)
• All animals age.
• A fish lives until the end of its 5th year (the age is between 0 and 5), unless it is killed earlier.
• An otter lives until the end of its 7th year (the age is between 0 and 7), unless it is killed earlier.
• A bear lives until the end of its 9th year (the age is between 0 and 9), unless it is killed earlier.
• There is limited space for each species.
• One species can never occupy more than 60% of an ecosystem.

Assumptions

• The river is modeled by an array of animal objects. The size of the array will be fixed after constructing an ecosystem.
  
• Each cell of the river-array should either be empty (i.e. null), or contain an animal object, which can be a bear, an otter, or a fish.
• One species can never occupy more than 60% of the river. E.g. A river of length 1000 can at most have 600 animals of the same species.
  
• In each time step, based on a random process, each animal either attempts to move into an adjacent array cell or stay where it is.
• One simulation step corresponds to one year.
  
• If an animal attempts to move into a cell which is already occupied (i.e. not null), then those two animals are about to collide.
• The strength of a bear is represented by an integer value 0,1,...,9, where higher number means stronger.
  

Model

• Create the model of the system before you start coding, but read the guidance first.
• Model the system on paper and submit the scanned document, or use any modeling tool of your choice.
• The model should not contain your test class. Other than that, it should contain:
• All the interfaces, abstract classes, classes, and their relationship.
• All the constructors, methods, and fields with the corresponded access modifiers, argument types, return types.
• Use "+" for public, "-" for private, " " for protected and package private. E.g.: + toString(): String
  

Implementation requirements

• Write an arbitrary test class which contains the entry point public static void main(...) {...}. This class is for testing purpose only and must not be submitted.
• Put every class and interface, which you create, into a separate file. None of them should contain an entry point public static void main(...) {...}.
• Write an interface Ecosystem, to represents an arbitrary ecosystem. It has to define (demand) functionality for:
• Adding an animal to the ecosystems at a random empty cell.
  
• Running the simulation for the specified number of time steps.
• Returning the number of animals of a certain species inside the ecosystem. I.e. the number of instances of the specified type.
  
• Returning a compact String representation of the ecosystem, which is a String that only contains one symbol for one cell. The symbol should uniquely identify the species and gender of an animal. E.g.:
  
• "-" represents an empty cell,
• "f" represents a female fish,
• "F" represents a male fish,
• "o" represents a female otter,
• "O" represents a male otter,
• "b" represents a female bear,
• "B" represents a male bear.
• Write a class River, which represents an ecosystem consisting of one river.
• The interface Ecosystem and the class River should be in the same package and all the animal-related classes should be in another package.
  
• The class River should override the method toString from the class Object and return a visualization of the array of animals, with all the state informations. I.e. Animal type, gender, age, strength.
  
• Follow the object oriented design concepts (e.g. Encapsulation, Abstraction).
• Provide a JavaDoc comment for every public and protected class, field, method, and constructor. The comment should describe the behavior and everything a user of your package needs to know (but no internal details).
  
• To initialize an ecosystem, you must provide a possibility to create animals of a specified age, or of random age (within the respective range).
  
• Write a documentation of your design ideas (approx. one A4 page) and append the (scanned) model to the documentation. The format must be pdf.
  
• Put the documentation of the ecosystem module into the folder where your interface Ecosystem can be found.
• Remove all the compiled .class files and submit the folder (package) as compressed tar ball or zip file.
  

Hints

A (pseudo) random numbers \( x \in [0,1) \) can be created by Math.random(). Other possibilities are using the class Random or ThreadLocalRandom.current().

Take care of the case where an animal would move out of the array.

Make sure that every animal only moves once for one simulation step. I.e. if you have a loop for moving animals, like

for (int i = 0; i < river.length; i++) {<br></pre><p>inside of the class River and an animal moves to position i + 1, you have to do one extra incrementation of i.<br></p><p>To test whether your implementation works correctly, use the method toString, but use the method toCompactString to test larger ecosystems. You should test ecosystems with at least 200 cells.</p><p>Use your test class to initialize the ecosystem with some animals and run the simulation stepwise. E.g.:<br></p><pre>// Create an ecosystem<br>Ecosystem eSys = new River(200);<br><br>// Add animals<br>for (int i = 0; i < 60; i++)<br>    eSys.add(new Fish());<br>for (int i = 0; i < 20; i++)<br>    eSys.add(new Otter());<br>for (int i = 0; i < 20; i++)<br>    eSys.add(new Bear());<br><br>System.out.println(eSys.toCompactString());<br>// Run simulation<br>for (int i = 0; i < 50; i++) {<br>    eSys.simulate(1);<br>    System.out.println(eSys.toCompactString());<br>}

One of your test outputs could look like:

-Fb--bf-ffbB-ob------O-ofFofB--fFO---fF---F-FFfo-B--F-fF-------fF---Bf---Ff--b--...
fFbfffbfffbBfbFFFfo--fOofFoFBFFfFObFFffFFFfFFFfFoBFFFfFF-ff-F-FfFo-BFfFOfFfF-bFf...
fF-bffbbfbb-BbFFFfoffOofFoFfBFFfFbOFFffFFFfFFFfoffBFFfFbFffOFfFfooFBFfFOOffFFbFf...
fbbFffbfFbFOBboFFo-fO-ofFFofBFFfbfOFFffFFFfFFFfoffBFFfFbfFOFFfFFooBoFfFOOffFoObf...
FFbFffbfFbFOBboFFofBOFfoFofBFFFfFbfOfFfFFFfFFFfFofFBFfFbfOFFFfFFoofBFfOffOfofObf...
FFfbfbFffbFOBbofofFFBFfoFFoBFFfFFFbOFFFfFFfFbFfFofBfFBFFbOFFFfFoofBFBfOffBOBoOfb...
FFbFbFFfbFfBbfooFfFFBFFoFFoBFfffFFFbFFFFfffffbFFfofBBfFbOFFFFfFoFoBFfBOffBOfBfbf...
FfbFbFFfBbfBbofFofFfBFFFfFFBFfffFFbFFFFFffffFFbffFfBFfFFbFFFFfFoFBFfFFBfFBOFBbff...
FfFbfbFfBbBbFfofffFfFBFFfFfBFfffFFbFFFFFffffFfbffFffBFFbFFFFFfFFFFBfFBFfFFBBFfbF...
ffbfFbFFBbFfFoFfofFfFoBFfFffFfffFFbFFfFFffffFfbffFffFFbfFfFFFfFFFOFfFOBFFOBFFffF...
...
--oOoOOOOO--ooF--o-o-FO-OO-OooOOOoOf-O-o-O-o--O-OoooOooOF-OoOo-f-o-o---OoooOO--f...
128 animals: 0 bears, 120 otter, 8 fish.

Play with different parameters for the birth rate, maximum age, space limitation, and various initial settings.