Skip to content

Lab 04

In this lab session you will revise the writing of javadoc as part of your code, conversion to human-readable websites, and practice the basics of the maven build system. You do not need to download any new code for this lab session.

JavaDoc

In the last class we have briefly seen the notation for JavaDoc comments. As a quick reminder:

  • Regular, one-liner comments are started with a double forward slash:
// Here is the answer to life, the universe, and everything:`
int answer = 42;
  • Longer, multi-line comments are fenced between a start and an end marker:
/* Here is a longer comment
 that makes up multiple
 lines, because it is very
 sophisticated.*/
int answer = 42;
  • JavaDoc comments, are started with a slash and two stars:
/**
 * Here is a JavaDoc comment that describes some detail about a function.
 */
public void foo() {
  ...
}

What is JavaDoc ?

JavaDoc comments are not only for programmers, but also for users. They do not "disappear" on compilation, but can be used as input for generating documentation.

Task 1, Reading ApiDoc

The workflow for writing and using JavaDoc is as follows:

  1. A developer writes JavaDoc, as part of their source code.
  2. A developer uses the javadoc command (automatically installed with javac) to generate a documentation
  3. Software users or developers using the software can use the documentation to quickly understand how the code functions.

All Java internal classes and functions are 100% documented, and the generated JavaDoc is openly available. You can for instance quickly look up what methods can be used on String objects, using the Online JavaDoc reference.

Your turn

  • Write a new short java program that converts all lower case letters of a string into upper case letters:
  • Example:
  String myString = "IloVeThIScouRsEinF2050iSAmAzIng";
  // Use the API reference to find the right method.
  // Must print: ILOVETHISCOURSEINF2050ISAMAZING
  System.out.println(myString.theMagicMethodYouhaveToFind());

Task 2, From Code to Docs

In this second task you will practice how to generate a human-readable documentation summary yourself.

  • Revisit the program you previously wrote to convert a sample string to upper-case, and make sure the code is in a dedicated method: toUpperOrLower.
  • toUpperOrLower should take 2 arguments, a string and a boolean.
    • If the boolean is true an upper-case version of the string is returned, otherwise a lower case version of the string.
  • Make sure your code is completely documented with javadoc (the class, and all methods.)

Your turn

Now it is your turn to generate JavaDoc from your code.

  • Instead of compiling your code with javac, use the javadoc command to produce a documentation.
  • The command is: javadoc -d /Users/schieder/Desktop/javadoc plants
    • Where /Users/schieder/Desktop/javadoc is replaced by the path to your Desktop.
    • You can choose another path, e.g. to /tmp.
    • If you're on Windows, you must certainly use backslashes (\)
  • If you see a new folder javadoc, containing a file index.html the command was successful
  • When you open index.html with your browser, you'll see mostly empty website.
    • This is because you likely do not have much JavaDoc in you java source code.
  • The javadoc command actually prints a warning, every time one of your methods or classes misses a comment.

Now comment your code with javadoc comments. Comment and relaunch the command until there are no more warnings!

Writing JavaDoc is NOT an optional luxury.

In your TP, all your code must be 100% documented. If the javadoc command raises a single warning, you will loose points (many).

Maven

In class we've seen that maven is a build system that allows automatic management of dependencies, and modification of the build process by help of plugins. In the remainder of the lab session, you will use the maven command, and simple amendement to the pom.xml configuration file.

Hello World

Maven projects must respect a specific layout of documents, and a specific pom.xml syntax.

  • In class we've seen a command to set up a new maven project, using the mvn command: 
      mvn archetype:generate \
  -DgroupId=ca.uqam.info \
  -DartifactId=MavenHelloWorld \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

Your turn

  • Customize the command to the group id is a valid package name, representing you as a developer: ca.uqam.info.lastname
  • Run the command and inspect the structure of the newly created project.
  • Go into the new project and compile the sources, using the mvn clean compile command.
    • Why is it good practice to run the clean parameter every time ? Try just mvn clean and mvn compile to spot the difference.

The exec plugin

By default, maven projects only compile and have no main class specified.

Why, should not all java projects have a main class?

Actually, plenty of java projects only provide functionality, but no main class to run / launch the code: These are all java libraries.

In class I've briefly shown how the pom.xml can be edited to specify a main class.

Your turn

  • Revisit the course notes, look up usage of the exec plugin.
  • Edit the pom.xml sources, add the exec plugin and specify the main class.
  • Run your project with mvn clean compile exec:java
  • Verify your program correctly runs and prints the Hello, World message.
Why not just mvn exec:java (which also runs the code) ?

mvn exec java does indeed run the code. However, it does not compile the sources, so possibly you are running something different than what you have currently written in your source editor. Always use mvn clean compile exec:java to run your code.

Using a library

In class, we've seen how maven can be used to add libraries to a project, by adding a dependency block to the pom.xml.

  • Dependencies allow you to conveniently access java libraries.
    • Libraries are great whenever you want to reuse a complex functionality
    • An example is MD5 hashing, which is relevant for checksums and file integrity verification
    • Example: MD5 hashsum of the String Schiedermeier is 50707bed5659e48b953b8b64a64c9f1c

Your turn

  • Integrate the apache commons io library into your maven project.
    • Visit the maven central respository
    • Search and find the apache commons codec artifact using the search field.
    • Copy the dependency block (xml snippet) for the most recent library version
    • Add the snippet to the correct place of your pom.xml
  • Modify your hello world project, so that...
    • It creates a string with your lastname
    • It correctly calls the md5Hex method to convert your last name into a MD5 hashsum
    • It prints the hashsum to screen
  • Verify the result, using this online hashsum calculator

The JavaDoc plugin

At the start of the lecture you've learned how to generate human-readable JavaDoc using the javadoc command.

  • Documentation should be actualized, whenever code is changed
  • Of course it would be tedious to manually call the javadoc command every time you modify code.
  • Luckily javadoc can be invoked as part of the build process with maven. All you need is the javadoc plugin.

Your turn

  • Revisit the course notes on maven plugins, find the plugin snippet to add to your pom.xml.
  • Add the javadoc plugin to your pom.xml configuration.
  • Rerun maven with mvn clean package
  • Carefully read the output of the build process.
  • For every warning or error, fix your documentation until the build passes.

Document early

25% of your TP1 grade is the quality of your javadocs. Writing documentation is easy in the moment you write your code, as you know exaclty how it works. Write documentation later is tedious, and slow. Regularly build your project with maven and keep up with the documentation.

The Jar plugin

Often times you want to ensure your java project can be delivered to the client as a single file. In the last course unit you've learned that JAR files can be created manually, by zipping compiled java bytecode.

  • Like documentation, it is good practice to produce a deliverable jarfile with every code modification.
  • Like with documentation it would be tedious, to do so manually, using the command line, on every code change.
  • Luckily maven can be configured to do so for you.

Your turn

  • Revisit the course notes on maven plugins, find the plugin snippet to add to your pom.xml.
  • Add the maven-jar-plugin plugin to your pom.xml configuration.
    • Make sure to specify the main class in the plugin's configuration.
  • Rerun maven with mvn clean package
  • Carefully read the output of the build process.
  • Inspect the generated target folder, is there a new file?
  • Verify you can run your jarfile, using the java -jar yourfile.jar command.

Test your TP1 Jarfile

Your TP1 submission must produce a valid jarfile on mvn clean package. Test the produced jar before you submit, to make sure you get those points.`

The green triangle

For your TP you certainly want to use an IDE, for example IntelliJ. That is perfectly fine, and we'll also cover IDEs in more detail in a future lecture. However, be very careful with buttons and menues that seem to magically simplify things.

IDEs are powerful, but think before you click 'run'

By default, the green triangle (▶) is not associated with maven. That is, although you may have a pom.xml file, and your project is structured as a maven project, maven is not called when you click the run button. If you want to use the green triangle, you must manually add a maven run configuration, to overload the triangle's behaviour.

Run configurations are user-defined behaviours associated with the green triangle.

Your turn

Let's now add a configuration that compiles and runs your code, using maven.

  • In the top menubar, select Run -> Edit Configurations
  • In the popup, click the + sign, and select Maven
  • You'll see a maven specific configuration formula:
  • Give your configuration a corresponding name, e.g. Build and run
  • In the Run / Command line field, add the maven command you want to invoked, e.g. clean package exec:java (note that the inital mvn command is obsolete)
  • Close the dialogue and click the green triangle (▶).
  • Verify maven is called and builds and runs your project.