Request Lifecycle

This document outlines the request lifecycle for the RESTful web service. It details how an incoming HTTP request is received, processed, and how a JSON response is generated and sent back to the client. The primary focus is on the /greeting endpoint, which is the core feature of this application.

The lifecycle begins when the Spring Boot application starts, enabling an embedded web server to listen for requests. When a GET request hits the /greeting endpoint, it is routed to the GreetingController. The controller processes the request, optionally using a query parameter, and returns a Greeting object. Spring's framework then automatically serializes this object into a JSON string and sends it as the HTTP response body with a 200 OK status.

1. Application Bootstrap

The entire process is initiated by the RestServiceApplication class. This class contains the main method, which serves as the application's entry point.

The @SpringBootApplication annotation enables auto-configuration, component scanning, and other core Spring Boot features. The SpringApplication.run() method launches the application, which includes starting an embedded web server (like Tomcat) that listens for incoming HTTP requests.

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

// complete/src/main/java/com/example/restservice/RestServiceApplication.java:8-12
@SpringBootApplication
public class RestServiceApplication {
	public static void main(String[] args) {
		SpringApplication.run(RestServiceApplication.class, args);
	}
}

The necessary web server and Spring MVC dependencies are included via the spring-boot-starter-web dependency in the project's pom.xml.

Sources: complete/pom.xml:21-24

2. Request Handling and Processing

When a request is made to the server, Spring's DispatcherServlet routes it to the appropriate controller method based on the path and HTTP verb.

2.1. Controller and Endpoint Mapping

The GreetingController class is responsible for handling requests to the /greeting endpoint.

• @RestController: This annotation marks the class as a controller where every method returns a domain object instead of a view. It is a shorthand for @Controller and @ResponseBody.
• @GetMapping("/greeting"): This annotation maps HTTP GET requests for the /greeting path to the greeting() method.

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

The following diagram illustrates the class structure for request handling.

This class diagram shows that GreetingController creates and returns Greeting objects.

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

2.2. Parameter Binding

The greeting() method accepts an optional query parameter named name.

• @RequestParam(value = "name", defaultValue = "World") String name: This annotation binds the value of the name query parameter from the URL (e.g., /greeting?name=User) to the name method parameter.
• If the name parameter is not provided in the request, its value defaults to "World".

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

2.3. Business Logic

The logic within the greeting() method is straightforward:

1. It increments a thread-safe AtomicLong counter to generate a unique ID for each request.
2. It formats a greeting string using a predefined template ("Hello, %s!") and the provided name.
3. It instantiates and returns a new Greeting object containing the new ID and the formatted content string.

// complete/src/main/java/com/example/restservice/GreetingController.java:15-16
public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
	return new Greeting(counter.incrementAndGet(), String.format(template, name));
}

Sources: complete/src/main/java/com/example/restservice/GreetingController.java:11-16

3. Response Generation

The object returned by the controller method becomes the body of the HTTP response.

3.1. Data Model: The Greeting Record

The Greeting class is a Java record, which is a simple data carrier. It models the data that will be sent in the JSON response.

// complete/src/main/java/com/example/restservice/Greeting.java:3
public record Greeting(long id, String content) { }

The record has two components:

• id: A unique identifier for the greeting.
• content: The textual representation of the greeting.

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

3.2. JSON Serialization

Because the GreetingController is annotated with @RestController, the returned Greeting object is automatically serialized into JSON format. This is handled by Spring's MappingJackson2HttpMessageConverter, which is available on the classpath because of the spring-boot-starter-web dependency.

The resulting JSON response looks like this:

{"id":1,"content":"Hello, World!"}

Sources: README.adoc:22-24, README.adoc:100-104

4. End-to-End Request Flow

The following sequence diagram shows the complete lifecycle of a single request to the /greeting endpoint.

This diagram illustrates a client making a GET request, which is routed by the Spring Framework to the GreetingController, resulting in the creation of a Greeting object that is serialized to JSON and returned to the client.

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

5. API Endpoint Summary

The table below summarizes the /greeting endpoint.

Sources: README.adoc:16-32, complete/src/main/java/com/example/restservice/GreetingController.java:14-16

6. Testing the Lifecycle

The request lifecycle is verified through integration tests in GreetingControllerTests. These tests use MockMvc to perform mock HTTP requests and validate the responses.

• noParamGreetingShouldReturnDefaultMessage(): Tests the default behavior when the name parameter is absent. It expects the content to be "Hello, World!".
• paramGreetingShouldReturnTailoredMessage(): Tests the behavior when a name parameter is provided. It expects the content to be "Hello, Spring Community!".

These tests confirm that the controller mapping, parameter binding, and response serialization work as expected.

Sources: complete/src/test/java/com/example/restservice/GreetingControllerTests.java:32-45