Repository Structure

Relevant source files

The following files were used as context for generating this wiki page:

• README.adoc
• initial/pom.xml
• complete/pom.xml
• complete/src/main/java/com/example/restservice/Greeting.java
• complete/src/main/java/com/example/restservice/GreetingController.java
• complete/src/main/java/com/example/restservice/RestServiceApplication.java
• complete/src/test/java/com/example/restservice/GreetingControllerTests.java
• test/run.sh
• complete/manifest.yml

This repository contains a Spring guide project for creating a simple RESTful web service. The structure is designed to guide a user from a basic project skeleton to a fully functional application. It provides two distinct project states: initial and complete.

The repository is configured to be built with either Maven or Gradle, and includes wrapper scripts to ensure a consistent build environment. The core application is a simple "Hello, World" service that responds with a JSON object, demonstrating fundamental concepts of Spring Boot for web services.

High-Level Directory Layout

The repository is organized into two primary directories, initial and complete, which represent the start and end points of the tutorial. A test directory also exists to provide automated build verification.

This diagram shows the main directories at the root of the repository.

Directory	Description
initial/	Contains the starting point for the tutorial. It's a basic Spring Boot project structure with necessary dependencies but no implementation.
complete/	Contains the finished code for the REST service, including the controller, data model, and application entry point.
test/	Contains a shell script (run.sh) to compile and test both the initial and complete projects.

Sources: initial/, complete/, test/run.sh

Build System and Dependencies

The project can be built using either Maven or Gradle. Both the initial and complete directories contain pom.xml for Maven and Gradle Wrapper files (gradlew, gradlew.bat) for Gradle.

Sources: initial/pom.xml, complete/pom.xml, initial/gradlew.bat, complete/gradlew.bat

Maven Dependencies

The core functionality is enabled by a few key dependencies managed by the spring-boot-starter-parent.

Group ID	Artifact ID	Scope	Description
org.springframework.boot	spring-boot-starter-web	compile	Provides dependencies for building web applications, including RESTful ones, using Spring MVC.
org.springframework.boot	spring-boot-starter-test	test	Provides dependencies for testing Spring Boot applications with libraries like JUnit 5, Hamcrest, and Mockito.

Sources: complete/pom.xml:20-29

Application Components

The application logic resides within the complete/src/main/java/com/example/restservice directory and is composed of three main classes.

Component Relationship

The GreetingController handles incoming web requests and uses the Greeting record to structure the response data.

This diagram illustrates that GreetingController creates instances of the Greeting record.

Sources: complete/src/main/java/com/example/restservice/GreetingController.java, complete/src/main/java/com/example/restservice/Greeting.java

RestServiceApplication.java

This is the main entry point for the Spring Boot application. The @SpringBootApplication annotation enables auto-configuration, component scanning, and other core Spring Boot features.

// complete/src/main/java/com/example/restservice/RestServiceApplication.java
@SpringBootApplication
public class RestServiceApplication {

	public static void main(String[] args) {
		SpringApplication.run(RestServiceApplication.class, args);
	}

}

Sources: complete/src/main/java/com/example/restservice/RestServiceApplication.java:6-12

Greeting.java

A Java record class that models the data for the greeting response. Instances of this class are automatically marshalled into JSON by the Jackson 2 library, which is included by spring-boot-starter-web.

// complete/src/main/java/com/example/restservice/Greeting.java
package com.example.restservice;

public record Greeting(long id, String content) { }

Sources: complete/src/main/java/com/example/restservice/Greeting.java:3, README.adoc

GreetingController.java

This class is a REST controller responsible for handling incoming HTTP requests.

• @RestController: Marks the class as a controller where every method returns a domain object instead of a view. It's a shorthand for @Controller and @ResponseBody.
• @GetMapping("/greeting"): Maps HTTP GET requests for /greeting to the greeting() method.
• @RequestParam: Binds the value of the name query string parameter to the name method parameter. If the parameter is absent, it uses the defaultValue "World".
• The method returns a new Greeting object, which Spring automatically converts to a JSON response.

Sources: complete/src/main/java/com/example/restservice/GreetingController.java:9-17

API Endpoint: /greeting

The service exposes a single GET endpoint.

Property	Value	Description
Path	/greeting	The path to access the resource.
Method	GET	The HTTP method used.
Parameter	name (optional, String)	A query parameter to customize the greeting. Defaults to "World".
Response	{"id":<long>,"content":<String>}	A JSON object representing the greeting. The id is an auto-incrementing long.

Sources: README.adoc, complete/src/main/java/com/example/restservice/GreetingController.java:15-17

Request/Response Flow

The following diagram shows the sequence of events when a client makes a request to the /greeting endpoint.

Testing

The repository includes both unit tests for the controller and a shell script for end-to-end build testing.

Controller Tests

The GreetingControllerTests.java file uses @SpringBootTest and @AutoConfigureMockMvc to load the application context and test the web layer without starting a full HTTP server. MockMvc is used to perform GET requests and assert the response status and content.

Two test cases are present:

1. noParamGreetingShouldReturnDefaultMessage: Tests the /greeting endpoint without a name parameter and expects the default message "Hello, World!".
2. paramGreetingShouldReturnTailoredMessage: Tests the /greeting endpoint with a name parameter and expects a customized message.

Sources: complete/src/test/java/com/example/restservice/GreetingControllerTests.java:34-47

Build Verification Script

The test/run.sh script automates the build process for both initial and complete projects to ensure they compile and package correctly with both Maven and Gradle.

This diagram outlines the sequence of build commands executed by the run.sh script.

Sources: test/run.sh

Deployment

A manifest.yml file is provided for deployment to Cloud Foundry platforms. It defines the application's name, memory allocation, and the path to the executable JAR file produced by the build.

# complete/manifest.yml
---
applications:
- name: gs-rest-service
  memory: 256M
  instances: 1
  host: rest-service
  domain: guides.spring.io
  path: build/libs/gs-rest-service-0.1.0.jar

Sources: complete/manifest.yml