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!
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)
- Root of repository.
- All contents in this folder will be ignored by version control, as long as the
.gitignoreremains untouched. This is a good place to just play around with scripts, which are not meant to be viewed by others. - 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. - Directory for laboration content, further explained in points
9 - 13. Note that the same structure is used for the final project. - Directory for final project. Further details surrounding the structure will be explained once the assignment has been published.
- 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.
- The parent Maven script. Note that we use a distributed system, where we have subscripts in each module.
- The document you're currently reading.
- 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.
- This is where you store java files and resources needed for the solutions. Note that source documents
(
.java) needs to be placed under folderjava, which is explicitly marked as Sources Root, and its package name. Ex:java/com/dt181g/laboration_1/Lab1.java. - 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.
- 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.
- Root test resource folder. Same as for source files, but for testing purposes.
- Maven script for the lab module, deriving from parent
pom.xmlin project root. - README which needs to contain a written report, in conformity to requirements which are stated in the study guidance.
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!");
}
}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.
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.
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
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:
.txtand.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.
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.
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
ERRORstating broken link tojavadoc-bundle-options.
You may ignore this error since it regards creation of JavaDocjarfor publishing to Maven repositories.
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
Please write a short presentation. Suitable content would be...
- ... who you are.
- ... previous programming experiences.
- ... your expectations regarding this course.