CSC108/A08 Assignment 1

Introduction

The purpose of this assignment is to give you practice in a number of areas:

writing class definitions
thinking up tests for the methods that make up that class definitions
using JUnit to write and run the tests
writing a moderate amount of Java

The classes that you write don't "do" much - they represent a simplified portion of the world (classrooms and audio-visual equipment) according to the specifications below. Most of the "doing" is done by your test cases: the test methods of your testing classes. They create objects of your class type and invoke their methods to prove that the methods work properly. The main purpose here is to get you to think about classes, objects, class (static) methods and object (instance) methods, and to write them all out, along with the tests, to give you lots of pratice in writing Java. Understanding the concepts is easy; getting everything right in Java is the challenge if you've never done it before.

To help you do it right, this description goes into great detail, and will require several readings. Please make sure you understand well what is required; come and see your instructor or your TA if you need more clarification. Be sure to read ALL sections: The Task, Restrictions, What to Hand in, Marking, and the Hints section.

The Task

For this assignment, you are asked to produce four classes: ClassRoom, AVEquipment, ClassRoomTester, and AVEquipmentTester. As you can see by their names, the last two exist in order to test the first two.

For ClassRoom and AVEquipment, an exact specification is given below.

For ClassRoomTester and AVEquipmentTester, we give you general guidelines. Although we don't give you exact instructions, you can read here about the general idea.

Class AVEquipment

This is the simplest class of all. It represents a unit of Audio-Visual Equipment (a projector, a computer console, a DVD player/display unit, etc.):

Variables

Type	Description
`int`	`static` variable. The overall number of AVEquipment units created.
`String`	The type of AV equipment.
`int`	The equipment identification number. The number is unique, and is assigned consecutively as each piece of equipment is created. The id numbers start at 1.

Methods

Constructor	Description
`AVEquipment()`	Constructor for the `AVEquipment` class. Takes no parameters.
`AVEquipment(String)`	Constructor for the `AVEquipment` class. Takes in the equipment type.
Method	Description
`setType(String)`	Set the type of equipment to the given parameter.
`getType()`	Return the equipment type (as a `String`).
`getAVEquipmentID()`	Return the equipment identification number (as an `int`).
`getTotalAVs()`	`static` method. Return the number of `AVEquipment` objects created (as an `int`).
`equals(Object)`	Compares this `AVEquipment` to the given object and return `true` if they have the same equipment identification number; return `false` otherwise.

Class ClassRoom

The ClassRoom class represents a single classroom. It has a number of fields for describing a classroom and for holding useful information about it, and it has methods that manipulate the fields.

The ClassRoom class has the following fields:

Variables

Type	Description
`int`	This room's maximum total capacity (including both standing room and seating) as per fire regulations.
`int`	This room's maximum seating capacity.
`int`	This room's current seating capacity.
`AVEquipment`	This room's AV equipment object. If the room has no AV equipment, its value is `null`. All rooms are created without AudioVisual equipment.
`String`	This room's name (several rooms may have the same name).
`String`	Name of the person this room is assigned to.
`int`	This room's number. The number is unique, and is assigned consecutively as each room is created. The room numbers start at 1.
`int`	`static` variable. Total number of rooms created from this class.
`boolean`	Whether the room is a permanent structure, or a temporary, "portable" classroom.

Methods

The ClassRoom class supports the following methods. Play close attention to the table below! There are two crucial things to remember:

First: while the descriptions given below are informal, they are precise and complete;
Second: your class must have exactly these method names - including the right letter case - and the methods must have exactly these parameters: same order and same type. If you have to, use copy and paste from this page to get it right. (If you don't, our testing programs will not recognize your methods and you will get no credit for them.) As with the variables, we leave the parameter names up to you.

Constructor	Description
`ClassRoom()`	Constructor for the `ClassRoom` class. Takes no parameters. The new classroom may hold 100 people maximum; there is room for at most 75 seats; there is currently seating for 50; its name and its owner's name are the empty string.
`ClassRoom`(int, int)	Constructor for the `ClassRoom` class. Takes in the maximum total capacity and the maximum seating capacity in that order. The current seating capacity is equal to the maximum seating capacity. Its name and its owner's name are the empty string.
`ClassRoom`(int, int, int, String, String)	Constructor for the `ClassRoom` class. Takes in maximum capacity, maximum seating, current seating, room name and owner's name - in that order.
Method Name	Description
`getMaxCapacity()`	Return this room's maximum total capacity (as an `int`).
`getMaxSeating()`	Return this room's maximum seating capacity (as an `int`).
`getCurrSeating()`	Return this room's current seating capacity (as an `int`).
`getExamSeating()`	Return this room's current seating capacity for exams (as an `int`). The exam capacity is defined as the largest integer that is equal to or less than one half of the current seating capacity.
`hasAVEquipment()`	Return whether this room has audiovisual equipment in it (as a `boolean`).
`getRoomName()`	Return this room's name (as a `String`).
`getOwnerName()`	Return this room's owner's name (as a `String`).
`getNumRooms()`	`static` method. Return the total number of classrooms.
`addAVEquipment()`	Creates an AVEquipment unit and adds it to this room. If the room already has AVEqipment the old equipment is replaced by the one created in this method. (The old one is sent to a charity, perhaps.)
`removeAVEquipment()`	Removes this room's AV equipment.
`moveAVUnit(ClassRoom, ClassRoom)`	`static` method. Moves an `AVEquipment` object from one classroom to another. The first parameter is the source classroom, the second the target.
`setRoomName(String)`	Set the room name to the parameter.
`setOwnerName(String)`	Set the owner to the parameter.
`addSeats(int)`	Increase the current seating capacity by the given number of seats. If the resulting number of seats would exceed the room's maximum seating capacity, the current seating capacity is set to the maximum seating capacity.
`removeSeats(int)`	Decrease the current seating capacity by the given number of seats. If the resulting number of seats would be less than 0, the set the current seating capacity to 0.
`hasSameOwner(ClassRoom)`	Return `true` if this classroom has the same owner as the given classroom; return `false` otherwise.
`hasSameAVEquipment(ClassRoom)`	Return `true` if this classroom has the same AV equipment as the given classroom; return `false` otherwise.
`isPortable()`	Return `true` if this classroom is a temporary structure; return `false` otherwise.
`areEquivalent(ClassRoom, ClassRoom)`	`static` method. Return `true` if the given classrooms have the same maximum room capacity and maximum seating capacity; return `false` otherwise.
`equals(Oject)`	Compares this `ClassRoom` to the given object and return `true` if they have the same room number; return `false` otherwise.

As a general rule, none of the inputs to these methods will be null.

Class AVEquipmentTester and Class ClassRoomTester

How do you know whether the AVEquipment and ClassRoom classes you're designing are correct or not? The only way you can be sure is if you test them, to see if they do what they are supposed to do:

For each new method that you add to AVEquipment and ClassRoom, you are expected to write one or more test methods in AVEquipmentTester and ClassRoomTester, respectively. In these methods, you usually create at least one new object and test your method on it.

The AVEquipmentTester and ClassRoomTester are the JUnit test suites you'll design, which perform these testing tasks for you. Lectures and tutorials will introduce you to JUnit - it comes with DrJava. You can also get more detail by following the links on the course main website's Java links page.

Make sure that your test suites adhere to the following principles:

For each method in your class, your AVEquipmentTester and ClassRoomTester classes test suite should have at least one test case that tests that method.
The more interesting a method is, the more test cases you should have for it. What makes a method 'interesting' can be the number of interesting combinations of inputs that a method can have, the number of different results that the method can have when run several times, the different results that can arise when other methods are called before and after this method, and so on.
Test very basic methods early in your test suite, and then move on to more complex ones. (Make sure that the car parts work on their own before you take the whole car for a test drive.)

Remember that if you change static variables in an early test, they will retain their values in later tests. Important: the tests in a JUnit test suite are not necessarily run in the order in which you list them in your suite. So when testing static variables, record their initial value at the beginning of the test, and test that the change in the value is what you expect.

Restrictions

You must not use if statements, loops and arrays. If you do, you will lose marks.

You will find that you can do everything you need to do with the boolean operators (&&, ||, !), and the methods Math.min(int, int) and Math.max(int, int).

Marking

What is important? Several things. While we do not hand out a marking scheme, you need to know what counts for good marks:

Commenting - your files should contain a brief (one-sentence, usually) description of each class, each variable, and each method (this includes your Tester files). The descriptions must be in grammatical, clear English. The specifications above are a good start - often what's there is similar to what you need to write. Remember, more is not necessarily better.
Obviously, your classes and methods have to perform as specified. (In fact, your test suites will ensure this most of the time, but you may miss some test cases.) Correctness, as measured by our tests, will count for the largest single portion of your marks - but less than 50%: having a correct program is just a start. You cannot pass on correctness alone.
Style: there are various aspects to style; in lectures and tutorials we'll cover some of the major points about formatting your files and about naming and spelling conventions. You are expected to satisfy those points.

What to Hand In

Your tutorial or your campus-specific information page describes how you hand in your assignment. This section tells you what to hand in:

Hand in the following four files: AVEquipment.java, AVEquipmentTester.java, ClassRoom.java, ClassRoomTester.java.

Remember that spelling, including case, count in Java: your files must be named exactly as above.

NOTE: Only hand in the files that end with the .java suffix. Be careful about this, because in the same place as your .java files you may also have files with the extension .class (that is, they end with the .class suffix), but otherwise have the same name. Two particular pitfalls:

Microsoft operating systems often do not display file extensions unless they've been told to do so.
DrJava creates "backup files", which means that you'll see filenames like "FamilyMember.java~". The ~ indicates that the file is a backup file, which happens to be an older version of your program.

Since .class files cannot be read by TAs or run with our testing programs, submitting the wrong files might cause you to fail the assignment. Every year, a half-dozen students submit the wrong file; we simply cannot do anything to fix this mistake.

Hints

If you're getting NullPointerException reports and would like to learn more about them, here is some background. (We will not take marks off for these exceptions and reading this section is optional.)

NullpointerExceptions happen when Java is attempting to excute an instruction which makes a reference to an object's method or variable when that object's value is null (the object does not exist). The trick is to make sure to make the reference only if the object exists.

The simplest way to do this would be with an if statement - but we have not covered that yet; and besides, you are not allowed to use if in this assignment.

Hmmmm.

What we want to do is to prevent Java from calling a method or evaluating a variable just in case the owner of that method or variable happens to be null. This is where you can be clever and use the && operator:

When Java is trying to evaluate a boolean expression with this operator, it starts by evaluating the expression on the left side of the operator first. If it finds that the left side is false, it will not bother to evaluate the right side. For example, given

(a == b) && (c < d)

it will first check if a is equal to b. If it is not, then this part is false, and there is no point in seeing whether c is less than d: the whole expression will be false anyway.

So - without giving too much away - you can prevent Java from, for example, calling a method on a null object if you place this method call as the second part of a && expression. The first part of the expression must be such that it is false if the object is null: then the second part will never be executed.