CSSE2002/7023 — Semester 1, 2023Assignment 1: Modelling Space Journeys of the Leaden Matter

School of ITEE CSSE2002/7023 — Semester 1, 2023

Assignment 1: Modelling Space Journeys of the Leaden Matter

Due: 6th of April 2023 at 16:00 AEST

Version: 1.0

Abstract

The goal of this assignment is to implement and test a set of classes and interfaces1.

Q1703105484

Language requirements: Java version 17, JUnit 4.

Preamble

All work on this assignment is to be your own individual work. As detailed in Lecture 1, code supplied by course staff (from this semester) is acceptable, but there are no other exceptions. You are expected to be familiar with “What not to do” from Lecture 1 and https://www.itee.uq. edu.au/itee-student-misconduct-including-plagiarism. If you have questions about what is acceptable, please ask course staff.

Please carefully read the Appendix A document. It outlines critical mistakes which you should circumvent in order to avoid losing marks. This is being heavily emphasised here because these are critical mistakes which must be avoided. If at any point you are even slightly unsure, please check as soon as possible with course staff!

All times are given in Australian Eastern Standard Time. It is your responsibility to ensure that you adhere to this time-zone for all assignment related matters. Please bear this in mind, especially if you are enrolled in the External offering and may be located in a different time-zone.

Introduction

In this assignment, you will take the role of an up and coming programming contractor. Your task will be to build a simple application. The script will take the form of a fictional story, to assist in your understanding of the task. This application is detailed in a specification given to you by the story’s protagonist. For this scenario, you will need to build up a system of classes and interfaces that meet the requirements that you have been given. For this assignment you will be focusing on accessor methods (getter’s and setter’s) as well building an understanding of Lists and basic programming logic.

Story

Hello my dear programmer friend,

I have come to understand that you might be in a position to help me. You see, I feel as if I am in a bit of a rut and have decided that I need to make a life altering change. I am going to resign my position as a celebrity insect therapist and pursue my dream of becoming a starship captain. I have bought a slightly used starship, the Leaden Matter :

From now on, classes and interfaces will be shortened to simply “classes”

Before I take off for a life of adventure beyond the stars, I would like to be able to model my ship, my journeys, and the resources I will be shipping between ports. This is where you come in.

Should you accept, there are a few things that I need you to model:

• Positions in space, as 3d coordinates;
• SpacePorts I can travel to. There are a few types of SpacePort:
  • Generic SpacePorts I can stop at;
  • ShipYards where I can upgrade part of my ship; and
  • Stores where I can buy Resources.
• Spaceships! Spaceships should have two Rooms, each of which can be upgraded to be more effective:
  • The CargoHold, which holds Resources; and
  • The NavigationRoom, where the galaxy map is kept, which allows me to fly or jump to SpacePorts

Rooms on the spaceship are Damageable and take damage when I fly or jump.

• Resources and their Containers, which include Repair Kits and Fuel.

I’m still new at this starship captain thing, so the program needs to be able to tell me when I don’t have enough room to put Resources in my CargoHold; when I don’t have enough resources to fly, jump or repair the ship; or when I’m trying to fly or jump to somwehere that doesn’t exist or is out of range.

Awesome, thanks so much!

• Jesko Thoch

Supplied Material

• • This task sheet.

• • Code specification document (Javadoc).2
  • A video showing the command line interface for the completed model.
  • Gradescope, a website where you will submit your assignment.3
  • A set of supporting files, available for download on Blackboard. These files provide function- ality for some of the trickier parts of the program, and include a text-based user interface that will let you interact with your program once you’ve completed it. These files have been provided so that you can avoid (some of) the critical mistakes described in Appendix A.

Each of these files:

• • • is in the correct directory (do not change this!)
    • has the correct package declaration at the top of the file (do not change this!)
    • has the correct public class or public interface declaration. Note that you may still need to make classes, extend classes, implement interfaces etc., as detailed in the Javadoc specification.

As the first step in the assignment (after reading through the specifications) you should download the template code from Blackboard. Once you have created a new project from the files you have downloaded, you should start implementing the specification.

Javadoc

Code specifications are an important tool for developing code in collaboration with other peo- ple. Although assignments in this course are individual, they still aim to prepare you for writing code to a strict specification by providing a specification document (in Java, this is called Javadoc).

You will need to implement the specification precisely as it is described in the specification docu- ment.

To view the Javadoc, navigate to the relevant assignment folder under Assessment on Blackboard and you will be able to download the Javadoc .zip file containing HTML documentation. Unzip the bundle somewhere, and open doc/index.html with your web browser.

Tasks

1. Fully implement each of the classes and interfaces described in the Javadoc.
2. Write JUnit 4 tests for all the methods in the following classes:
   • Position (in a class called PositionTest)
   • ResourceContainer (in a class called ResourceContainerTest

Marking

Your grade for the assignment will be determined based on your achievement in a number of categories, as shown in Tables 1 and 2.

Please note that Code Style grades are capped at the level of your Functionality grade. The reasoning here is to place emphasis on good quality functional code. Well styled code that does not implement the required functionality is of no value in a project, consequently marks will not be given to well styled code that is not functional.

iled in the Javadoc section

3Detailed in the Submission section

Table 1: Marking schema components

Symbol	Marked	Description
FT	Electronically	Functionality according to the specification
CF	Electronically	Conformance to the specification
CS : SL	Electronically	Code style: Structure and layout
CS : CR	By course staff	Code style: Style Guide Compliance
JU	Electronically	Whether JUnit tests identify and distinguish between correct and incorrect implementations

Functionality Marking

Functionality evaluates if you have correctly implemented classes, properties and methods accord- ing to the specification.

Conformance

Conformance is marked by identifying conformance violations in your code. Note that multiple conformance violations of the same type will each be counted as separate violations.

Conformance violations include (but are not limited to):

• Placing files in incorrect directories.
• Incorrect package declarations at the top of files.
• Using modifiers on classes, methods and member variables that are different to those specified in the Javadoc. Modifiers include private, protected, public, abstract, final, and static. For example, declaring a method as public when it should be private.
• Adding extra public methods, constructors, member variables or classes that are not de- scribed in the Javadoc.
• Incorrect parameters and exceptions declared as thrown for constructors.
• Incorrect parameters, return type and exceptions declared as thrown for methods.
• Incorrect types of public fields.

Code Style

Code Structure and Layout

The Code Structure and Layout category is marked by identifying violations of the style guide in your code. Style violations in your solution will be detected and counted by CheckStyle using the course-provided configuration4. Note that multiple style violations of the same type will each be counted as separate violations.

Note: There is a plugin available for IntelliJ which will highlight style violations in your code. Instructions for installing this plugin are available in the Java Programming Style Guide on Black- board (Learning Resources → Guides). If you correctly use the plugin and follow the style require- ments, it should be relatively straightforward to get high marks for this section. IntelliJ will also give you hints in the correct direction. Ensure you know the difference between a checkstyle and IntelliJ hint.

he latest version of the course CheckStyle configuration can be found at http://csse2002.uqcloud.net/ checkstyle.xml. See the Style Guide for instru

5

Table 2: Marking Schema

Level              of Achievement	FTa	CF	CS:SLb	CS:CR	JU	Overall
Exceptional (7)	At  least  85%  of  tests are successful across all classes	Expert                        confor- mance    (no    more than 2 violations)	Mastery of style (no more than 4 viola- tions)	Variable naming is masterful. Comments are significantly nu- merous, meaningful, detailed and useful. Code design follows best practice. Programming fol- lows best practices.	See JUnit Testing Marking section for	FT 7; CF 6+; CS 6+; JU 6+
Advanced (6)	At  least  75%  of  tests are successful across all classes	Extensive                        confor- mance    (no    more than 3 violations)	Extensive  compli- ance with style (no more than 6 violations)	Variable naming is substantially appropriate. Comments are ex- tensively numerous, meaningful, detailed and useful. Code design is substantially approaching best practice. Programming substan- tially approaches best practice.	details.	FT 6+; CF 5+; CS 5+; JU 5+
Proficient (5)	At  least  65%  of  tests are successful across all classes	Good conformance (no more than 4 vi- olations)	Good                compliance with style (no more than 8 violations)	Variable naming is good. Com- ments are generally meaningful, detailed and useful. Code design is good. Programming practices are good.		FT 5+; CF 4+; CS 4+; JU 4+
Functional (4)	At  least  8  classes  ex- hibit expected functional- ity with few to no mistakes in implementation	Adequate                        confor- mance    (no    more than 5 violations)	Adequate  compli- ance with style (no more than 10 violations)	Adequate compliance with style (no more than 7 violations)		All components 4+
Developing (3)	At  least  7  classes  ex- hibit expected functional- ity with few to no mistakes in implementation	Superficial confor- mance    (no    more than 6 violations)	Superficial compli- ance with style (no more than 12 viola- tions)	Variable naming is adequate. Commenting is superficial. Code design is adequate. Program- ming practices are adequate.		All components 3+
Minimal achievement (2)	At  least  6  classes  ex- hibit expected functional- ity with few to no mistakes in implementation	Deficient                        confor- mance    (no    more than 7 violations)	Deficient  compli- ance with style (no more than 14 violations)	Variable  naming  is  deficient. Commenting is deficient. Code design is deficient. Programming practices are deficient.		All components 2+
Absence          of achievement (1)	No demonstrated evidence of ability to apply concepts in the field of study.

 

aCS component grades will be capped at the level of FT grade.

bIf FT or CS:SL show Absence of Achievement, CS:CR will automatically receive 1

Code Review

Your assignment will be style marked with respect to the course style guide, located under Learning Resources → Guides. Common mistakes are listed in Table 3.

Note that style marking does involve some aesthetic judgement (and the marker’s aesthetic judge- ment is final).

Note that the plugin available for IntelliJ mentioned in the Code Structure and Layout section cannot tell you whether your code violates style guidelines for this section. You will need to man- ually check your code against the style guide.

JUnit Test Marking

See Appendix B for more details.

The JUnit tests that you provide in PositionTest and ResourceContainerTest will be used to test both correct and incorrect implementations of the relevant classes. Marks will be awarded for test sets which distinguish between correct and incorrect implementations5. A test class which passes every implementation (or fails every implementation) will likely get a low mark. Marks will be rewarded for tests which pass or fail correctly.

The test program will first see how many of your tests pass against a correct solution. Then, out of those tests that did pass against the correct solution it will run them against one (or more) faulty solutions. A faulty solution is a complete solution apart from some small changes that go against the specification.

Your tests should fail more test cases against this faulty solution then the correct solution. There will be some limitations on your tests:

1. If your tests take more than 20 seconds to run, or
2. If your tests consume more memory than is reasonable or are otherwise malicious,

then your tests will be stopped and a mark of zero given. These limits are very generous (e.g. your tests should not take anywhere near 20 seconds to run).

Electronic Marking

The electronic aspects of the marking will be carried out in a Linux environment. The environment will not be running Windows, and neither IntelliJ nor Eclipse (or any other IDE) will be involved. OpenJDK 17 will be used to compile and execute your code and tests.

It is critical that your code compiles.

If your submission does not compile, you will receive zero for Functionality (FT).

Submission

How/Where to Submit

Submission is via Gradescope.

Instructions for submitting to Gradescope will be made available on Blackboard (under Assessment

→ Assignment 1) in week 5. You will not be able to submit your assignment before then.

d get them the right way around

Table 3: Common errors in Style Guide Compliance

Metric	How it is marked
Naming	Misnamed variables e.g. → Non-meaningful or one-letter names String temp; // bad naming char a; // bad naming int myVar, var, myVariable; // all bad naming → Variable names using Hungarian notation int roomInteger; // bad naming List<Gate> gateList; // bad naming (‘gates’ is better)
Commenting	Javadoc comments lacking sufficient detail e.g. → Insufficient detail or non-meaningful Javadoc comments on (any) classes → Insufficient detail or non-meaningful Javadoc comments on (any) methods → Insufficient detail or non-meaningful Javadoc comments on (any) construc- tors → Insufficient detail or non-meaningful Javadoc comments on (any) class vari- ables → etc. Lack of inline comments, or comments not meaningful e.g. → There needs to be sufficient comments which explain your code so that someone else can readily understand what is going. Someone should not need to guess or make assumptions. → Lack of inline comments, or comments not meaningful in methods → Lack of inline comments, or comments not meaningful in constructors → Lack of inline comments, or comments not meaningful for variables → etc.
Code Design	Code design issues e.g. → Using class member variables where local variables could be used → Duplicating sections of code instead of extracting into a private helper method → Having functions that exceed 100 liens in length → Class content is laid out in a way which is not straightforward to follow → Methods are laid out in Classes or Interfaces in a way which is not straight- forward to follow → Method content is laid out in a way which is not straightforward to follow → Variables are not placed in logical locations
Programming Practices	Programming Best Practices issues e.g. → Using class member variables where local variables could be used → Incorrect use of inheritance by duplicating code → Incorrect exception handling → Using magic numbers without explanatory comments object.someMethod(50); // what does 50 mean?       What is the unit/metric?

You must ensure that you have submitted your code to Gradescope before the submission deadline. Code that is submitted after the deadline will be subject to a late penalty, as per the ECP.

You may submit your assignment to Gradescope as many times as you wish before the due date, however only your last submission made before the due date will be marked.

What to Submit

Your submission should have the following internal structure:

src/         folders (packages) and .java files for classes described in the Javadoc

test/        folders (packages) and .java files for the JUnit test classes A complete submission would look like:

src/srg/exceptions/InsufficientCapacityException src/srg/exceptions/InsufficientResourcesException src/srg/exceptions/NoPathException src/srg/ports/Position src/srg/ports/ShipYard src/srg/ports/SpacePort src/srg/ports/Store src/srg/resources/FuelContainer src/srg/resources/ResourceContainer src/srg/ship/CargoHold src/srg/ship/Damageable src/srg/ship/NavigationRoom src/srg/ship/Room src/srg/ship/Ship test/srg/ports/PositionTest             (Note test directory, not src!) test/srg/resources/ResourceContainerTest

e that your classes and interfaces correctly declare the package they are within. For example,

Position.java should declare package srg.ports.

Do not submit any other files (e.g. no provided .java files, no .class files).

Note that your JUnit tests will be compiled individually against a sample solution without the rest of your test files.

Provided set of unit tests

A small number of the unit tests (about 10-20%) used for assessing Functionality (FT) (not con- formance, style, or JUnit tests) will be provided in Gradescope prior to the submission deadline, which you will be able to test your submission against.

The purpose of this is to provide you with an opportunity to receive feedback on whether the basic functionality of your classes is correct or not. Passing all the provided unit tests does not guarantee that you will pass all of the full set of unit tests used for functionality marking.

Instructions about the provided set of unit tests will be made available on Blackboard (under Assessment → Assignment 1) when these are available.

Late Submission

Assignments submitted after the submission deadline of 16:00 on 6th of April 2023 will attract a late penalty as described in the Electronic Course Profile — see the Electronic Course Profile for details.

Do not wait until the last minute to submit the final version of your assignment. A submission that starts before 16:00 but finishes after 16:00 will be penalised. Exceptions cannot be made for individual students, as this would not be fair to all other students.

Assignment Extensions

All requests for extensions must be made via my.UQ as outlined in section 5.3 of the respective Electronic Course Profile. Please do not directly email the course coordinator seeking an extension (you will be redirected to my.UQ).

Remark Requests

To submit a remark of this assignment please follow the information presented here: https://my.uq.edu.au/information-and-services/manage-my-program/exams-and-assessment/   querying-result.

Please be aware that remarks can result in your mark decreasing or remaining the same, not just increasing.

Revisions

If it becomes necessary to correct or clarify the task sheet or Javadoc, a new version will be issued and an announcement will be made on the Blackboard course site.

Appendix A: Critical Mistakes which can cause loss in marks. Things you need to avoid!

This is being heavily emphasised here because these are critical mistakes which must be avoided.

We use an automated tool for marking the functionality of your assignment. This appendix provides information to help you avoid common errors.

Code may run fine locally on your own computer in IntelliJ, but it is required that it also builds and runs correctly when it is marked with the electronic marking tool in Gradescope. Your solution needs to conform to the specification for this to occur.

Correctly reading specification requirements is a key objective for the course.

• Files must be in the exact correct directories specified by the Javadoc. If files are in incorrect directories (even slightly wrong), you may lose marks for functionality in these files because the implementation does not conform to the specification.
• Files must have the exact correct package declaration at the top of the file. If files have incorrect package declarations (even slightly wrong), you may lose marks for functionality in these files because the implementation does not conform to the specification.
• You must implement the public and protected members exactly as described in the supplied documentation (no extra public/protected members or classes). Creating public or protected data members in a class when it is not required will result in loss of marks, because the implementation does not conform to the specification.

– Private members may be added at your own discretion.

• Never import the org.junit.jupiter.api package. This is from JUnit 5. This will auto- matically cause the marks for the JUnit section to be 0 because JUnit 5 functionality is not supported.
• Do NOT use any version of Java newer than 17 when writing your solution! If you accidentally use Java features which are only present in a version newer than 17, then your submission may fail to compile when marked. This will automatically cause the marks for associated files with this functionality to be 0.

Appendix B: How your JUnit unit tests are marked.

The JUnit tests you write for a class (e.g.PositionTest.java) are evaluated by checking whether they can distinguish between a correct implementation of the respective class (e.g. Po- sition.java) (made by the teaching staff), and incorrect implementations of the respective class (deliberately made by the teaching staff).

First, we run your unit tests (e.g. PositionTest.java) against the correct implementation of the respective classes (e.g. Ship.java).

We look at how many unit tests you have, and how many have passed. Let us imagine that you have 9 unit tests for PositionTest.java and 7 unit tests for ResourceContainerTest.java; and they all pass (i.e. none result in Assert.fail() in JUnit4).

We will then run your unit tests in both classes (PositionTest.java, ResourceContainerTest.java) against an incorrect implementation of the respective class (e.g. ResourceContainer.java). For example, the constructor in the ResourceContainer.java file is incorrect.

We then look at how many of your unit tests pass.

PositionTest.java should still pass 9 unit tests. However, we would expect that ResourceContain- erTest.java would pass fewer than 7 unit tests.

If this is the case, we know that your unit tests can identify that there is a problem with this specific implementation of ResourceContainer.java.

This would get you one identified faulty implementation towards your JUnit mark.

The grade you receive for JUnit is based on the correct number of identified faulty implementa- tions, out of the total number of faulty implementations which the teaching staff create.