CS 302 Programming Assignment 1: Golf...and fireworks!

Due date: Friday, September 28 at 7:00 pm (CSL time)

Last modified: Wednesday, September 26, 2007

9/26/2007	The handin directories have been created. See the Handin section for details about how to use the Handin program and what to hand in. Edit for clarification: sentence added to make it clear that the print method is required.
9/21/2007	Program released. The handin directories have not yet been created - watch this space (and your email) for an update when they have been.

In this assignment you will write a class that simulates the motion of physical objects in freefall near the Earth's surface. Then you will use this class to animate golf balls in flight and a fireworks display. (Don't worry; we take care of most of the animation code, and all the physics you need to know is right in this document!)

You will model physical objects by using the instantiable class Particle; each object from this class represents a different physical object. After implementing and testing the Particle class, you will use it in an application class AnimationPlayer, where you will set up the starting position and velocity of Particle objects in such a way that the golf animations will be holes-in-one. You will create multiple instances of Particle objects to represent the different golf balls and use them with an instance of a class called Animator to make the animation come to life. The fireworks display is also based directly on your Particle implementation but in such a way that you don't actually instantiate any new Particle objects. That is, your Particle class is used to implement a fireworks display but how this is done is completely hidden from your point of view! Finally, you will be required to answer some questions in a separate file.

• Learn how to implement a simple class
• Learn how to comment the public interface of your class
• Learn how to test your class
• Learn how to write a simple application class
• Learn how to instantiate and use interacting objects
• Learn how to use pre-existing classes and their methods

• Physics background
• The Particle Class
• Testing the Particle Class
• The Animator Class
• The AnimationPlayer Class
• Documentation
• Questions to answer
• Assignment requirements

Your program will have to implement some basic physics to satisfy the requirements of the project. The purpose of this section is to give you the physics background you will need in order to complete this project.

We will be representing the position of physical objects in a 2-dimensional coordinate system. In this system, the y-axis is vertical ("goes up") and corresonds to "height", whereas the x-axis is horizontal ("goes to the right"). Every physical object has a location which is uniquely determined by a pair of decimal numbers that represent its position with respect to the origin of the coorindate system, just like in algebra. For our purposes, these numbers are always in units of meters. For example, the ball's x-position is -20.24 meters and y-position is 4.37 meters in the figure below (the ball is white). (Note that the origin is roughly in the middle of the tee box at the right of the figure. Also note that the "fake 3D" look of the program is just for show; it's really a 2D world, i.e., the tee is literally higher than the green.)

We will also need to deal with velocities. Every physical object has an x-velocity (which represents "how fast the physical object is going in the x-direction") and a y-velocity (which represents "how fast the physical object is going in the y-direction"). The values can be positive or negative. For the y-velocity, positive would indicate that the object is going up, whereas negative indicates that the object is going down. In the case of x-velocity, positive values indicate that the object is going to the right while negative values mean the object is going left (for our coordinate system, anyway). A velocity of zero in either case means that there is currently no motion in that particular direction. We will always use units of meters per second to describe velocities (which basically means "how many meters would it go per second, if it kept going at the current speed"). The following illustration shows the x and y velocities of the ball as "arrows" coming out of it. The (very approximate) path of the ball is also shown for reference. Note that the y-velocity is negative since the ball is going down (also note that these annotations won't be displayed when the program is running).

One final note on terminology: when we just say "velocity" or "position" (without specifying x or y), we mean both x and y components. The main thing we will need for the program is to know an answer to the question: "Given we know the current position and velocity of some physical object, how do we figure out what the position and velocity will be t seconds from now (for some given positive value of t)?".

Suppose that we have a physical object and we know its current x-position p_x, y-position p_y, x-velocity v_x, and y-velocity v_y. We want to find the new position and velocity t seconds from now (we will denote these future position and velocity values as x-position P_x, y-position P_y, x-velocity V_x, and y-velocity V_y). Then these new position and velocity values are given by the following equations. These equations (based upon a 9.8 m/s/s acceleration down the negative y axis as the given number of seconds of time goes by) take into account gravity near the Earth's surface, as well as the original position and velocity of the object and how much time goes by.

To complete this assignment you will need to write three classes:

• Particle - an instantiable class, which represents a physical object
• ParticleTester - a test class to test your Particle class
• AnimationPlayer - an application class which uses the Particle and (already existing) Animator classes to play some animations

The Particle class is an instantiable class representing a single physical object. Different instances of it will be used to represent distinct physical objects. Each Particle object needs to keep track of its x and y position and its x and y velocity. These values should all be doubles. Another thing that the Particle objects need to keep track of is the starting x and y positions and velocities. This will be needed in order to implement the reset() method which resets the position and velocity back to the ones the particle was given when it was first created (i.e., the ones passed to the constructor).

Constructors

The Particle class must have the following constructor:

• Particle(double xPos, double yPos, double xVel, double yVel) Creates a particle with the given starting position and velocity.

Accessor Methods

The Particle class must have the following public accessor methods, each of which returns the corresponding current (x or y) position or velocity value.

• double getXPosition()
• double getYPosition()
• double getXVelocity()
• double getYVelocity()

Mutator Methods

The Particle class must have the following two public mutator methods:

• void passTime(double seconds) Updates the particle's x and y position and velocity using the equations given above. The parameter seconds indicates how many seconds of time are simulated and the particle's current position and velocity are updated accordingly. For example, suppose that the x and y position and velocity of the object are all zero, except for horizontal (x) velocity which is 2.0. Then a call of passTime(1.0) should cause the particle to update its vertical (y) velocity to -9.8 and its vertical (y) position to -4.9, whereas horizontal (x) velocity and position would both be 2.0 in this case.
  
• void reset() Resets the values of the data members holding the current position and velocity to the same values that this particle was created with.

The Particle class must also have the following public method:

• void print() Prints the a text-representation of the Particle object using System.out.println(). The format must be: Particle at (x, y) with velocity (vX, vY) where x and y are the position components and vX and vY are the velocity components. For example: Particle at (1.7, -1.33333333) with velocity (2.0, 0.0)

There should be a line in your expected.out file for every line printed out by your ParticleTester class.

The Animator class has already been written and is provided to you for use in the AnimationPlayer class. Animator provides methods that let you control which golf animations play (and in what order). Refer to Animator documentation for full details.

You will need to download Animator.jar to the Eclipse folder you are using for programming assignment 1.  (You can do this by right-clicking on the link for Animator.jar and then choosing the "Save Link As..." option.)  After you have downloaded,  you still have one more step to do in Eclipse to get it to recognize the Animator.jar file as one containing Java classes:

• Right-click on your folder for programming assignment 1 and select the "Properties" option.
• A new window titled "Properties for prog 1 name" should appear.  Select the "Java Build Path" option that appears on the left hand side of this window, and click on the "Libraries" tab.
• Click on the "Add External JARs" tab and navigate to (and select) the Animator.jar file.
• Click "OK", after which you will be returned to the Eclipse IDE.

AnimationPlayer class is the application that creates an Animator object and tells the Animator object to play animations for holes 1,7, and 9 in that order. The calls should be made in such a way that each animation turns out to be a hole-in-one. Then a fireworks display should be given. In order to do this you will need to study the appropriate methods from the Animator class in the javadocs. The playerName parameter to the constructor needs to be a string that matches your real name (or both of your names, if you are pair programming). Note that you may need to experiment with the method calls to get all the holes-in-one. Also, you may want to try the fireworks first once you think you have your Particle class working before going on to try the golf animations.

After the animations for the holes of golf are played, the AnimationPlayer class should do the following, in the order given here:

• Print the String that you gave to the Animator object constructor for your name.
• Use the print method of Particle to display the object you used to get a hole-in-one on hole 1.
• Use the print method of Particle to display the object you used to get a hole-in-one on hole 7.
• Use the print method of Particle to display the object you used to get a hole-in-one on hole 9.

For this assignment you are required to generate javadoc documentation (i.e., the html file) for your Particle class. See the section on Generating documentation in Lab 3 for information on how to use Eclipse to generate Javadoc webpages from your source files. Don't forget to look at your Javadoc documentation before you turn it in to make sure it is what you expect!

Make sure also to follow the CS 302 standards for style as well as commenting.

This section lists several questions that should deepen your understanding of the assignment.  Create a text-only file named questions.txt and answer these questions.  Note that some of the questions ask you to try things out in code and give or explain the results you get.  While you can modify your AnimationPlayer class to do this, it is recommended that you make another Java application class and put the code for you use to answer the questions in this new class.

Be sure to include the descriptive information listed below as well as the answers to each question:

Assignment Number:
Assignment Name:
Date Completed:

Partner 1 Name:
Partner 1 Login:
Partner 1 Lecturer's Name:
Partner 1 Lab Section:

Partner 2 Name:
Partner 2 Login:
Partner 2 Lecturer's Name:
Partner 2 Lab Section:

1. What happens if you try to call playHole() with a position or velocity that is out of bounds?
2. Instantiate a Particle at the origin with no velocity and let it fall for 3 seconds by calling passTime 6 times with 0.5 seconds each time. What results do you get (i.e., what are the particle's x and y position and velocity at the end)?  Now run the same experiment again but this time only use a single call to passTime with 3.0 seconds (and give your results). How do the results compare to those you got in the first case? Explain why this phenomenon occurs.
3. Suppose you wanted to simulate getting holes-in-one for holes 1, 7, and 9 on a planet with 1/10th the gravity of earth.  Which of the classes (Particle, Animator, AnimationPlayer) would need to be modified?  Justify your answer.
4. Suppose a programmer wants to update the Animator class so that the initial position and velocity of the ball is displayed in the animation window (in the same format used by the print() method).  Could the print() method of Particle class be used to do this (without modifying the source code for Particle)?  If yes, explain why; if not, explain and suggest a solution (which can involve modifying the Particle class).
5. Have an Animator object animate the same hole twice with two distinct but identical Particles (i.e., same position and velocity, but different objects). Observe what happens when you run the program. Now create just one Particle object and use it in both animations (without calling reset() in between them). Form a guess as to whether or not the same thing will happen. Now observe the results. What happened? Was it what you expected? Why do you suppose it turned out this way?
6. Modify the Particle's passTime method to do absolutely nothing (you can do this by making that section of your code a multi-line comment temporarily). Then run one of the golf animations. What eventually happens? Now run just the fireworks (with no golf holes). What do you observe? (Don't forget to change your passTime method back!)

This section outlines the major requirements of the assignment.  Your solution to the assignment must meet each of these requirements.  Be sure to read the announcements frequently and ask questions if you need clarification.

1. Include name, login, lecture, and lab section information at the top of all assignment files.
2. Follow the style and commenting standards for CS 302.  This includes:
   • including javadoc comments for every portion of the public interface of every class.
   • using symbolic names wherever they are appropriate.
   • using visibility modifiers appropriately; data members should be private and publicly accessible methods should be public.
3. Follow the Particle specifications exactly, i.e., each method you implement must have the correct spelling, the correct return type, and the correct parameter type(s) and must behave according to the specifications.
4. The ParticleTester class must contain code to test every method of the Particle class.
5. The expected.out file must contain the values that you expect the ParticleTester class to print out.
6. The AnimationPlayer class must use the Particle class and the Animator class to display the animations as specified above.
7. Submit your answers to the questions in a text-only file (no Word documents) named questions.txt.
8. Use the Handin program to hand in all work electronically.

• You should do this assignment as a separate project in Eclipse.
• Make sure you read through the entire programming assignment description before you start writing any code.
• After you have read and understand the assignment description, you are ready to start coding.  There are two ways that you can approach writing code:
  • The right way:
    Incremental coding is a way to manage the problems that occur while coding. An incremental coding approach to writing the Particle class is to first add code for the data members and constructor for the Particle class. Then test the Particle constructor (and add the appropriate information to your expected.out file). Next, write the accessor methods and use them to test your Particle class (and update expected.out). Next write one of the mutator methods and test it, then another mutator method and test it, and so on. (In other words, develop your Particle class, ParticleTester class, and expected.out file at the same time, method by method.)  As you are writing your code, don't forget to include appropriate documentation.
  • The wrong way:
    Type in a lot of code at once and then try to compile and run it.  
• Pair Programmers: don't forget to create a text-only README file that provides both students' information.  This file must be handed in to each student's handin directory.

Use the Handin program to hand in your work (see the instructions on how to use the Handin program). Students working in pairs will only submit one copy of all program files, except the README file described below.

Only hand in the files listed below; do not hand in any other files.  These files may be handed in any time prior to the due date.  Note: you may hand in your files before the deadline as many times as you wish.  We suggest you use your handin directory to keep your most recent working copy as you develop your solution.

Required files for this assignment

• Java source code files (program files):
  • Particle.java
  • ParticleTester.java
  • AnimationPlayer.java
  
  
• One javadoc file:
  • Particle.html
  
  
• One text file of expected output:
  • expected.out
  
  
• One text file of answers to the questions:
  • questions.txt
  
  
• Pair Programming students must also submit a README file: All students working in pairs must read the Pair Programming Guidelines and submit a README file.  Each student working in a pair must hand-in this file to his/her own hand-in directory.  Copy, complete, and hand-in the file that is linked here:
  • README.txt