Lesson 6: Spring Boot Hello World

A first Spring Boot web app with Maven, @SpringBootApplication, @RestController, query parameters, JSON POST requests, configuration properties, service validation, error handling, and tests.

scripts/run.sh lesson_6 demo
scripts/run.sh lesson_6 exercise
scripts/apply_answers.sh lesson_6
scripts/run.sh lesson_6 verify
scripts/reset_exercises.sh lesson_6

Lesson README

Lesson 6: Spring Boot Hello World

This lesson starts a Spring Boot tutorial from the smallest useful web app: a GET /hello endpoint that returns JSON. It then extends the hello-world example with query parameters, a JSON POST, configuration properties, service-layer validation, error handling, and tests.

The lesson uses Spring Boot 4.1.0, Java 21, and Maven. Spring Boot's official project page describes Boot as a way to create stand-alone Spring applications with embedded servers and starter dependencies. The official system requirements for Spring Boot 4.1.0 require Java 17 or newer and Maven 3.6.3 or newer.

References:

• Spring Boot project page
• Spring Boot system requirements
• Spring Boot web reference

120-Minute Plan

Commands

Run the safe stub exercise:

scripts/run.sh lesson_6 exercise

Run a real embedded server demo that starts on a random port, calls itself, and exits:

scripts/run.sh lesson_6 demo

Apply answers and verify:

scripts/apply_answers.sh lesson_6
scripts/run.sh lesson_6 verify
scripts/reset_exercises.sh lesson_6

Start the real hello app on local port 8080:

scripts/serve_spring_hello_8080.sh

The default bind address is 0.0.0.0. To bind only to loopback:

SERVER_ADDRESS=127.0.0.1 SERVER_PORT=8080 scripts/serve_spring_hello_8080.sh

Try these requests:

curl http://127.0.0.1:8080/
curl 'http://127.0.0.1:8080/hello?name=Ada'
curl 'http://127.0.0.1:8080/hello?name=Linus&punctuation=%3F'
curl -X POST http://127.0.0.1:8080/hello \
  -H 'Content-Type: application/json' \
  -d '{"name":"Grace Hopper","punctuation":"."}'
curl 'http://127.0.0.1:8080/hello?name=Ada&punctuation=%40'

Exercise

Edit:

lesson_6/src/exercise/java/tutorial/lesson6/hello/GreetingService.java

Functions to implement:

• hello
• normalizeName
• normalizePunctuation

The lesson compiles before implementation. The stub always returns the classic Hello, World! shape. The answer verifier checks defaults, trimming, whitespace collapse, punctuation validation, max-name length, GET /hello, POST /hello, and HTTP 400 error handling.

Learner Workbook

Learner Workbook: Lesson 6 Spring Boot Hello World

This workbook is designed to take about two hours. The goal is to understand the first Spring Boot path from main to HTTP request to JSON response, while still practicing normal Java service design.

What You Should Understand By The End

• @SpringBootApplication marks the class Spring Boot starts from.
• SpringApplication.run(...) creates the application context and starts the embedded web server.
• spring-boot-starter-web brings in Spring MVC, JSON handling, and an embedded server.
• @RestController turns return values into HTTP response bodies.
• @GetMapping and @PostMapping map Java methods to HTTP routes.
• @RequestParam reads query-string values.
• @RequestBody reads JSON request bodies.
• @ConfigurationProperties binds values from application.properties.
• @Bean tells Spring how to construct an object it should manage.
• Service logic should be testable without starting the web server.
• Controller tests should prove the route, status code, and JSON shape.

0-10 Minutes: Boot Mental Model

Plain Java starts with:

public static void main(String[] args)

Spring Boot still starts there, but SpringApplication.run does extra work:

• scans for Spring-managed classes
• creates a dependency-injection container
• applies auto-configuration
• starts an embedded web server for web apps
• routes HTTP requests to controller methods

Open pom.xml. Find:

• spring-boot-starter-parent
• spring-boot-starter-web
• spring-boot-starter-test
• src/exercise/java as the Maven source directory

10-25 Minutes: Run The Stub And Demo

Run:

scripts/reset_exercises.sh lesson_6
scripts/run.sh lesson_6 exercise
scripts/run.sh lesson_6 demo

The exercise runner calls Java objects directly. The demo starts a real embedded server on a random port, sends HTTP requests to it, prints the JSON, and shuts down.

Write down the difference between:

• calling GreetingService.hello(...) directly
• calling /hello?name=Ada
• posting JSON to /hello

25-45 Minutes: Trace A Request

Open these files in order:

• SpringHelloApplication.java
• GreetingConfiguration.java
• HelloController.java
• GreetingService.java
• GreetingResponse.java
• GreetingRequest.java
• ApiExceptionHandler.java

Trace this request:

GET /hello?name=Ada&punctuation=.

Answer these questions:

• Which class starts the app?
• Which method receives /hello?
• Which annotation reads name from the query string?
• Which object builds the actual greeting?
• Which record becomes JSON?
• Where would an invalid punctuation error become HTTP 400?

45-65 Minutes: Define The Service Contract

GreetingService is the exercise file. Its rules are intentionally small:

• Missing, null, blank, or whitespace-only names use the configured default name.
• Extra internal whitespace collapses to one space.
• Names longer than tutorial.greeting.max-name-length are rejected.
• Missing or blank punctuation uses !.
• Allowed punctuation is only !, ?, or ..
• The response message is <prefix>, <name><punctuation>.

Examples:

65-95 Minutes: Implement In Rounds

Edit GreetingService.java.

Round 1: normalizeName

• Convert null to blank.
• Trim leading and trailing whitespace.
• Collapse repeated whitespace with replaceAll("\\s+", " ").
• Use properties.defaultName() when the result is blank.
• Reject names longer than properties.maxNameLength().

Round 2: normalizePunctuation

• Convert null or blank punctuation to !.
• Trim punctuation.
• Accept only !, ?, and ..
• Throw IllegalArgumentException for anything else.

Round 3: hello

• Call both normalize functions first.
• Build new GreetingResponse(...).
• Use properties.prefix() instead of hard-coding Hello.

Run after each round:

scripts/run.sh lesson_6 exercise

95-110 Minutes: Verify

Run:

scripts/apply_answers.sh lesson_6
scripts/run.sh lesson_6 verify
scripts/reset_exercises.sh lesson_6

The verifier is a Maven test suite. Read test names as requirements:

• buildsDefaultGreetingWhenNameIsMissing
• trimsAndCollapsesNameWhitespace
• acceptsQuestionMarkPunctuation
• rejectsUnsupportedPunctuation
• rejectsNamesLongerThanConfigurationAllows
• getHelloEndpointReturnsJsonGreeting
• postHelloEndpointUsesSameServiceRules
• badPunctuationReturnsHttpBadRequest
• simpleHealthEndpointReturnsUp

110-120 Minutes: Run On Port 8080

Start the app:

scripts/serve_spring_hello_8080.sh

In another terminal:

curl http://127.0.0.1:8080/
curl 'http://127.0.0.1:8080/hello?name=Ada'
curl 'http://127.0.0.1:8080/hello?name=Linus&punctuation=%3F'
curl -X POST http://127.0.0.1:8080/hello \
  -H 'Content-Type: application/json' \
  -d '{"name":"Grace Hopper","punctuation":"."}'
curl 'http://127.0.0.1:8080/hello?name=Ada&punctuation=%40'

Stop the app with Ctrl+C.

Edge-Case Drill

Before leaving the lesson, predict each result:

• GET /hello
• GET /hello?name=%20%20
• GET /hello?name=Alan%20%20%20Turing
• GET /hello?punctuation=.
• GET /hello?punctuation=%3F
• GET /hello?punctuation=!!
• GET /hello?name= followed by 41 letters
• POST /hello with {} as the body
• POST /hello with {"name":null,"punctuation":null}

Then run the request and compare.

Instructor Notes

Instructor Notes: Lesson 6 Spring Boot Hello World

Teaching Goal

This is the first framework lesson. Keep the frame tight: Spring Boot does not replace Java fundamentals. It wires Java objects together, starts infrastructure, and maps external requests onto ordinary methods.

Key Teaching Points

• pom.xml is part of the lesson. Learners should see how starter dependencies enter the project.
• SpringHelloApplication.main is still plain Java's entry point.
• @RestController is a routing adapter, not the place for business rules.
• GreetingService is deliberately testable without Spring.
• The controller returns records; Jackson converts those records to JSON.
• ApiExceptionHandler keeps error translation separate from greeting logic.
• scripts/run.sh lesson_6 demo starts a real server on a random port, so it is safe during workshops.
• scripts/serve_spring_hello_8080.sh is the manual local server path and binds to 0.0.0.0 by default.

Suggested Live Flow

• Run scripts/run.sh lesson_6 exercise and point out that no web server is required to call service code.
• Run scripts/run.sh lesson_6 demo and point out the JSON response bodies.
• Open SpringHelloApplication and explain the Boot startup boundary.
• Open HelloController and trace only one route first: GET /hello.
• Open GreetingService and ask learners what edge cases are missing from the stub.
• Implement normalizeName live if the class needs one example.
• Let learners implement normalizePunctuation and hello.
• Apply answers and run scripts/run.sh lesson_6 verify.
• Start scripts/serve_spring_hello_8080.sh and make real curl requests.

Common Confusions

• Learners may think annotations execute by themselves. Clarify that Spring scans annotations and builds behavior from metadata.
• Learners may put validation in the controller. Accept it as a discussion point, then show why one service rule can support both GET and POST.
• Learners may expect @RequestParam(defaultValue = "!") to solve all defaults. It handles absent query params, but service defaults still matter for direct calls and JSON requests.
• Learners may ask why this lesson uses Maven when earlier lessons use javac. Spring dependencies require a build tool to resolve libraries and run tests consistently.

Extension Prompts

• Add GET /hello/{name} with @PathVariable.
• Add a tutorial.greeting.prefix=Ahoy override and verify the message changes.
• Add GET /goodbye using the same service pattern.
• Add Actuator and compare /health/simple with /actuator/health.
• Add a second test that proves unsupported punctuation returns HTTP 400 for POST /hello.

Rescue Prompts

• If the app does not start, run scripts/run.sh lesson_6 exercise first to isolate Java service behavior.
• If port 8080 is already used, run SERVER_PORT=8081 scripts/serve_spring_hello_8080.sh.
• If tests fail, read the test method name and fix only the behavior it describes.
• If JSON output is surprising, inspect the record component names; those become JSON field names.

Functions In This Lesson

public GreetingService(GreetingProperties properties) {

public GreetingResponse hello(String rawName, String rawPunctuation) {

public String normalizeName(String rawName) {

public String normalizePunctuation(String rawPunctuation) {

public ResponseEntity<ErrorResponse> badRequest(IllegalArgumentException exception) {

private BootHelloDemo() {

public static void main(String[] args) throws IOException, InterruptedException {

private static String get(HttpClient client, int port, String pathAndQuery) throws IOException, InterruptedException {

private static String post(HttpClient client, int port, String path, String json) throws IOException, InterruptedException {

private static URI uri(int port, String pathAndQuery) {

public ErrorResponse {

private ExerciseRunner() {

public static void main(String[] args) {

public GreetingService greetingService(GreetingProperties properties) {

public GreetingProperties {

private static String defaultText(String candidate, String fallback) {

public GreetingRequest {

public GreetingResponse {

public GreetingService(GreetingProperties properties) {

public GreetingResponse hello(String rawName, String rawPunctuation) {

public String normalizeName(String rawName) {

public String normalizePunctuation(String rawPunctuation) {

public HelloController(GreetingService greetings) {

public Map<String, String> index() {

public GreetingResponse helloJson(@RequestBody GreetingRequest request) {

public Map<String, String> health() {

public static void main(String[] args) {

public void buildsDefaultGreetingWhenNameIsMissing() {

public void trimsAndCollapsesNameWhitespace() {

public void acceptsQuestionMarkPunctuation() {

public void rejectsUnsupportedPunctuation() {

public void rejectsNamesLongerThanConfigurationAllows() {

public static void startServer() {

public static void stopServer() {

public void getHelloEndpointReturnsJsonGreeting() throws IOException, InterruptedException {

public void postHelloEndpointUsesSameServiceRules() throws IOException, InterruptedException {

public void badPunctuationReturnsHttpBadRequest() throws IOException, InterruptedException {

public void simpleHealthEndpointReturnsUp() throws IOException, InterruptedException {

private HttpResponse<String> get(String pathAndQuery) throws IOException, InterruptedException {

private HttpResponse<String> post(String path, String json) throws IOException, InterruptedException {

private URI uri(String pathAndQuery) {

public GreetingService(GreetingProperties properties) {

public GreetingResponse hello(String rawName, String rawPunctuation) {

public String normalizeName(String rawName) {

public String normalizePunctuation(String rawPunctuation) {