Assignment 2 API

package your implementation along proper module boundaries

Create your overall project as two (or more) Maven modules under a single parent

Define the module as a Web Application (dependency on spring-boot-starter-web).

Add a @SpringBootApplication class to the app module (already provided in starter for initial demo).

Once constructed, the modules should be able to

package your implementation along proper module boundaries

Pick a Maven hierarchical groupId for your modules that is unique to your overall work on this assignment.

design a set of Data Transfer Objects (DTOs) to render information from and to the service

define a Java class content type mappings to customize marshalling/unmarshalling

specify content types consumed and produced by a controller

specify content types accepted by a client

Create a DTO class to represent HomeSale

Create a HomeSaleListDTO class to provided a typed collection of HomeSaleDTO.

Map each DTO class to:

Create a unit test to verify your new DTO type(s) can be marshalled/unmarshalled to/from the targeted serialization type.

API TODO: Annotate controller methods to consume and produce supported content type(s) when they are implemented.

API TODO: Update clients used in unit tests to explicitly only accept supported content type(s) when they are implemented.

design a set of Data Transfer Objects (DTOs) to render information from and to the service

define a Java class content type mappings to customize marshalling/unmarshalling

API TODO: specify content types consumed and produced by a controller

API TODO: specify content types accepted by a client

This portion of the assignment alone primarily produces a set of information classes that make up the primary vocabulary of your API and service classes.

Use of lombok is highly encouraged here and can tremendously reduce the amount of code you write for these classes

Java Period class can easily calculate age in years between two LocalDates.

There are several states for a HomeSaleDTO. It would be helpful to create constructors and compound business methods around these states within the in the HomeSaleDTO class.

The homebuyers-support-api-client module also provides a HomeDTOFactory, BuyerDTOFactory, and StreetAddressDTOFactory that makes it easy for tests and other demonstration code to quickly assembly example instances. You are encouraged to follow that pattern. However, keep your known client-side states and information sources in mind when creating the factory methods.

The homebuyers-support-api-client test cases for Home and Buyer demonstrate marshalling and unmarshalling DTO classes within a JUnit test. You should create a similar test of your HomeBuyerDTO class to satisfy the testing requirement. Note that those tests leverage a JsonUtil class that is part of the class utility examples and simplifies example use of the Jackson JSON parser.

The homebuyers-support-api-client and supplied starter unit tests make use of JUnit @ParameterizedTest — which allows a single JUnit test method to be executed N times with variable parameters — pretty cool feature. Try it.

Supporting multiple content types is harder than it initially looks — especially when trying to mix different libraries. WebClient does not currently support Jackson XML and will attempt to resort to using JAXB in the client. I provide an example of this later in the semester (Spring Data JPA End-to-End) and advise you to address the optional XML mapping last after all other requirements of the assignment are complete. If you do attempt to tackle both XML and WebClient together, know to use JacksonXML mappings for the server-side and JAXB mappings for the client-side.

identify resources

define a URI for a resource

define the proper method for a call against a resource

identify appropriate response code family and value to use in certain circumstances

Homes (provided) - an individual home that can be part of a home sale

Buyers (provided) - identification for a person that may participate in a home sale

HomeSales (your assignment) - a transaction for one Home and 0..1 Buyer

Identify your base resource(s) and sub-resource(s)

Identify the @RestController methods required to represent the following actions for HomeSale. Assign them specific URIs and HTTP methods.

CLIENT TODO: Identify the response status codes to be returned for each of the actions

identify resources

define a URI for a resource

define the proper method for a call against a resource

CLIENT TODO: identify appropriate response code family and value to use in certain circumstances

This portion of the assignment alone should produce a @RestController class with annotated methods that statically define your API interface (possibly missing content details). There is nothing to run or test in this portion alone.

A simple and useful way of expressing your URIs can be through defining a set of public static attributes expressing the collection and individual instance of the resource type.

public static final String (RESOURCE)S_PATH="(path)";
public static final String (RESOURCE)_PATH="(path)/{identifier(s)}";

If you start with this portion, you may find it helpful to

The details of the HomeSale will be performed server-side — based upon IDs and optional properties provided by the client and the Home and Buyer values found server-side. The client never provides more than an ID to reference information available server-side.

There is nothing to code up relative to response codes at this point. However:

implement a service method with Spring MVC synchronous annotated controller

implement a client using Spring MVC RestTemplate or Spring Webflux (in synchronous mode)

pass parameters between client and service over HTTP

return HTTP response details from service

access HTTP response details in client

Implement stub behavior in the controller class as necessary to complete the example end-to-end calls.

return ResponseEntity.status(HttpStatus.CREATED)
    .body(HomeDTO.builder()
        .id("1")
        .build());

Implement a unit integration test to demonstrate a success path

implement a service method with Spring MVC synchronous annotated controller

implement a client using Spring MVC RestTemplate or Spring Webflux WebClient (in synchronous mode)

pass parameters between client and service over HTTP

return HTTP response details from service

access HTTP response details in client

Your DTO class(es) have been placed in your Client module in a separate section of this assignment. You may want to add an optional API client class to that Client module — to encapsulate the details of the RestTemplate or WebClient calls. The homebuyers-support-client module contains example client API classes for Homes and Buyers using RestTemplate.

Avoid placing extensive business logic into the stub portion of the assignment. The controller method details are part of a separate section of this assignment.

This portion of the assignment alone should produce a simple, but significant demonstration of client/API communications (success and failure) using HTTP and service as the model for implementing additional resource actions.

Inject the dependencies for the test from the Spring context. Anything that depends on the server’s port number must be delayed (@Lazy)

@Bean @Lazy (2)
public ServerConfig serverConfig(@LocalServerPort int port) { (1)
    return new ServerConfig().withPort(port).build();
}
@Bean @Lazy (3)
public HomesAPI homesAPI(RestTemplate restTemplate, ServerConfig serverConfig) {
    return new HomesAPIClient(restTemplate, serverConfig, MediaType.APPLICATION_JSON);
}

@SpringBootTest(...webEnvironment=...
public class HomeSalesAPINTest {
    @Autowired
    private HomesAPI homesAPI;

implement a service class to encapsulate business logic

turn @RestController class into a facade and delegate business logic details to an injected service class

implement an error reporting strategy

Implement a HomeSaleDTORepository interface and implementation component to simulate necessary behavior (e.g., save, findById) for the base HomeSaleDTO resource type. Don’t go overboard here. We just need some place to generate IDs and hold the data in memory.

Implement a HomeSale service to implement actions and enforce business logic on the base resources

Design a means for service calls to

Integrate services into controller components

Implement a unit integration test to demonstrate at least one success and error path

implement a service class to encapsulate business logic

turn @RestController class into a facade and delegate business logic details to an injected service class

implement an error reporting strategy

This portion of the assignment alone primarily provides an implementation pattern for how services will report successful and unsuccessful requests and how the API will turn that into a meaningful HTTP response that the client can access.

The homebuyers-support-api-svc module contains a set of example DTO Repository Stubs.

You are required to use the Pageable and Page classes (from the org.springframework.data.domain Java package) for paging methods in your getAllHomeSales() service interface — to be forward compatible with later assignments that make use of Spring Data. You can find example use of Pageable and Page (and PageImpl) in Home and Buyer examples.

It is highly recommend that exceptions be used between the service and controller layers to identify error scenarios and specific exceptions be used to help identify which kind of error is occurring in order to report accurate status to the client. Leave non-exception paths for successful results. The Homes and Buyers example leverage the exceptions defined in the ejava-dto-util module. You are free to define your own.

It is highly recommended that ExceptionHandlers and RestExceptionAdvice be used to handle exceptions thrown and report status. The Homes and Buyers example leverage the ExceptionHandlers from the ejava-web-util module. You are free to define your own.

Implement the above scenarios within one or more integration unit tests.

Name the tests such that they are picked up and executed by the Surefire test phase of the maven build.

Turn in a cleaned source tree of the project under a single root parent project. The Home and Buyer modules do not need to be included.

The source tree should be ready to build in an external area that has access to the ejava-nexus repository.

create an integration test that verifies a successful scenario

create an integration test that verifies a failure scenario

Place behavior in the proper place