Skip to content

Latest commit

 

History

History
290 lines (236 loc) · 17.2 KB

README.md

File metadata and controls

290 lines (236 loc) · 17.2 KB
Raw

MIUN DT179G

Version MIT license JetBrains java vcs Bitbucket made-with-Markdown

Student Assignment Solutions

This is your personal student repository which will be used to submit solutions for the course's three lab assignments. 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 DT179G 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)
  src/test/         (11)
  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.
  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 laboration content, where 'X' indicate a sequence number. There are a total of three lab 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/dt180g/laboration_1/Lab1.java.
  11. This is where we place unit tests, which will be relevant for laboration 2 and 3. The first lab assignment does not have this structure, and is excluded from tests as stated in its pom.xml.
  12. Maven script for the lab module, deriving from parent pom.xml in project root.
  13. README which needs to contain a written report, in conformity to requirements which are stated in 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

We will rely heavily on Maven throughout both this and the upcoming course DT181G, but won't dive into the specifics until the later DT042G. The Moodle page for the course's initial learning module links to some material which provides an introduction to what Maven is and what it can do, but in order to fully appreciate its value one would also need to understand its build processes in terms of phase stages together with targeting of specific goals.

Build 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 DT181G. 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 and 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 macOS Monterey running openjdk 17.0.1 and Apache Maven 3.8.6.

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 include clean for 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 the generated reports but you may notice that only Surefire Report is available here, while you can only see reports for JavaDoc and Checkstyle if you navigate to the report section of respective module. The reason for this lie in how we have configured propagation in the build, where some settings are inherited while others are aggregated.

Because of how we have it right now you should always run *mvn site from module directories, such as from the folder for Laboration_2/. When you do so, all reports will be generated properly and you can access everything by opening *Laboration_2/target/site/index.html in any browser.

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.

Note that we use _RepoResources/checkstyle.xml for our linting purposes. This is a custom ruleset we use in the course, and it's based on the official sun_checks.xml

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/, but you can of course also run the command from modules also. 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:

java -jar path_to_jar.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.