This assignment gives you practice with writing functions whose bodies have
assignment statements, conditional statements, and blocks. You will be
working with one class, TimeZones.
You may work with one partner. If you do, get on the CMS several days before the assignment is due and follow directions for forming a group. Don't wait until the last minute to do this; do it several days before you want to submit the assignment.
This is (very, very roughly) a 10-hour assignment. Plan accordingly. Please keep track of your time and, just before you submit, tell us how many hours you took in a comment at the top of the class. Spend an hour reading this handout so that you thoroughly understand what we are asking for. Do this with your partner before you start programming! We strongly suggest that you and your partner alternate writing the methods (but with the other person watching and helping). You will both benefit from this, even if you find it feels like it is taking longer.
You must also produce a class TimeZonesTester that contains your
test cases. You must include enough test cases to be sure that your program
is correct. When you start on a method, think of the test cases you will need
to test the method and write the assertEquals statements before
writing the method body. Add more test cases as you write the method body to
ensure that there is complete test coverage —so that each statement in
the method body is exercised during at least one test case.
Note on extra (private) methods. You are allowed to write any private methods that you wish. Whenever you write a program, as you proceed, you may find it helpful to add new methods in order to keep other methods simple and understandable. You saw this in the program to anglicize integers, which we developed in class on Tuesday, 19 September.
Class TimeZones
You will write the bodies of several functions in class TimeZones.
To help you out, we give you
a skeleton: a class with all the methods specified but with some stubs
for bodies (empty body or simply a return statement), so that the program
is syntactically correct and will compile. All the methods are fully specified.
Look at them carefully; they are so complete that one can write the method
body based on the specification. This is how you should write your method
specifications. You can also see the Javadoc
specifications for the program. Get these from the course web page or
from the CMS.
An instance of class TimeZones represents a time in some time zone. The time zones that are implemented are:
Indian Standard Time (IST) is included to show that times are not always on hourly boundaries from GMT. Some time may appear negative or greater than 24 hours. This is because we allow a conversion of a time from one time zone to another, and a time of 0 hours GMT is –7 hours PDT (for example), while a time of 23:59 GMT is 29:29 IST. See the comment on the class for a complete specification. Look at this website to see the time in any time zone in the world: http://www.worldtimezone.com/
Note that time zone is "GMT", but "gmT" is not a time zone. This should be clear from the specification of the class, which lists what time zones are allowed.
An instance of the class can show you the time using a 24-hour clock or using the AM-PM designation; it is the user's choice.
Study the specification of the class and its methods carefully, to get an overall view of what the class is for. For this purpose, use either the skeleton or, better, the JAVADOC spec for it.
Restriction on times. Any time that is given in a new expression new TimeZones(...) will
be > –24
hours (–1 day) and < 48 hours (2 days) —otherwise, 0 is
used. This restriction applies only to values given as arguments in
constructor calls. That is the only place restrictions are given in the specification.
An internal time may get out of that range. For example, if you create a folder
with time 47 hours GMT and then convert it to India time, the India time will
be 53 hours and 30 minutes. However, the restriction on times does imply that
any hour of a time to be printed takes at most two digits.
This assignment will be presented as a series of tasks. Finish each task completely before proceeding to the next. And, wherever it is possible, write each method in an incremental fashion. This holds especially for method toString, which is quite complicated. Test each method carefully and thoroughly, using the Interactions Pane, before proceeding to the next.
Task 1: getter methods
You can see in the skeleton that we have given you two completed two constructors
(and one that is uncompleted). Therefore, you can create instances of the
class, but you can't get anything out of them. So, your first task is to
complete getter methods getTime, getZone, and getAmPm.
Once they are properly written, check them out, by writing suitable test
cases in class TimeZoneTester. Note that you don't really have
to think about testing the two constructors because they were given to you
as correct.
Task 2: function toString.
Now, write function toString. You MUST follow its specification
carefully. Don't just blindly make it do what you want; implement it to be
consistent with the specification. To help you out, we have put in
the body of toString a sequence of statement-comments that, together,
do what the body is supposed to do. All you have to do is implement these statement-comments.
Of course, if you want, start with an empty body and do it the way you want.
But it must be correct!
After you write function toString, test it thoroughly, with instances
of the class for negative times, times in the range 0..24, and times greater
than 24 hours. Also, test these with both modes of output —24-hour clock and
12-hour clock. This function MUST be correct before you proceed.
Rules for function toString. We present below rules to be followed in the output of function toString.
(a) If the time is negative, then a 24 hour clock is to be used. Further, only ONE – sign is to appear. For example, here are two times and how they should be displayed:
– 48370 seconds, i.e. (–13 hours, –26 minutes, –10 seconds) in GMT :
"–13:26:10 GMT"
– 36970 seconds, i.e. (–10 hours, –16 minutes, –10 seconds) in GMT :"–10:16:10 GMT"
(b) Precede a positive time by one blank. Here is a positive time and a negative time:
36970 seconds, i.e. (10 hours, 16 minutes, 10 seconds) in GMT :
" 10:16:10 GMT"
– 36970 seconds, i.e. (–10 hours, –16 minutes, –10 seconds) in GMT :"–10:16:10 GMT"
(c) The hours, minutes, and seconds MUST each be two digits. Examples
0 hours, 5 minutes, 16 seconds in GMT :
"00:05:16 GMT"
6 hours, 15 minutes, 6 seconds in GMT :"00:15:06 GMT"
(d) The time 0 is midnight. It is usually thought of as AM, so print time 0 in 12-hour time with an AM indication. Similarly, noon is the beginning of PM, so it should be printed in 12-hour time with a PM indication.
Note: If the time is between –hours and –10 hours, prepending a leading 0 can be tricky. Be careful.
Note: It may be advantageous to write an auxiliary private function that, given a string that contains an unsigned integer, returns a string that represents the same unsigned integer but has length at least two (it prepends a leading 0 if necessary). You can then call this function in several different places.
Task 3: function isLegal.
Users may give time zones that are not legal. The purpose of private function
isLegal is to test whether its parameter is one of the legal time
zones, returning true if it is and false if it is not. Implement this function.
Be sure to test it on ALL possible legal zones, as well as illegal ones, before
proceeding to the next step. To test it, note that the second constructor
calls isLegal, so, you can test isLegal using
the constructor. Hint: Here's one way to think about writing isLegal.
Can you use one of the String functions to search for a zone in some string?
Task 4: procedure setDisplay.
This procedure should be easy to write and test. It is a simple setter method.
Task 5: the third constructor.
Up to now, any instance you created had either time 0 or a time for which you
gave a number of seconds. Now implement the third constructor, the one that
has 5 parameters. Use the second constructor as an example in writing this
one. Test it thoroughly before proceeding.
Parameters h, m, and s of this constructor
are the hours, minutes, and seconds of a time. No restriction is given on these
parameters individually, so there is no need to do any checking of them individually.
The only restriction is that when the given time is translated into seconds,
the result be > –24 hours (ie. –1 day, or whatever that is in
seconds) and < 48 hours (i.e.
2 days, or whatever that is in seconds).
To translate h hours,
m minutes, s seconds to a time in seconds, convert
all three values to seconds and add them together. This implies
that h = 48, m = 0, and s = 1 is an
illegal time, because it is greater than 2 days. Also, h = 48, m =
0, s = –1 is a legal time, because it is 1 second less
than 2 days.
Task 6: function timeInZone.
This function is given a time in one zone and is asked to create a new TimeZones
instance that has the same time but in a different time zone. To help you out,
take a look at function timeInGMT. It does roughly the same thing but always
converts to GMT time. Function timeInGMT should give you an idea how to write
function timeInZone. Here's a point to ponder. You have to translate from ANY
time zone to ANY OTHER time zone. How many possibilities are there? Can you
make use of function timeInGMT to simplify the task? Make sure you test this
method thoroughly before proceeding in to the next task.
Task 7: function compare.
Finally, you have to implement function compare. Of course, it
has to satisfy its specification. Note that time 18:00 GMT is the same as
time 13:00 EST. You can't really compare the times until they are both converted
to the same time zone. What's the simplest way to do that?
Task 8. Finishing up and submitting.
You have written all the methods. You see how a class filled with methods can
be written one method at a time, in order to come up with a neat little
class. Now, go over your program once more, as follows:
(1) Make sure the indentation is correct —use DrJava's indenting feature if you want.
(2) Make sure that the comments are suitable (we gave most of them to you), by clicking the javadoc button in DrJava and then looking carefully at the class and method specifications to be sure they are correct.
(3) Look once more at the test cases you put into class TimeZonesTester.java and
make sure you have enough suitable test cases.
(4) Put a comment at the front of class TimeZones that indicates how many hours you worked on the assignment.
(5) Submit files TimeZones.java. and
TimeZonesTester.java. Make sure you submit the .java file, and
not the .class or the .java~ file!!!!!