Response and Resources

🍕 RESTful Web Services: Response and Resources

The Pizza Delivery Story

Imagine you run a magical pizza delivery service. Customers call you (send requests), and you need to:

• Package the pizza properly (Entity Providers)
• Speak their language (Content Negotiation)
• Handle complaints gracefully (Exception Mappers)
• Build the delivery box (Response Building)
• Fix mistakes when things go wrong (REST Error Handling)
• Manage multiple shops (Sub-Resources)
• Call other pizza shops for help (Client API)

Let’s learn how Jakarta EE helps you run this pizza empire! 🚀

🎁 Entity Providers: The Packaging Masters

What Are They?

Entity Providers are like gift wrappers. They take your pizza (Java object) and wrap it nicely for delivery (JSON, XML).

There are two types:

• MessageBodyWriter → Wraps your gift (Java → JSON)
• MessageBodyReader → Unwraps a gift (JSON → Java)

Simple Example

Think of it like this:

• Customer orders online → You get JSON text
• Your system needs a Pizza object
• MessageBodyReader transforms text into a pizza!

@Provider
@Produces("application/json")
public class PizzaWriter
    implements MessageBodyWriter<Pizza> {

    @Override
    public void writeTo(Pizza pizza, ...) {
        // Turn pizza into JSON text
        String json = "{\"name\":\""
            + pizza.getName() + "\"}";
        outputStream.write(json.getBytes());
    }
}

The Magic Flow

graph TD
    A["Java Pizza Object"] --> B["MessageBodyWriter"]
    B --> C["JSON Text"]
    C --> D["Sent to Customer"]
    E["JSON from Customer"] --> F["MessageBodyReader"]
    F --> G["Java Pizza Object"]

When to Use Custom Providers

✅ Special data formats (not just JSON/XML) ✅ Need extra processing (compression, encryption) ✅ Working with legacy systems

🗣️ Content Negotiation: Speaking Their Language

What Is It?

Your customer calls and says “I speak French!” Content Negotiation is how you figure out which language to respond in.

In REST, customers ask for specific formats:

• “Give me JSON!” → Accept: application/json
• “Give me XML!” → Accept: application/xml

How It Works

@GET
@Path("/menu")
@Produces({"application/json",
           "application/xml"})
public List<Pizza> getMenu() {
    return pizzaService.getAllPizzas();
}

The server checks the customer’s Accept header and picks the best match!

The Decision Flow

graph TD
    A["Customer Request"] --> B{Accept Header?}
    B -->|application/json| C["Return JSON"]
    B -->|application/xml| D["Return XML"]
    B -->|No Preference| E["Use Default"]

Consuming Content

For incoming data, use @Consumes:

@POST
@Path("/order")
@Consumes("application/json")
@Produces("application/json")
public Pizza createOrder(Pizza pizza) {
    return pizzaService.save(pizza);
}

This says: “I understand JSON orders and reply in JSON too!”

⚠️ Exception Mappers: The Complaint Department

What Are They?

Sometimes things go wrong. A customer orders a pizza that doesn’t exist! Exception Mappers are your complaint handlers — they turn ugly errors into friendly messages.

The Problem Without Mappers

Without them, customers see scary error pages with technical jargon. Not good! 😱

The Solution

@Provider
public class PizzaNotFoundMapper
    implements ExceptionMapper<PizzaNotFound> {

    @Override
    public Response toResponse(
        PizzaNotFound ex) {

        return Response
            .status(404)
            .entity("Sorry! That pizza " +
                    "doesn't exist.")
            .build();
    }
}

How It Works

graph TD
    A["Error Happens!"] --> B["ExceptionMapper"]
    B --> C["Creates Nice Response"]
    C --> D["Customer Gets Friendly Message"]

Real-World Tips

✅ Create mappers for common exceptions ✅ Return proper HTTP status codes ✅ Include helpful error messages ✅ Log errors for debugging

🏗️ Response Building: Crafting Perfect Deliveries

What Is Response Building?

It’s like packing a delivery box with:

• The pizza (entity body)
• A receipt (status code)
• Special notes (headers)

The Response Class

@GET
@Path("/pizza/{id}")
public Response getPizza(@PathParam("id") int id) {
    Pizza pizza = service.find(id);

    if (pizza == null) {
        return Response
            .status(Response.Status.NOT_FOUND)
            .build();
    }

    return Response
        .ok(pizza)
        .header("X-Pizza-Hot", "true")
        .build();
}

Common Response Builders

Building with Headers

return Response
    .ok(pizza)
    .type(MediaType.APPLICATION_JSON)
    .header("Cache-Control", "max-age=3600")
    .lastModified(pizza.getUpdatedAt())
    .build();

🛠️ REST Error Handling: Fixing Problems Gracefully

Why Proper Error Handling?

Bad error handling = frustrated customers Good error handling = happy customers who understand what went wrong

Best Practice: Error Response Structure

public class ErrorResponse {
    private int code;
    private String message;
    private String details;

    // Constructor and getters
}

Handling Different Errors

@Provider
public class GenericExceptionMapper
    implements ExceptionMapper<Exception> {

    @Override
    public Response toResponse(Exception ex) {

        ErrorResponse error = new ErrorResponse(
            500,
            "Something went wrong!",
            ex.getMessage()
        );

        return Response
            .status(500)
            .entity(error)
            .type(MediaType.APPLICATION_JSON)
            .build();
    }
}

HTTP Status Code Cheat Sheet

graph TD
    A["Status Codes"] --> B["2xx Success"]
    A --> C["4xx Client Error"]
    A --> D["5xx Server Error"]
    B --> E["200 OK, 201 Created"]
    C --> F["400 Bad Request"]
    C --> G["404 Not Found"]
    D --> H["500 Internal Error"]

🏢 REST Sub-Resources: Managing Multiple Shops

What Are Sub-Resources?

Imagine your pizza empire has many locations. Each location has its own menu. Sub-Resources help organize this!

/shops/{shopId}/pizzas/{pizzaId}

It’s like folders inside folders!

How to Create Sub-Resources

Step 1: Parent Resource

@Path("/shops")
public class ShopResource {

    @Path("/{shopId}/pizzas")
    public PizzaSubResource getPizzas(
        @PathParam("shopId") int shopId) {

        return new PizzaSubResource(shopId);
    }
}

Step 2: Sub-Resource Class

public class PizzaSubResource {
    private int shopId;

    public PizzaSubResource(int shopId) {
        this.shopId = shopId;
    }

    @GET
    @Produces("application/json")
    public List<Pizza> getAll() {
        return service.getPizzasByShop(shopId);
    }

    @GET
    @Path("/{pizzaId}")
    public Pizza getOne(
        @PathParam("pizzaId") int id) {
        return service.getPizza(shopId, id);
    }
}

The Structure

graph TD
    A["/shops"] --> B["/shops/1"]
    B --> C["/shops/1/pizzas"]
    C --> D["/shops/1/pizzas/42"]

📞 Client API: Calling Other Services

What Is It?

Sometimes your pizza shop needs to call another service — maybe to check ingredient prices or order supplies. The JAX-RS Client API is your phone line to other REST services!

Creating a Client

// Step 1: Create the client
Client client = ClientBuilder.newClient();

// Step 2: Target a URL
WebTarget target = client
    .target("https://api.ingredients.com")
    .path("/cheese/prices");

// Step 3: Make the call
Response response = target
    .request(MediaType.APPLICATION_JSON)
    .get();

// Step 4: Read the response
CheesePrice price = response
    .readEntity(CheesePrice.class);

// Step 5: Clean up
client.close();

Different HTTP Methods

// GET
target.request().get();

// POST with body
target.request()
    .post(Entity.json(newOrder));

// PUT
target.request()
    .put(Entity.json(updatedOrder));

// DELETE
target.request().delete();

Adding Headers

Response response = target
    .request()
    .header("Authorization", "Bearer token123")
    .header("X-Custom-Header", "value")
    .get();

Async Calls

Don’t want to wait? Make it async!

Future<Response> future = target
    .request()
    .async()
    .get();

// Do other stuff...

// Then get the result when ready
Response response = future.get();

🎯 Quick Summary

🌟 You Did It!

You now understand how Jakarta EE handles REST responses and resources! Think of yourself as the master pizza delivery manager who knows:

• ✅ How to package orders (Entity Providers)
• ✅ How to speak any language (Content Negotiation)
• ✅ How to handle complaints (Exception Mappers)
• ✅ How to build perfect deliveries (Response Building)
• ✅ How to fix problems (Error Handling)
• ✅ How to manage multiple locations (Sub-Resources)
• ✅ How to call other services (Client API)

You’re ready to build amazing REST APIs! 🚀🍕