1. Introduction

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

Software versions do not have to be latest-and-greatest. My JDK 11/Maven environment looks to be close to 2 years old when authoring this guide. For the most part, the firmest 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 have options (e.g., Docker/Mongo or Mongo). 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 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' | grep 17
 Microsoft |  | 17.0.3  | ms  |    | 17.0.3-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.3 2022-04-19
OpenJDK Runtime Environment Temurin-17.0.3+7 (build 17.0.3+7)
OpenJDK 64-Bit Server VM Temurin-17.0.3+7 (build 17.0.3+7, mixed mode, sharing)

$ javac --version
javac 17.0.3

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.

Download and install a Git Client.

I have git installed thru brew on MacOS
Example git Version Check
$ git --version
git version 2.36.0

Checkout the course baseline.

$ git clone https://gitlab.com/ejava-javaee/ejava-springboot.git
...
$ ls | sort
app
build
common
coursedocs
env
intro
pom.xml
...

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

$ git checkout master # switches to master 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 branchusing 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 master  #switch back to course baseline
$ git pull
Saving Modifications to an Existing Branch

If you have made modifications to the source tree 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 master  #switch back to course baseline
$ git pull

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 through brew on MacOS. Anything fairly recent should be good.

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.6 (84538c9988a25aec085021c365c560670ad80f63)
Maven home: /usr/local/Cellar/maven/3.8.6/libexec
Java version: 17.0.3, vendor: Eclipse Adoptium, runtime: .../.sdkman/candidates/java/17.0.3-tem
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "12.4", 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">

<!--
    <localRepository>somewhere_else</localRepository>
-->
    <offline>false</offline>

    <mirrors>
        <!-- uncomment when JHU unavailable
        <mirror>
            <id>ejava-dependencies</id>
            <mirrorOf>ejava-nexus</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. 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 you use. Using something familiar is always the best 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 web API client that can issue POST, PUT, and DELETE commands in addition to GET commands over HTTP and (one-way TLS) HTTPS. 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 use to simply be a browser plugin tool. However, the free version works and seems to only require a sign-up login.

$ 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)

Is seems everything in this world has become containerized — and for a good reason. 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 tentative in requiring Docker for the class. I will make it optional for the students who cannot install. I will leverage Docker more heavily if I get a sense that all students have access. Let me know where you stand on this optional install.

Optionally download and install Docker. 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

Without Docker installation, you will

  1. need to manually install MongoDB

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

All platforms - Docker.com

docker-compose is now being installed with docker for the Docker Desktop installations. It may not be necessary to do a separate installation for docker-compose.
Example Docker Version Check
$ docker -v
Docker version 20.10.7, build f0df350
$ docker-compose -v
docker-compose version 1.29.2, build 5becea4c

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. Note that you will eventually need an Internet accessible MongoDB instance later in the course, so feel free to activate a free Atlas account at any time.

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

2.8. Heroku Account (later)

Mid-way through the course you will hit a very exciting point in the course, where you will begin deploying your assignments to the Internet for all to see.

We will be leveraging the Heroku Internet hosting platform. Heroku supports deploying Spring Boot executable JARs as well as Docker images. You will need an account and download their "toolbelt" set of commands for uploading, configuring, and managing deployments.

Create an account and download the Heroku toolbelt.

2.9. Mongo Atlas Account (later)

In the last 1/3 of the course, when deploying an application based on RDBMS and MongoDB, you will need access to an Internet accessible RDBMS and MongoDB instance. You will be able to provision a free RDBMS database directly from Heroku. You will be able to provision a free, Internet accessible MongoDB instance via Mongo Atlas.

Create an account and provision an Internet accessible MongoDB.

All platforms - Mongo Atlas