1. Introduction

Participation in this course requires a local development environment. Since competence using Java is a prerequisite for taking the course, much of the content here is likely already installed in your environment.

Software versions do not have to be latest-and-greatest. For the most part, the firm requirement is that the JDK must be 17 or at least your source code needs to stick to Java 17 features to be portable to grading environments.

You must manually download and install some of the software locally (e.g., IDE). Some software installations (e.g., MongoDB) have simple Docker options. The remaining set will download automatically and run within Maven. Some software is needed day 1. Others can wait.

Rather than repeat detailed software installation procedures for the various environments, I will list each one, describe its purpose in the class, and direct you to one or more options to obtain. Please make use of the course newsgroup if you run into trouble or have questions.

1.1. Goals

The student will:

  • setup required tooling in local development environment and be ready to work with the course examples

1.2. Objectives

At the conclusion of these instructions, the student will have:

  1. installed Java JDK 17

  2. installed Maven 3

  3. installed a Git Client and checked out the course examples repository

  4. installed a Java IDE (IntelliJ IDEA Community Edition, Eclipse Enterprise, or Eclipse/STS)

  5. installed a Web API Client tool

  6. optionally installed Docker

  7. conditionally installed Mongo

2. Software Setup

2.1. Java JDK (immediately)

You will need a JDK 17 compiler and its accompanying JRE environment immediately in class. Everything we do will revolve around a JVM.

  • For Mac and Unix-like platforms, SDKMan is a good source for many of the modern JDK images. You can also use brew or your package manager (e.g., yum, apt).

> brew search jdk | grep 17
openjdk@17

$ sdk list java | egrep 'ms|open|amzn' | grep 17
               |     | 17.0.12      | amzn    | installed  | 17.0.12-amzn
               |     | 17.0.11      | amzn    |            | 17.0.11-amzn
               |     | 17.0.11      | ms      |            | 17.0.11-ms
# apt-cache search openjdk-17 | egrep 'jdk |jre '
openjdk-17-jdk - OpenJDK Development Kit (JDK)
openjdk-17-jre - OpenJDK Java runtime, using Hotspot JIT

  • For Windows Users - Microsoft has JDK images available for direct download. These are the same downloads that SDKMan uses when using the ms option.

Windows        x64        zip        microsoft-jdk-17.0.3-windows-x64.zip        sha256 / sig
Windows        x64        msi        microsoft-jdk-17.0.3-windows-x64.msi        sha256

After installing and placing the bin directory in your PATH, you should be able to execute the following commands and output a version 17.x of the JRE and compiler.

Example Java Version Check
$ java --version
openjdk 17.0.12 2024-07-16 LTS
OpenJDK Runtime Environment Corretto-17.0.12.7.1 (build 17.0.12+7-LTS)
OpenJDK 64-Bit Server VM Corretto-17.0.12.7.1 (build 17.0.12+7-LTS, mixed mode, sharing)

$ javac --version
javac 17.0.12

2.2. Git Client (immediately)

You will need a Git client immediately in class. Note that most IDEs have a built-in/internal Git client capability, so the command line client shown here may not be absolutely necessary. If you chose to use your built-in IDE Git client, just translate any command-line instructions to GUI commands. If you have git already installed, it is highly likely you do not need to upgrade.

Download and install a Git Client.

I have git installed through brew on macOS.
If you already have git installed and working — no need for upgrade to latest.
Example git Version Check
$ git --version
git version 2.45.2

Checkout the course baseline.

$ git clone https://gitlab.com/ejava-javaee/ejava-springboot.git
...

$ ls | sort
...
assignment-starter
assignment-support
build
common
...
pom.xml

Each week you will want to update your copy of the examples as I updated and release changes.

$ git checkout main   # switches to main branch
$ git pull            # merges in changes from origin
Updating Changes to Modified Directory

If you have modified the source tree, you can save your changes to a new branch using the following:

$ git status           #show me which files I changed
$ git diff             #show me what the changes were
$ git checkout -b new-branch        #create new branch
$ git commit -am "saving my stuff"  #commit my changes to new branch
$ git checkout main    #switch back to course baseline
$ git pull             #get latest course examples/corrections
Saving Modifications to an Existing Branch

If you have made modifications to the source tree while in the wrong branch, you can save your changes in an existing branch using the following:

$ git stash            #save my changes in a temporary area
$ git checkout existing-branch      #go to existing branch
$ git commit -am "saving my stuff"  #commit my changes to existing branch
$ git checkout main    #switch back to course baseline
$ git pull             #get latest course examples/corrections

2.3. Maven 3 (immediately)

You will need Maven immediately in class. We use Maven to create repeatable and portable builds in class. This software build system is rivaled by Gradle. However, everything presented in this course is based on Maven and there is no feasible way to make that optional.

Download and install Maven 3.

I have Maven installed manually from the site since brew would only install the latest and I had an issue with 3.9.8 that reverting to 3.8.8 fixed. The issue is likely unique to my docs area and should not be an issue with the class examples. Just know that I am currently using 3.8.8 and the examples are built in the CI/CD environment with 3.8.6.

Place the $MAVEN_HOME/bin directory in your $PATH so that the mvn command can be found.

Example Maven Version Check
$ mvn --version
Apache Maven 3.8.8 (4c87b05d9aedce574290d1acc98575ed5eb6cd39)
Maven home: /usr/local/opt/apache-maven-3.8.8
Java version: 17.0.12, vendor: Amazon.com Inc., runtime: /Users/jim/.sdkman/candidates/java/17.0.12-amzn
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "12.6.9", arch: "x86_64", family: "mac"

Setup any custom settings in $HOME/.m2/settings.xml. This is an area where you and I can define environment-specific values referenced by the build.

<?xml version="1.0"?>
<settings xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">

<!-- keep as default if using class docker-compose script
    <localRepository>somewhere_else</localRepository>
-->
    <offline>false</offline>

    <mirrors>
        <!-- uncomment when JHU VPN unavailable
        <mirror>
            <id>ejava-nexus</id>
            <mirrorOf>ejava-nexus,ejava-nexus-snapshots,ejava-nexus-releases</mirrorOf>
            <url>file://${user.home}/.m2/repository/</url>
        </mirror>
        --> (1) (2)
    </mirrors>

    <profiles>
    </profiles>

    <activeProfiles>
      <!--
      <activeProfile>aProfile</activeProfile>
      -->
    </activeProfiles>

</settings>
1 make sure your ejava-springboot repository:main branch is up to date and installed (i.e., mvn clean install -f ./build; mvn clean install) prior to using local mirror
2 the URL in the mirror must be consistent with the localRepository value. The value shown here assumes the default, $HOME/.m2/repository value.

Attempt to build the source tree. Report any issues to the course newsgroup.

$ pwd
.../ejava-springboot
$ mvn install -f build
...
[INFO] ----------------------------------------
[INFO] BUILD SUCCESS
[INFO] ----------------------------------------

$ mvn clean install
...
[INFO] ----------------------------------------
[INFO] BUILD SUCCESS
[INFO] ----------------------------------------

2.4. Java IDE (immediately)

You will realistically need a Java IDE very early in class. If you are a die-hard vi, emacs, or text editor user — you can do a lot with your current toolset and Maven. However, when it comes to code refactoring, inspecting framework API classes, and debugging, there is no substitute for a good IDE. I have used Eclipse/STS for many years and some students in previous semester have used Eclipse installations from a previous Java-development course or work experience. They are free and work well. I will actively be using IntelliJ IDEA Community Edition. The community edition is free and contains most of the needed support. The professional edition is available for 1 year to anyone supplying a .edu e-mail.

It is up to you what IDE you use. Using something familiar is always the best first choice.

Download and install an IDE for Java development.

Load an attempt to run the examples in

  • app/app-build/java-app-example

2.5. Web API Client tool (not immediately)

Within the first month of the course, it will be helpful for you to have a client that can issue POST, PUT, and DELETE commands in addition to GET commands over HTTP. This will not be necessary until a few weeks into the semester.

Some options include:

  • curl - command line tool popular in Unix environments and likely available for Windows. All of my Web API call examples are done using curl.

  • Postman API Client - a UI-based tool for issuing and viewing web requests/responses. I personally do not like how "enterprisey" Postman has become. It used to be a simple browser plugin tool. However, the free version works and seems to only require a sign-up login.

curl example
$ curl -v -X GET https://ep.jhu.edu/
<!DOCTYPE html>
<html class="no-js" lang="en">
        <head>
...
<title>Johns Hopkins Engineering | Part-Time &amp; Online Graduate Education</title>
...

2.6. Optionally Install Docker (not immediately)

We will cover and make use of Docker since it is highly likely that anything you develop professionally will be deployed with Docker or will leverage it in some way. Spring/Spring Boot has also embraced Docker and Testcontainers as their preferred integration environment. There will be time-savings setup of backend databases as well as options in assignments where Docker desired. Once the initial investment of installing Docker has been tackled — software deployments, installation, and executions become very portable and easy to achieve.

I am still a bit hesitant in requiring Docker for the class. I will make it optional for the students who cannot install. I will lean into Docker more heavily if I get a sense that all students have access. Let me know where you stand on this optional installation.

Docker can serve three purposes in class:

  1. automates example database and JMS resource setup

  2. provides a popular example deployment packaging

  3. provides an integration test platform option with Maven plugins or with Testcontainers

Without Docker installation, you will

  1. need to manually install MongoDB native to your environment

  2. be limited to conceptual coverage of deployment and testing options in class

Optionally download and install Docker (called "Docker Desktop" these days).

Example Docker Version Check
$ docker -v
Docker version 27.0.3, build 7d4bcd8
$ docker-compose -v
Docker Compose version v2.28.1-desktop.1
The Docker Compose capability is now included with Docker via a Docker plugin and executed using docker compose versus requiring a separate docker-compose wrapper. Functionally they are the same. However, Testcontainers still looks for the legacy docker-compose command when testing with Docker Compose — so the wrapper is still necessary.
Legacy docker-compose Wrapper
$ docker compose --help
Usage:  docker compose [OPTIONS] COMMAND
Define and run multi-container applications with Docker
...

$ docker-compose --help
Usage:  docker compose [OPTIONS] COMMAND
Define and run multi-container applications with Docker
...

2.6.1. docker-compose Test Drive

With the course baseline checked out, you should be able to perform the following. Your results for the first execution will also include the download of images.

Start up database resources
$ docker-compose -p ejava up -d mongodb postgres (1)(2)
Creating ejava_postgres_1 ... done
Creating ejava_mongodb_1  ... done
1 -p option sets the project name to a well-known value (directory name is default)
2 up starts services and -d runs them all in the background
Shutdown database resources
$ docker-compose -p ejava stop mongodb postgres (1)
Stopping ejava_mongodb_1  ... done
Stopping ejava_postgres_1 ... done
$ docker-compose -p ejava rm -f mongodb postgres (2)
Going to remove ejava_mongodb_1, ejava_postgres_1
Removing ejava_mongodb_1  ... done
Removing ejava_postgres_1 ... done
1 stop pauses the running container
2 rm removes state assigned to the stopped container. -f does not request confirmation.

2.7. MongoDB (later)

You will need MongoDB in the later 1/3 of the course. It is somewhat easy to install locally, but a mindless snap — configured exactly the way we need it to be — if we use Docker. Feel free to activate a free Atlas account if you wish, but what gets turned in for grading should either use a standard local URL (using Fongo (via Maven), Docker, or Testcontainers).

If you have not and will not be installing Docker, you will need to install and set up a local instance of Mongo.