---

Student Assignment Solutions

This is your personal student repository which will be used to submit solutions for the course's three lab assignments, as well as its final project. This repo is completely private, meaning none other than you and the teachers have access to it. As you've completed a particular assignment and wish to have its solution evaluated, you'll need to perform a formal hand-in using the dedicated submission box in Moodle. Nothing should be attached to this submission in Moodle, as the current solution state will be fetched from this repository. So make sure to synchronize any local changes with remote origin before submission.

Just as in previous courses you're encouraged to isolate development to dedicated branches, and only merge with master upon submitting your solution for evaluation. This will enable greater degree of experimentation since the stable states are preserved, and readily available at all times. Do note that evaluations will only be performed on the solutions available in this master branch, which for our purposes is regarded as the release branch.

Please write a short presentation in the dedicated section at the end of this document!

---

Structure of Repository

studid_solutions/   (1)
  _playground/      (2)
  _RepoResources/   (3)
  Laboration_X/     (4)
  Project/          (5)
  .gitignore        (6)
  pom.xml           (7)
  README.md         (8)

Laboration_X/       (9)
  src/main/         (10)
    /resources/     (11)
  src/test/         (11)
    /resources/     (12)
  pom.xml           (12)
  README.md         (13)

1. Root of repository.
2. All contents in this folder will be ignored by version control, as long as the .gitignore remains untouched. This is a good place to just play around with scripts, which are not meant to be viewed by others.
3. General resources for the repository, not to be confused with resources for tests and / or Java. An example of usage can be seen at the top of this document, where an image is pulled from /img/badge_miun.png.
4. Directory for laboration content, further explained in points 9 - 13. Note that the same structure is used for the final project.
5. Directory for final project. Further details surrounding the structure will be explained once the assignment has been published.
6. Patterns to be ignored from version control, such as project files generated by the IDE. Existing contents of this file should be general enough to cover most circumstances, but feel free to add more if the need arises.
7. The parent Maven script. Note that we use a distributed system, where we have subscripts in each module.
8. The document you're currently reading.
9. Main directory for assignment content, where 'X' indicate a sequence number for the laboration. There are a total of four assignments in the course and each one represents a nested Maven module within the parent project.
10. This is where you store java files and resources needed for the solutions. Note that source documents (.java) needs to be placed under folder java, which is explicitly marked as Sources Root, and its package name. Ex: java/com/dt181g/laboration_1/Lab1.java.
11. Root resource folder. This is where you add resources which are important to the application, such as images and data files. Note that these resources will be bundled inside the JAR, so only read-access is allowed. You also need to make sure to load resources properly using class loader.
12. This is where we place unit tests. The use of unit tests are not mandatory, but strongly recommended. The structure enables you to add tests as you wish, but you need to be the one writing them.
13. Root test resource folder. Same as for source files, but for testing purposes.
14. Maven script for the lab module, deriving from parent pom.xml in project root.
15. README which needs to contain a written report, in conformity to requirements which are stated in the study guidance.

---

Markdown in Reports

Bitbucket offers very limited support for HTML-tags so you need to avoid them, and instead fully rely on ordinary Markdown syntax. For example, if you would like to present some code in your lab reports you should not enclose it within <pre>. The same goes for tags used to structure content, such as <center>. If you really want more control over the presentation, you should instead utilize stylesheets (.css) as we did in DT179G, but it's not needed as plain Markdown will suffice.

In general, you shouldn't include much code in your reports as it represents implementation details which would not scale well with a larger project. It will also add redundancies since we already have access to the solution, and you can easily imagine how bloated the report becomes if all code is repeated. However, in some situations it can be justified to include some snippets to illustrate an approach or to strengthen a case. But be sure to use proper Markdown:

public class ShowCase {
  public static void main(String[] args) {
    System.out.println("Hello World!");
  }
}

---

Maven

As in DT180G we'll rely heavily on Maven throughout the course, but won't dive into the specifics since it doesn't fit within the current course scope. Build / management tools such as Maven is a rather vast subject to cover, and since it's strictly governed by a large set of rules one would also need to reach some proficiency with its declarative syntax. In order to learn any new technology it's always important to strip away complexities and start from the very fundamentals. This repo uses a modularized implementation, of one base project and multiple sub-projects, which makes its structure unsuitable as learning material.

The modularized structure you find in this repo is in a somewhat stable state, and will have improved once we reuse it for later iterations. We have a parent pom.xml in the main root which declares dependencies, build process, and report generations to be used in our sub modules. These sub modules will have their own pom.xml that inherits the configurations from the parent script. There shouldn't be any reason for you to change anything in these documents, and the current structure has been verified to work in both Windows 10 and OSX Big Sur running openjdk 15.0.2 and Apache Maven 3.6.3.

Maven builds follow specific life cycles, which in turn are constituted out of multiple phases which are exectuted in sequence. There are three built-in life cycles:

• default: the main life cycle as it's responsible for project deployment. Consists of 23 phases in total.
• clean: to clean the project and remove all files generated by the previous build. Consists of 3 phases in total.
• site: to create the project's site documentation. Consists of 4 phases in total.

Phases

A Maven phase represents a stage in the Maven build lifecycle. Each phase is responsible for a specific task. Here are some of the most important phases in the default build lifecycle:

• validate: check if all information necessary for the build is available
• compile: compile the source code
• test-compile: compile the test source code
• test: run unit tests
• package: package compiled source code into the distributable format (jar, war, …)
• integration-test: process and deploy the package if needed to run integration tests
• install: install the package to a local repository
• deploy: copy the package to the remote repository

For the full list of each lifecycle's phases, check out the Maven Reference.

Phases are executed in a specific order. This means that if we run a specific phase using the command mvn <PHASE> it won't only execute the specified phase but all the preceding phases as well. For example, if we run the deploy phase mvn deploy, which is the last phase in the default build lifecycle, that will execute all phases before the deploy phase as well, which is the entire default lifecycle.

Goals

Each phase is a sequence of goals, and each goal is responsible for a specific task. When we run a phase, all goals bound to this phase are executed in order. Here are some of the phases and default goals bound to them:

• compiler:compile the compile goal from the compiler plugin is bound to the compile phase
• compiler:testCompile is bound to the test-compile phase
• surefire:test is bound to test phase
• install:install is bound to install phase
• jar:jar and war:war is bound to package phase

We can list all goals bound to a specific phase and their plugins using the command mvn help:describe -Dcmd=PHASENAME. For example, to list all goals bound to the site phase, we can run mvn help:describe -Dcmd=site which would output info such as:

'site' is a phase within the 'site' lifecycle, which has the following phases: 
* pre-site: Not defined
* site: org.apache.maven.plugins:maven-site-plugin:3.3:site
* post-site: Not defined
* site-deploy: org.apache.maven.plugins:maven-site-plugin:3.3:deploy

Maven Plugins

A Maven plugin is a group of goals. However, these goals aren't necessarily all bound to the same phase. We can infact control these details to a high degree by encapsulating plugins within specific tags in our pom.xml. The tag <build> is used for plugins which are involved in our compilation of .jar files, while those declared within <reporting> will be tied to our site phase.

• maven-site-plugin: The Site Plugin is used to generate a site for the project. The generated site also includes the project's reports that were configured in the POM.
• maven-project-info-reports-plugin: The Maven Project Info Reports plugin is used to generate reports information about the project.
• maven-javadoc-plugin: The Javadoc Plugin uses the Javadoc tool to generate javadocs for the specified project. For more information about the standard Javadoc tool, please refer to Reference Guide.
• maven-checkstyle-plugin: The Checkstyle Plugin generates a report regarding the code style used by the developers. For more information about Checkstyle, see its official homepage.
• maven-surefire-plugin: The Surefire Plugin is used during the test phase of the build lifecycle to execute the unit tests of an application. It generates reports in two different file formats: .txt and .xml.
• maven-surefire-report-plugin: The Surefire Report Plugin parses the generated TEST-*.xml` files under **${basedir}/target/surefire-reports``** and renders them using DOXIA, which creates the web interface version of the test results.
• maven-jar-plugin: This plugin provides the capability to build jars.
• maven-compiler-plugin: The Compiler Plugin is used to compile the sources of your project.
• maven-project-info-reports-plugin: The Maven Project Info Reports plugin is used to generate reports information about the project.

The Commands We Will Use

For our purposes we'll mostly rely on the phases clean, verify, and site. All output generated from these phases, and their inherent goals, will be placed under directory target/, for which there are one for each module. Since their contents will be generated on local systems, they are excluded from version control. It will be a good idea to always include clean for any commands you run, since it will remove lingering files from previous output. Simply running mvn clean from repo's root will effectively delete all target/ in the project hierarchy.

mvn site

The aim has been to minimize the amount of Maven commands you need to learn and in terms of generating reports we've consolidated JavaDoc, Checkstyle, and Surefire under the shared site goal. If you run mvn clean site from the repo's root this will traverse all modules and generate reports for these plugins, and link necessary pages to one another. You can open the generated site pages from the root's target/:

/target/site/index.html

When you open this page in a browser you'll find some general information about the project and its modules, but the important stuff will be under Project Reports, accessed from the navigation menu to the left. Under the Overview of this page you'll find two reports: JavaDoc and Surefire Report. Both of these contains information which has been aggregated from each sub module in the project, where the first contains documentation of packages, classes, interfaces and methods, while the latter contains outcomes from running unit tests. Both of these report types will be relevant once you've progressed into the third and fourth learning modules in the course.

You can also see that one report seems to be missing from this main overview. The plugin Checkstyle has been configured to be inherited to each sub module, not aggregated as the other two, which means that its reports can only be accessed from each sub module's target/:

/target/site/checkstyle.html

It would of course be nice if these reports also were included in the main aggregation, and perhaps we can find a way to make it possible for the upcoming course DT181G. In the mean time, just be aware that these reports has a different placing. Also note that we use sun_checks.xml for our linting purposes, which can be somewhat pedantic about certain issues. For instance, it will raise warnings about line lengths exceeding 80 characters and that private data members lacks documentation. These two issues can mostly be ignored since you would normally not document private members, only the shared interface (public and protected). When it comes to line lengths, there are of course limits... but as long as you restrict to a maximum of 120 characters it will be fine.

When generating JavaDoc, Maven may throw an ERROR stating broken link to javadoc-bundle-options.
You may ignore this error since it regards creation of JavaDoc jar for publishing to Maven repositories.

mvn verify

In order to build our solutions to executables (.jar) we can use the Maven command mvn clean verify. If ran from the repo's root, this will generate a .jar for each sub module which can be found under respective target/. The path for Laboration 1 would thus be:

laboration_1/target/laboration_1-1.0-SNAPSHOT.jar

The maven-jar-plugin will make sure we have included a manifest attribute stating which class should be the main execution. You can execute this .jar from the target/ directory:

java -jar laboration_1-1.0-SNAPSHOT.jar

So, you would use the following commands with Maven:

Command	Description
$ mvn clean	deletes all contents under 'target/'
$ mvn clean verify	runs tests, builds and compiles source files into 'jar'.
$ mvn clean site	runs tests, generates JavaDoc and reports for Checkstyle and Surefire.

You can also make more fine grained executions by stating specific goals:

$ mvn javadoc:javadoc         # only generate JavaDocs
$ mvn checkstyle:checkstyle   # only run code linting
$ mvn surefire:test           # only run unit tests

---

About the Author

Please write a short presentation. Suitable content would be...

• ... who you are.
• ... previous programming experiences.
• ... your expectations regarding this course.