Running the Application

Relevant source files

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

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

This document provides a technical overview of how to build, run, and test the gs-rest-service application. The project is a simple, "Hello, World" RESTful web service built with Spring Boot. It exposes a single HTTP GET endpoint that returns a JSON greeting.

The application is designed to be run as a standalone executable JAR file. It can be built using either Maven or Gradle. The core functionality is encapsulated within a Spring @RestController which handles incoming web requests and returns a JSON response.

Sources: README.adoc:7-8, README.adoc:112-114

Core Components

The application is composed of three main Java classes that work together to provide the REST service.

• RestServiceApplication: The main class that bootstraps and launches the Spring Boot application.
• GreetingController: A REST controller that handles HTTP requests to the /greeting endpoint.
• Greeting: A Java record that models the data for the JSON response.

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

The diagram below illustrates the relationship between these core components.

RestServiceApplication

This is the entry point of the service. The @SpringBootApplication annotation enables auto-configuration, component scanning, and other Spring Boot features. The main method uses SpringApplication.run() to launch the application.

// complete/src/main/java/com/example/restservice/RestServiceApplication.java:6-12
@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

GreetingController

This class is marked with @RestController, indicating that it handles web requests and that every method returns a domain object instead of a view. It defines the /greeting endpoint.

Sources: README.adoc:65-68, complete/src/main/java/com/example/restservice/GreetingController.java:10

Greeting

This is a simple Java record used to model the JSON response. Instances of this class are automatically marshaled to JSON by the Jackson library, which is included by default with the spring-boot-starter-web dependency.

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

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

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

Building the Application

The application can be built into an executable JAR file using either Maven or Gradle. The pom.xml file defines the necessary dependencies and build plugins for a Maven build.

Sources: README.adoc:115-117, complete/pom.xml

Build Dependencies

The primary dependencies for the project are spring-boot-starter-web for building the web service and spring-boot-starter-test for testing.

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. It includes an embedded Tomcat server.
org.springframework.boot	spring-boot-starter-test	test	Provides dependencies for testing Spring Boot applications with libraries like JUnit, Hamcrest, and Mockito.
Sources: complete/pom.xml:19-29

Build Commands

The run.sh script demonstrates the build commands for both Maven and Gradle.

To build with Maven, execute the following command from the complete directory:

./mvnw clean package

This command compiles the code, runs tests, and packages the application into an executable JAR in the target/ directory.

Sources: test/run.sh:13, README.adoc:117

Application Execution

Once the application is built, it can be run from the command line using java -jar. The service will start and be available on http://localhost:8080.

java -jar target/gs-rest-service-0.1.0.jar

Sources: README.adoc:117

The following diagram shows the startup sequence.

API Endpoint: /greeting

The service exposes a single GET endpoint at /greeting.

Sources: README.adoc:8

Endpoint Details

Method	Path	Description
GET	/greeting	Returns a JSON object with a greeting. Accepts an optional name query parameter.

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

Request Parameter

The endpoint accepts one optional query parameter.

Parameter	Type	Default Value	Description
name	String	"World"	Used to customize the content of the greeting message.
Sources: complete/src/main/java/com/example/restservice/GreetingController.java:17

Request/Response Flow

The GreetingController handles the request. The @GetMapping("/greeting") annotation maps the greeting() method to GET requests for /greeting. The @RequestParam annotation binds the value of the name query parameter to the name method parameter. A new Greeting object is created with a unique ID and the formatted content, which is then serialized to JSON and returned in the HTTP response.

Sources: README.adoc:73-83, complete/src/main/java/com/example/restservice/GreetingController.java:16-18

Testing the Service

The project includes integration tests for the GreetingController. The tests use MockMvc to perform requests against the endpoint without needing to run a full HTTP server.

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

The GreetingControllerTests class contains two test cases:

1. noParamGreetingShouldReturnDefaultMessage: Sends a GET request to /greeting without any parameters and asserts that the response content is "Hello, World!".
2. paramGreetingShouldReturnTailoredMessage: Sends a GET request to /greeting with the name parameter set to "Spring Community" and asserts that the response content is "Hello, Spring Community!".

// complete/src/test/java/com/example/restservice/GreetingControllerTests.java:38-42
@Test
public void noParamGreetingShouldReturnDefaultMessage() throws Exception {

    this.mockMvc.perform(get("/greeting")).andDo(print()).andExpect(status().isOk())
            .andExpect(jsonPath("$.content").value("Hello, World!"));
}

Sources: complete/src/test/java/com/example/restservice/GreetingControllerTests.java:38-42

// complete/src/test/java/com/example/restservice/GreetingControllerTests.java:45-49
@Test
public void paramGreetingShouldReturnTailoredMessage() throws Exception {

    this.mockMvc.perform(get("/greeting").param("name", "Spring Community"))
            .andDo(print()).andExpect(status().isOk())
            .andExpect(jsonPath("$.content").value("Hello, Spring Community!"));
}

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

Deployment

The repository includes a manifest.yml file, which suggests a deployment configuration for Cloud Foundry-compatible platforms.

Property	Value	Description
name	gs-rest-service	The name of the application.
memory	256M	The amount of memory to allocate to the application instance.
instances	1	The number of application instances to run.
host	rest-service	The hostname for the application route.
domain	guides.spring.io	The domain for the application route.
path	build/libs/gs-rest-service-0.1.0.jar	The path to the application artifact to be deployed.
Sources: complete/manifest.yml:2-8