Web Request and Response Mechanisms

In a Browser/Server (B/S) architecture, clients interact with backend applications via HTTP protocols. When a request reaches the embedded Tomcat server in a Spring Boot application, it is initially processed by the core DispatcherServlet. This front controller routes the incoming request to the appropriate handler class (Controlller) based on mapping rules, processes the logic, and ultimately returns the HTTP response to the client.

Tomcat parses the raw HTTP data—including request lines and headers—and encapsulates them into an HttpServletRequest object. Conversely, response data is managed via HttpServletResponse. While Spring Boot abstracts away much of this native Servlet API complexity, understanding this underlying mechanism is foundational for web development.

1. Handling Request Parameters

---

When developing RESTful APIs, backend engineers often rely on API testing tools like Postman to simulate client requests (GET, POST, etc.) and verify endpoint behavior without requiring a frontend interface.

1.1 Simple Parameters

Traditionally, retrieving query parameters required injecting the native HttpServletRequest object and explicitly extracting values, which necessitated manual type conversion.

@RestController
public class DataController {
    @RequestMapping("/basicParam")
    public String handleBasicParam(HttpServletRequest req) {
        String username = req.getParameter("user");
        String yearsStr = req.getParameter("years");
        int years = Integer.parseInt(yearsStr); // Manual parsing
        return "Processed";
    }
}

Spring Boot significantly simplifies this by automatically binding request parameters to method arguments, provided the parameter names match the variable names. Type conversion is also handled automatically.

@RestController
public class DataController {
    @RequestMapping("/basicParam")
    public String handleBasicParam(String user, Integer years) {
        System.out.println(user + " : " + years);
        return "Processed";
    }
}

If request parameter name differs from the method argument name, binding fails (resulting in null). To resolve this, use the @RequestParam annotation to explicitly map the request key to the variable. By default, required is set to true; set it to false for optional parameters.

@RequestMapping("/basicParam")
public String handleBasicParam(@RequestParam(name = "user", required = false) String username, Integer years) {
    return "Processed";
}

1.2 POJO Parameters

For complex forms with numerous fields, binding individual arguments is inefficient. Instead, encapsulate the data into a Plain Old Java Object (POJO). Spring automatically populates the object properties if the request parameter names match the POJO field names.

Nested objects (Complex POJOs) follow the same rule. For instance, if a Person object contains a Location object, the frontend must submit parameters using hierarchical naming conventions (e.g., homeAddress.state and homeAddress.municipality).

public class Location {
    private String state;
    private String municipality;
    // getters and setters
}

public class Person {
    private String fullName;
    private Integer yearsOfAge;
    private Location homeAddress;
    // getters and setters
}

@RestController
public class DataController {
    @RequestMapping("/pojoParam")
    public String handlePojo(Person person) {
        System.out.println(person);
        return "Processed";
    }
}

1.3 Array and Collection Parameters

When a form submits multiple values for the same key (e.g., multiple checkboxes), they can be received as an array.

@RequestMapping("/arrayParam")
public String handleArray(String[] preferences) {
    System.out.println(Arrays.toString(preferences));
    return "Processed";
}

To bind these multiple values into a List, the @RequestParam annotation is mandatory, as Spring defaults to array binding for identical parameter keys.

@RequestMapping("/listParam")
public String handleList(@RequestParam List<String> preferences) {
    System.out.println(preferences);
    return "Processed";
}

1.4 Date Parameters

Date formats vary widely. To deserialize a date string into a temporal object, apply the @DateTimeFormat annotation with a specific pattern matching the incoming string format.

@RequestMapping("/dateParam")
public String handleDate(@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") LocalDateTime timestamp) {
    System.out.println(timestamp);
    return "Processed";
}

1.5 JSON Parameters

In modern front-end/back-end separation architectures, JSON is the standard payload format for POST requests. To map a JSON request body to a POJO, annotate the method argument with @RequestBody. This instructs Spring to deserialize the JSON keys into matching object properties.

@RequestMapping("/jsonPayload")
public String handleJson(@RequestBody Person person) {
    System.out.println(person);
    return "Processed";
}

1.6 Path Parameters

Parameters can also be embedded directly within the URL path rather than as query strings (e.g., /resource/5/department). To capture these, define path variables using curly braces in the mapping annotation and extract them using @PathVariable.

@RequestMapping("/resource/{identifier}/{category}")
public String handlePath(@PathVariable Long identifier, @PathVariable String category) {
    System.out.println(identifier + " : " + category);
    return "Processed";
}

2. Handling Responses

---

2.1 The @ResponseBody Mechanism

For a Controller method to return data directly to the client response body rather than resolving to a view template, it must be annotated with @ResponseBody. If the return type is a POJO or Collection, Spring automatically marshals it into a JSON structure via HttpMessageConverters.

In Spring Boot REST applications, the @RestController annotation is conventionally used at the class level. It is a composite annotation equivalent to @Controller + @ResponseBody, meaning every method within the class automatically serializes its return value to the HTTP response body.

2.2 Unified Response Structure

Returning raw strings, objects, or lists directly leads to inconsistent API contracts, making frontend integration difficult. Best practice dictates encapsulating all responses within a standardized wrapper class containing a status code, a message, and the payload data.

public class ApiResponse {
    private Integer status; // 1: Success, 0: Failure
    private String message;
    private Object payload;

    public ApiResponse(Integer status, String message, Object payload) {
        this.status = status;
        this.message = message;
        this.payload = payload;
    }

    public static ApiResponse ok(Object data) {
        return new ApiResponse(1, "Success", data);
    }
    
    public static ApiResponse ok() {
        return new ApiResponse(1, "Success", null);
    }

    public static ApiResponse fail(String msg) {
        return new ApiResponse(0, msg, null);
    }
    // getters and setters omitted for brevity
}

Refactoring Controller methods to use this wrapper ensures a consistent contract for the client.

@RestController
public class DataController {
    @RequestMapping("/fetchAddress")
    public ApiResponse fetchAddress() {
        Location loc = new Location();
        loc.setState("California");
        loc.setMunicipality("Los Angeles");
        return ApiResponse.ok(loc);
    }
}

2.3 Practical Implementation Case

Consider a requirement to read staff data from an XML file, transform specific numeric codes into descriptive strings, and return a unified JSON response.

Dependencies: Include dom4j in the Maven POM file for XML parsing.

<dependency>
    <groupId>org.dom4j</groupId>
    <artifactId>dom4j</artifactId>
    <version>2.1.3</version>
</dependency>

Initial Monolithic Controller:

@RestController
public class StaffController {
    @RequestMapping("/staffList")
    public ApiResponse listStaff() {
        String filePath = this.getClass().getClassLoader().getResource("staff.xml").getFile();
        List<Staff> staffList = XmlParserUtils.parse(filePath, Staff.class);

        staffList.stream().forEach(staff -> {
            String gender = staff.getGender();
            if ("1".equals(gender)) {
                staff.setGender("Male");
            } else if ("2".equals(gender)) {
                staff.setGender("Female");
            }

            String role = staff.getRole();
            switch (role) {
                case "1": staff.setRole("Instructor"); break;
                case "2": staff.setRole("Administrator"); break;
                case "3": staff.setRole("Counselor"); break;
            }
        });
        return ApiResponse.ok(staffList);
    }
}

3. Layered Architecture and Decoupling

---

3.1 Three-Tier Architecture

The monolithic controller above violates the Single Responsibility Principle by mixing data access, business logic, and request handling. To enhance maintainability and reusability, enterprise applications adopt a Three-Tier Architecture:

• Controller Layer: Handles HTTP routing and response formatting.
• Service Layer: Encapsulates core business rules and data transformation.
• DAO (Data Access Object) Layer: Manages persistence and data retrieval (XML, DB, etc).

Separating these layers ensures that modifications in data retrieval logic or business rules do not leak into the request handling layer.

Refactored Layers:

// DAO Interface & Implementation
public interface StaffDao {
    List<Staff> retrieveAll();
}

public class StaffDaoXmlImpl implements StaffDao {
    @Override
    public List<Staff> retrieveAll() {
        String filePath = this.getClass().getClassLoader().getResource("staff.xml").getFile();
        return XmlParserUtils.parse(filePath, Staff.class);
    }
}

// Service Interface & Implementation
public interface StaffService {
    List<Staff> processAll();
}

public class StaffServiceImpl implements StaffService {
    private StaffDao staffDao = new StaffDaoXmlImpl();

    @Override
    public List<Staff> processAll() {
        List<Staff> staffList = staffDao.retrieveAll();
        staffList.forEach(staff -> {
            staff.setGender("1".equals(staff.getGender()) ? "Male" : "Female");
            // additional role logic...
        });
        return staffList;
    }
}

While this structural separation improves cohesion, the layers remain tightly coupled because objects are manually instantiated using the new keyword (e.g., private StaffDao staffDao = new StaffDaoXmlImpl();). Switching to a different DAO implementation requires modifying the Service class source code.

3.2 Decoupling via IoC and DI

The solution to tight coupling lies in Inversion of Control (IoC) and Dependency Injection (DI).

• IoC: The responsibility of creating and managing object lifecycles is transferred from the developer to a container (the Spring ApplicationContext).
• DI: The container actively provides required dependencies to a component at runtime, replacing manual new declarations.

3.3 Implementing IoC and DI

To delegate object creation to Spring, annotate the implementation classes with @Component or its specialized derivatives. To inject dependencies, use @Autowired.

• @Controller / @RestController: Marks a presentation layer bean.
• @Service: Marks a business logic layer bean.
• @Repository: Marks a data access layer bean.
• @Component: General-purpose bean annotation.

@Repository
public class StaffDaoXmlImpl implements StaffDao { ... }

@Service
public class StaffServiceImpl implements StaffService {
    @Autowired
    private StaffDao staffDao; // Injected by Spring
    ...
}

@RestController
public class StaffController {
    @Autowired
    private StaffService staffService; // Injected by Spring
    ...
}

Component Scanning

Annotations alone do not register beans; they must be discovered via Component Scanning. The @SpringBootApplication annotation inherently includes @ComponentScan, which by default scans the package of the main class and all it sub-packages. Classes defined outside this default scope will not be registered unless scanning is explicitly configured.

Resolving Dependency Conflicts

@Autowired performs injection by type. If the ApplicationContext contains multiple beans of the same interface type (e.g., two StaffDao implementations), Spring will throw a NoUniqueBeanDefinitionException. Resolve this conflict using:

• @Primary: Annotate the preferred implementation to set it as the default injection candidate.
• @Qualifier("beanName"): Pair with @Autowired to specify the exact bean instance by its registered name (default bean name is the class name with a lowercase first letter).
• @Resource(name="beanName"): A JDK-standard annotation that injects explicitly by bean name, rather than by type.

Key Differences: @Autowired is a Spring-specific annotation resolving dependencies by type, whereas @Resource is a Jakarta/Java EE standard resolving dependencies by name.