Jersey Java Tutorial – Building RESTful Web Services

Jersey serves as Oracle’s official implementation of the JAX-RS standard for developing RESTful services in Java. If you’ve faced challenges in constructing APIs that deliver performance and scalability, Jersey presents a reliable framework that simplifies the complexity while allowing precise control over your service setup. This guide will lead you through creating resilient REST APIs with Jersey, from the fundamentals of resource creation to advanced topics such as custom providers, configuring clients, and deploying in real-world scenarios.

Understanding Jersey’s Inner Workings

As a servlet-based framework, Jersey implements the JAX-RS specification, providing a complete runtime environment for RESTful web services. Fundamentally, Jersey utilises annotation-driven programming, where resources are represented as straightforward Java classes decorated with JAX-RS annotations such as @Path, @GET, and @POST.

The framework features an intricate processing pipeline that encompasses resource identification, method selection, parameter injection, and response formulation. Jersey’s container abstraction facilitates its operation across various environments, including Grizzly, Jetty, Tomcat, and Java EE application Servers.

Some fundamental architectural components are:

• Resource classes dedicated to processing HTTP requests
• Providers for managing serialization, deserialization, and various cross-cutting concerns
• Filters and interceptors for request/response handling
• Client API designed for accessing RESTful services
• Integration with dependency injection tools like HK2 and others

Detailed Implementation Guide

Let’s create a complete RESTful service from scratch. Start by setting up your Maven project with the required dependencies:

    
        org.glassfish.jersey.containers
        jersey-container-grizzly2-http
        3.1.3
    
    
        org.glassfish.jersey.media
        jersey-media-json-jackson
        3.1.3
    
    
        org.glassfish.jersey.inject
        jersey-hk2
        3.1.3
    

Create a basic resource class for user management:

@Path("/users")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class UserResource {
    
    private static final Map users = new ConcurrentHashMap<>();
    private static final AtomicInteger idCounter = new AtomicInteger(1);
    
    @GET
    public Response getAllUsers() {
        return Response.ok(new ArrayList<>(users.values())).build();
    }
    
    @GET
    @Path("/{id}")
    public Response getUser(@PathParam("id") int id) {
        User user = users.get(id);
        if (user == null) {
            return Response.status(Response.Status.NOT_FOUND)
                          .entity("User not found").build();
        }
        return Response.ok(user).build();
    }
    
    @POST
    public Response createUser(User user) {
        if (user.getName() == null || user.getName().trim().isEmpty()) {
            return Response.status(Response.Status.BAD_REQUEST)
                          .entity("Name is required").build();
        }
        
        int id = idCounter.getAndIncrement();
        user.setId(id);
        users.put(id, user);
        
        return Response.status(Response.Status.CREATED)
                      .entity(user)
                      .location(URI.create("/users/" + id))
                      .build();
    }
    
    @PUT
    @Path("/{id}")
    public Response updateUser(@PathParam("id") int id, User updatedUser) {
        if (!users.containsKey(id)) {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
        
        updatedUser.setId(id);
        users.put(id, updatedUser);
        return Response.ok(updatedUser).build();
    }
    
    @DELETE
    @Path("/{id}")
    public Response deleteUser(@PathParam("id") int id) {
        User removedUser = users.remove(id);
        if (removedUser == null) {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
        return Response.ok().build();
    }
}

Now, let’s create the User model class:

public class User {
    private int id;
    private String name;
    private String email;
    private LocalDateTime createdAt;
    
    public User() {
        this.createdAt = LocalDateTime.now();
    }
    
    public User(String name, String email) {
        this();
        this.name = name;
        this.email = email;
    }
    
    // Getters and setters
    public int getId() { return id; }
    public void setId(int id) { this.id = id; }
    
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public LocalDateTime getCreatedAt() { return createdAt; }
    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }
}

Next, create the main application class to initiate the server:

public class RestServiceApplication {
    
    public static void main(String[] args) {
        final ResourceConfig config = new ResourceConfig();
        config.packages("com.example.resources");
        config.register(JacksonFeature.class);
        
        // Configure Jackson for LocalDateTime serialization
        config.register(new AbstractBinder() {
            @Override
            protected void configure() {
                ObjectMapper mapper = new ObjectMapper();
                mapper.registerModule(new JavaTimeModule());
                mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
                bind(mapper).to(ObjectMapper.class);
            }
        });
        
        final HttpServer server = GrizzlyHttpServerFactory
            .createHttpServer(URI.create("http://localhost:8080/api/"), config);
        
        try {
            server.start();
            System.out.println("Jersey app started at http://localhost:8080/api/");
            System.out.println("Press CTRL+C to terminate the server...");
            Thread.currentThread().join();
        } catch (Exception e) {
            System.err.println("Error initializing server: " + e.getMessage());
        } finally {
            server.shutdownNow();
        }
    }
}

Practical Examples and Use Cases

Jersey shines in various production contexts. Here’s an advanced example implementing a notification service with custom filters and error handling:

@Path("/notifications")
@Produces(MediaType.APPLICATION_JSON)
public class NotificationResource {
    
    @Inject
    private NotificationService notificationService;
    
    @POST
    @Path("/send")
    @Authenticated // Custom security annotation
    @RateLimited(requests = 100, window = "1m") // Custom rate limiting
    public Response sendNotification(
            @Valid NotificationRequest request,
            @Context SecurityContext securityContext) {
        
        try {
            String userId = securityContext.getUserPrincipal().getName();
            NotificationResult result = notificationService
                .sendNotification(userId, request);
            
            return Response.ok(result).build();
            
        } catch (QuotaExceededException e) {
            return Response.status(429)
                          .entity(Map.of("error", "Rate limit exceeded"))
                          .build();
        } catch (ValidationException e) {
            return Response.status(400)
                          .entity(Map.of("error", e.getMessage()))
                          .build();
        }
    }
    
    @GET
    @Path("/history")
    public Response getNotificationHistory(
            @QueryParam("limit") @DefaultValue("50") int limit,
            @QueryParam("offset") @DefaultValue("0") int offset,
            @QueryParam("status") String status) {
        
        NotificationQuery query = NotificationQuery.builder()
            .limit(Math.min(limit, 100)) // Prevent excessive queries
            .offset(offset)
            .status(status)
            .build();
            
        Page notifications = notificationService
            .getNotifications(query);
            
        return Response.ok(notifications)
                      .header("X-Total-Count", notifications.getTotalElements())
                      .build();
    }
}

Create custom exception mappers for enhanced error management:

@Provider
public class ValidationExceptionMapper implements ExceptionMapper {
    
    @Override
    public Response toResponse(ValidationException exception) {
        ErrorResponse error = new ErrorResponse(
            "VALIDATION_ERROR",
            exception.getMessage(),
            exception.getViolations()
        );
        
        return Response.status(Response.Status.BAD_REQUEST)
                      .entity(error)
                      .build();
    }
}

@Provider
public class GenericExceptionMapper implements ExceptionMapper {
    
    private static final Logger logger = LoggerFactory.getLogger(GenericExceptionMapper.class);
    
    @Override
    public Response toResponse(Exception exception) {
        logger.error("Unhandled exception", exception);
        
        ErrorResponse error = new ErrorResponse(
            "INTERNAL_ERROR",
            "An internal error occurred",
            null
        );
        
        return Response.status(Response.Status.INTERNAL_SERVER_ERROR)
                      .entity(error)
                      .build();
    }
}

Comparative Frameworks and Performance Assessment

Feature	Jersey	Spring Boot	Quarkus	Micronaut
Startup Time	~2-3 seconds	~4-6 seconds	~0.3-0.8 seconds	~1-2 seconds
Memory Usage (Basic API)	~80-120 MB	~150-200 MB	~30-50 MB	~60-90 MB
Throughput (req/sec)	~25,000-35,000	~20,000-30,000	~40,000-50,000	~35,000-45,000
JAX-RS Compliance	Full (Reference Implementation)	Partial via Jersey	Full via RESTEasy	Custom Implementation
Learning Curve	Moderate	Easy	Moderate	Moderate
Container Support	Excellent	Excellent	Excellent (Native)	Good

Performance tests indicate that Jersey reliably achieves substantial throughput while maintaining reasonable resource usage. In real-world applications managing over 10,000 concurrent users, Jersey typically keeps response times under 100ms for straightforward CRUD operations when optimally configured.

Optimal Practices and Frequent Missteps

Below are tried-and-true strategies that can lessen your debugging woes:

• Always utilize Response objects instead of returning entities directly for enhanced control over HTTP status codes and headers
• Establish appropriate exception mappers to prevent exposing stack traces to users
• Employ @Valid annotations alongside Bean Validation for automatic input checks
• Set up connection pooling and timeouts for database links
• Implement proper logging in structured formats for monitoring in production

Common pitfalls to steer clear of:

• Neglecting to register providers in your ResourceConfig
• Handling JSON serialization exceptions inadequately
• Engaging in blocking I/O operations in resource methods without proper thread pool management
• Ignoring appropriate HTTP status codes (e.g., returning 200 for everything)
• Overlooking essential CORS headers for web applications

Set up a production-ready filter for CORS and security headers:

@Provider
@PreMatching
public class CorsAndSecurityFilter implements ContainerRequestFilter, ContainerResponseFilter {
    
    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {
        // Handle preflight requests
        if ("OPTIONS".equals(requestContext.getMethod())) {
            requestContext.abortWith(Response.ok().build());
        }
    }
    
    @Override
    public void filter(ContainerRequestContext requestContext, 
                      ContainerResponseContext responseContext) throws IOException {
        
        // CORS headers
        responseContext.getHeaders().add("Access-Control-Allow-Origin", "*");
        responseContext.getHeaders().add("Access-Control-Allow-Methods", 
            "GET, POST, PUT, DELETE, OPTIONS");
        responseContext.getHeaders().add("Access-Control-Allow-Headers", 
            "Content-Type, Authorization, X-Requested-With");
        
        // Security headers
        responseContext.getHeaders().add("X-Content-Type-Options", "nosniff");
        responseContext.getHeaders().add("X-Frame-Options", "DENY");
        responseContext.getHeaders().add("X-XSS-Protection", "1; mode=block");
    }
}

For production setups, consider using Jersey with asynchronous processing for I/O-heavy tasks:

@GET
@Path("/heavy-operation")
public void heavyOperation(@Suspended AsyncResponse asyncResponse) {
    CompletableFuture.supplyAsync(() -> {
        // Simulated heavy processing
        try {
            Thread.sleep(2000);
            return performDatabaseQuery();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }).whenComplete((result, throwable) -> {
        if (throwable != null) {
            asyncResponse.resume(Response.serverError().build());
        } else {
            asyncResponse.resume(Response.ok(result).build());
        }
    });
}

The Jersey client API is equally potent for interacting with external services. Configure it with appropriate timeouts and connection pooling:

public class ExternalServiceClient {
    
    private final Client client;
    
    public ExternalServiceClient() {
        ClientConfig config = new ClientConfig();
        config.property(ClientProperties.CONNECT_TIMEOUT, 5000);
        config.property(ClientProperties.READ_TIMEOUT, 10000);
        config.connectorProvider(new ApacheConnectorProvider());
        
        this.client = ClientBuilder.newClient(config);
    }
    
    public Optional fetchData(String id) {
        try {
            Response response = client
                .target("https://api.external-service.com")
                .path("/data/{id}")
                .resolveTemplate("id", id)
                .request(MediaType.APPLICATION_JSON)
                .header("Authorization", "Bearer " + getAccessToken())
                .get();
                
            if (response.getStatus() == 200) {
                return Optional.of(response.readEntity(ExternalData.class));
            }
            return Optional.empty();
            
        } catch (Exception e) {
            logger.error("Failed to fetch external data", e);
            return Optional.empty();
        }
    }
}

The Jersey ecosystem integrates seamlessly with monitoring solutions such as Micrometer for metrics gathering and distributed tracing through OpenTelemetry. To explore comprehensive documentation and advanced capabilities, visit the official Jersey documentation and the JAX-RS specification. These resources provide extensive insights into advanced features like server-sent events, WebSocket integration, and custom injection providers that can significantly enhance your REST service functionality.

---

---

This article includes information and material from various online sources. We acknowledge and appreciate the contributions of all original authors, publishers, and websites. While every effort has been made to appropriately credit the source material, any unintentional oversight or omission does not constitute a copyright infringement. All trademarks, logos, and images mentioned are the property of their respective owners. If you believe that any content used in this article infringes upon your copyright, please contact us immediately for review and prompt action.

This article is meant for informational and educational purposes only and does not infringe on the rights of copyright owners. If any copyrighted material has been used without proper credit or in violation of copyright laws, this is unintentional, and we will promptly rectify it upon notification. Please note that the republication, redistribution, or reproduction of part or all of the contents in any form is prohibited without express written permission from the author and website owner. For permissions or further inquiries, please contact us.