Building a RESTful Web Service with JAX-RS

<!-- Jakarta EE API — GlassFish provides these at runtime -->
<dependency>
    <groupId>jakarta.platform</groupId>
    <artifactId>jakarta.jakartaee-api</artifactId>
    <version>10.0.0</version>
    <scope>provided</scope>
</dependency>

<!-- MySQL JDBC driver -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

package au.edu.cqu.productrest;

import jakarta.persistence.*;
import java.io.Serializable;

/**
 * JPA ENTITY — each instance represents one row in the "products" table.
 *
 * @Entity              tells JPA "this is a database entity"
 * @Table(name=...)     maps it to the named table
 * @Id                  marks the primary key
 * @GeneratedValue      MySQL auto-increments the ID
 *
 * JSON-B (bundled with GlassFish) automatically converts this object
 * to/from JSON using the getter methods — no extra annotations needed.
 */
@Entity
@Table(name = "products")
public class Product implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    private String description;

    @Column(nullable = false)
    private double price;

    // Default constructor — required by JPA, never remove this
    public Product() {}

    // Getters and Setters — JSON-B uses these for serialisation
    public Long getId()                       { return id; }
    public void setId(Long id)                { this.id = id; }

    public String getName()                   { return name; }
    public void setName(String name)          { this.name = name; }

    public String getDescription()            { return description; }
    public void setDescription(String d)     { this.description = d; }

    public double getPrice()                  { return price; }
    public void setPrice(double price)        { this.price = price; }
}

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="3.0"
  xmlns="https://jakarta.ee/xml/ns/persistence"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence
    https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd">

  <persistence-unit name="ProductPU"
                     transaction-type="JTA">

    <!-- JNDI name MUST match your GlassFish JDBC Resource -->
    <jta-data-source>jdbc/myDatasource</jta-data-source>

    <class>au.edu.cqu.productrest.Product</class>

    <properties>
      <!-- Auto-create tables on first deployment -->
      <property name="jakarta.persistence.schema-generation.database.action"
                value="create"/>
    </properties>
  </persistence-unit>
</persistence>

package au.edu.cqu.productrest;

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

/**
 * JAX-RS APPLICATION CONFIG
 *
 * This class does two things with one annotation:
 *   1. Registers the JAX-RS servlet with GlassFish
 *   2. Sets "/api" as the base path for ALL REST endpoints
 *
 * After this, a resource at @Path("/products") becomes accessible at:
 *   http://localhost:8080/ProductRestService/api/products
 *         |__ context root __|__ app path __|__ resource __|
 *
 * No code needed inside — the annotation does all the work.
 */
@ApplicationPath("/api")
public class RestApplication extends Application {
    // intentionally empty
}

package au.edu.cqu.productrest;

import jakarta.persistence.*;
import jakarta.transaction.Transactional;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.*;
import java.util.List;

/**
 * REST RESOURCE — the equivalent of a Managed Bean in Faces, but instead
 * of rendering XHTML pages it returns JSON over HTTP.
 *
 * @Path("/products")  maps this class to /api/products
 * @Produces(JSON)     all methods return JSON by default
 * @Consumes(JSON)     all methods accept JSON input by default
 * @PersistenceContext  injects the JPA EntityManager
 */
@Path("/products")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ProductResource {

    @PersistenceContext(unitName = "ProductPU")
    private EntityManager em;

    // ── GET /api/products ─────────────────────────────────────────────────
    // Returns ALL products as a JSON array.
    // Empty table → returns []. HTTP status: 200 OK (default).
    @GET
    public List<Product> getAll() {
        return em.createQuery("SELECT p FROM Product p",
                              Product.class).getResultList();
    }

    // ── GET /api/products/{id} ────────────────────────────────────────────
    // Returns ONE product by primary key.
    // @PathParam extracts {id} from the URL.
    // Returns 404 if the ID does not exist.
    @GET
    @Path("/{id}")
    public Response getById(@PathParam("id") Long id) {
        Product p = em.find(Product.class, id);
        if (p == null) {
            return Response.status(404).build();
        }
        return Response.ok(p).build();
    }
}

// ── POST /api/products ────────────────────────────────────────────────
// Creates a new product from the JSON request body.
//
// JSON-B converts the incoming JSON into a Product object automatically.
// Example request body:
//   {"name":"Laptop","description":"A fast laptop","price":999.99}
//
// @Transactional wraps the method in a JTA transaction.
// Without this, em.persist() throws an error because there is
// no active transaction.
//
// Returns 201 Created with the saved product (including generated ID).
@POST
@Transactional
public Response create(Product product) {
    em.persist(product);
    return Response
        .status(Response.Status.CREATED)   // 201
        .entity(product)                   // includes the generated ID
        .build();
}

# Create the first product
curl -X POST http://localhost:8080/ProductRestService/api/products ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"Laptop\",\"description\":\"A fast laptop\",\"price\":999.99}"

# Create a second product
curl -X POST http://localhost:8080/ProductRestService/api/products ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"Wireless Mouse\",\"description\":\"Ergonomic mouse\",\"price\":35.99}"

# Verify both were saved
curl http://localhost:8080/ProductRestService/api/products

// ── PUT /api/products/{id} ────────────────────────────────────────────
// Updates an existing product. ID from URL, new values from JSON body.
// Pattern: find → null check → copy fields → merge → respond.
// Returns 200 OK with updated product, or 404 if not found.
@PUT
@Path("/{id}")
@Transactional
public Response update(@PathParam("id") Long id,
                       Product updated) {
    Product existing = em.find(Product.class, id);
    if (existing == null) {
        return Response.status(404).build();
    }
    existing.setName(updated.getName());
    existing.setDescription(updated.getDescription());
    existing.setPrice(updated.getPrice());
    em.merge(existing);
    return Response.ok(existing).build();       // 200 OK
}

// ── DELETE /api/products/{id} ─────────────────────────────────────────
// Removes a product by ID.
// Returns 204 No Content on success (no response body).
// Returns 404 if the ID does not exist.
@DELETE
@Path("/{id}")
@Transactional
public Response delete(@PathParam("id") Long id) {
    Product p = em.find(Product.class, id);
    if (p == null) {
        return Response.status(404).build();
    }
    em.remove(p);
    return Response.noContent().build();      // 204 No Content
}