Running as a Local Service

Relevant source files

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

• complete/pom.xml
• README.adoc
• 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/src/test/java/com/example/restservice/GreetingControllerTests.java
• test/run.sh
• complete/mvnw.cmd

This document describes how to build, run, and test the gs-rest-service application locally. The project is a simple "Hello, World" RESTful web service built using the Spring Framework. Its primary function is to accept HTTP GET requests and respond with a JSON representation of a greeting.

The service exposes a single endpoint, /greeting, which can be customized with a query parameter. By default, it runs on http://localhost:8080. The application is built as a standalone executable JAR file, making it easy to run on any machine with a Java Runtime Environment.

Sources: README.adoc:8-10, 80-82

System Architecture

The service is composed of three main Java components that work together within the Spring Boot framework to handle web requests and generate responses.

Sources: README.adoc:48-50, 65-67

Core Components

Component	File	Description
RestServiceApplication	RestServiceApplication.java	The main application class and entry point. It uses the @SpringBootApplication annotation to enable auto-configuration and component scanning.
GreetingController	GreetingController.java	A REST controller (@RestController) that handles incoming HTTP requests to the /greeting endpoint.
Greeting	Greeting.java	A Java record class that models the data structure for the JSON response. It contains id and content fields.

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 following diagram illustrates the relationship between these core components.

Building and Running the Service

The application can be built and run using either Maven or Gradle. The Spring Boot plugin for each build tool packages the service into an executable JAR file with all dependencies included.

Build and Run Flow

The diagram below shows the general workflow for building the application and running it as a local service.

Build Commands

You can build an executable JAR from the complete directory using one of the following commands:

• Maven:

  ./mvnw clean package
  

  This command uses the Maven wrapper to build the project. The spring-boot-maven-plugin specified in the pom.xml is responsible for creating the executable JAR.
  Sources: complete/pom.xml:37-40, test/run.sh:16

• Gradle:

  ./gradlew build
  

  This command uses the Gradle wrapper to build the project.
  Sources: test/run.sh:26

Running the Service

Once the JAR file is built, you can run the service from the command line:

java -jar build/libs/gs-rest-service-0.1.0.jar

(Note: The path and filename may vary slightly based on the build tool and version).

The service will start, and logging output will be displayed. It should be running and ready to accept requests within a few seconds. The main entry point is the main method in RestServiceApplication.

Sources: README.adoc:86-88, complete/src/main/java/com/example/restservice/RestServiceApplication.java:10-12

API Endpoint: /greeting

The service exposes a single HTTP GET endpoint.

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

Endpoint Details

Method	Path	Description
GET	/greeting	Returns a JSON object with a greeting message.

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

Request Parameters

Parameter	Type	Description	Default Value
name	String	An optional parameter to customize the greeting message.	"World"

The @RequestParam annotation in GreetingController binds the value of the query string parameter name to the name parameter of the greeting() method.

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

Response Body

The endpoint returns a JSON object representing a Greeting.

Field	Type	Description
id	long	A unique identifier for the greeting, incremented with each request.
content	String	The textual representation of the greeting.

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

Example Response (no parameter):

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

Example Response (with ?name=User):

{"id":2,"content":"Hello, User!"}

Sources: README.adoc:12-14, 22-24

Request-Response Flow

This sequence diagram illustrates how a request to the /greeting endpoint is processed.

Testing the Service

The service can be tested manually via a web browser or curl, or through the automated tests included in the project.

Manual Testing

After starting the service, you can test it by visiting the following URLs in your browser:

1. http://localhost:8080/greeting
   • This should return the default greeting: {"id":1,"content":"Hello, World!"}.
2. http://localhost:8080/greeting?name=User
   • This should return a customized greeting: {"id":2,"content":"Hello, User!"}.

The id field increments with each request, demonstrating that a single controller instance is handling all requests.

Sources: README.adoc:91-105

Automated Testing

The project includes tests for the GreetingController using Spring's MockMvc. These tests run without needing a live server.

*Sources: complete/src/test/java/com/example/restservice/GreetingControllerTests.java

The GreetingControllerTests class contains two test cases:

1. noParamGreetingShouldReturnDefaultMessage(): This test performs a GET request to /greeting without any parameters and asserts that the HTTP status is 200 OK and the content field in the JSON response is "Hello, World!".

   // complete/src/test/java/com/example/restservice/GreetingControllerTests.java:38-41
   this.mockMvc.perform(get("/greeting")).andDo(print()).andExpect(status().isOk())
           .andExpect(jsonPath("$.content").value("Hello, World!"));
   

2. paramGreetingShouldReturnTailoredMessage(): This test performs a GET request to /greeting with the name parameter set to "Spring Community" and asserts that the status is 200 OK and the content field is "Hello, Spring Community!".

   // complete/src/test/java/com/example/restservice/GreetingControllerTests.java:46-49
   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:36-51