Skip to main content

juneau-examples-rest-jetty

The juneau-examples-rest-jetty module demonstrates how to deploy Juneau REST servers using embedded Jetty server for standalone microservice applications.

Overview​

This example shows how to create a lightweight, self-contained REST microservice using Apache Juneau's Jetty integration. It's perfect for scenarios where you need a standalone application that can be easily deployed and run without external dependencies.

Getting Started​

Prerequisites​

  • Java 17+
  • Maven 3.6+

Dependencies​

Add the following dependencies to your project:

<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-microservice-jetty</artifactId>
    <version>${juneau.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-examples-rest</artifactId>
    <version>${juneau.version}</version>
</dependency>

Example Implementation​

Main Application Class​

The example demonstrates a simple REST microservice using the App class:

package org.apache.juneau.examples.rest.jetty;

import org.apache.juneau.examples.rest.RootResources;
import org.apache.juneau.microservice.jetty.*;

public class App {
    public static void main(String[] args) throws Exception {
        JettyMicroservice
            .create()
            .args(args)
            .servlet(RootResources.class)
            .build()
            .start()
            .startConsole()
            .join();
    }
}

Key Features​

  • Embedded Jetty Server - No external servlet container required
  • Standalone Application - Can be run as a simple JAR file
  • Configuration Support - Uses examples.cfg configuration file
  • Console Interface - Built-in management console
  • Resource Integration - Seamlessly integrates with juneau-examples-rest resources

Configuration​

Configuration File​

The application looks for an examples.cfg file in the home directory. This file can contain various configuration options:

# Server configuration
server.port=8080
server.host=localhost

# Logging configuration
logging.level=INFO
logging.file=microservice.log

# REST configuration
rest.path=/api
rest.serializers=JsonSerializer,XmlSerializer
rest.parsers=JsonParser,XmlParser

Command Line Arguments​

The application accepts standard command line arguments:

java -jar juneau-examples-rest-jetty.jar --port=8080 --host=0.0.0.0

Running the Example​

Development Mode​

# Clone the repository
git clone https://github.com/apache/juneau.git
cd juneau

# Build the project
mvn clean package

# Run the Jetty example
java -jar juneau-examples/juneau-examples-rest-jetty/target/juneau-examples-rest-jetty-${version}.jar

Production Deployment​

# Run with custom configuration
java -jar juneau-examples-rest-jetty.jar --config=/path/to/config.cfg

# Run with specific port
java -jar juneau-examples-rest-jetty.jar --port=9090

# Run with console disabled
java -jar juneau-examples-rest-jetty.jar --no-console

Available Endpoints​

Once running, the application provides access to all the REST examples from the juneau-examples-rest module:

  • Root Resources - GET /api/
  • Hello World - GET /api/helloWorld
  • Request Echo - GET /api/requestEcho
  • Photos - GET /api/photos
  • DTO Bean Examples - Various DTO bean demonstration endpoints

Architecture​

JettyMicroservice Class​

The App class provides:

  • Embedded Jetty Server - Lightweight HTTP server
  • REST Servlet Integration - Automatic servlet registration
  • Configuration Management - File and command-line configuration
  • Console Interface - Built-in management and monitoring
  • Graceful Shutdown - Proper resource cleanup

Resource Integration​

The example integrates with the juneau-examples-rest module, providing:

  • Pre-built REST Resources - Ready-to-use example endpoints
  • DTO Bean Examples - Various data transfer object bean demonstrations
  • Command Patterns - Example command implementations
  • Utility Resources - Common utility endpoints

Development Patterns​

Custom Microservice​

You can extend the App class for custom behavior:

public class CustomApp extends JettyMicroservice {
    
    @Override
    protected void configure() {
        // Custom configuration
        setPort(9090);
        setHost("0.0.0.0");
        addServlet(CustomResource.class);
    }
    
    public static void main(String[] args) throws Exception {
        new CustomApp().start().join();
    }
}

Multiple Servlets​

Register multiple REST servlets:

JettyMicroservice
    .create()
    .servlet(RootResources.class, "/api/*")
    .servlet(AdminResources.class, "/admin/*")
    .servlet(PublicResources.class, "/public/*")
    .build()
    .start();

Testing​

Integration Tests​

The module includes integration tests in juneau-examples-rest-jetty-ftest:

  • Root Content Tests - Verify root endpoint responses
  • Resource Tests - Test individual REST resources
  • End-to-End Tests - Complete request/response cycle testing

Running Tests​

# Run integration tests
mvn test -pl juneau-examples/juneau-examples-rest-jetty-ftest

# Run with specific test
mvn test -pl juneau-examples/juneau-examples-rest-jetty-ftest -Dtest=RootResourcesTest

Deployment Options​

JAR Deployment​

# Create executable JAR
mvn clean package

# Run standalone
java -jar target/juneau-examples-rest-jetty-${version}.jar

Docker Deployment​

FROM openjdk:17-jre-slim
COPY target/juneau-examples-rest-jetty.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

System Service​

Create a systemd service file:

[Unit]
Description=Juneau REST Jetty Example
After=network.target

[Service]
Type=simple
User=juneau
ExecStart=/usr/bin/java -jar /opt/juneau/juneau-examples-rest-jetty.jar
Restart=always

[Install]
WantedBy=multi-user.target

Monitoring and Management​

Built-in Console​

The application includes a management console accessible at /console:

  • Server Status - Current server state and metrics
  • Configuration - View and modify configuration
  • Logs - Real-time log viewing
  • Health Checks - Application health status

Health Endpoints​

Standard health check endpoints:

  • GET /health - Basic health status
  • GET /health/detailed - Detailed health information
  • GET /metrics - Application metrics

Best Practices​

Configuration Management​

  • Use environment-specific configuration files
  • Implement configuration validation
  • Support hot configuration reloading

Error Handling​

  • Implement comprehensive error handling
  • Provide meaningful error messages
  • Log errors appropriately

Performance​

  • Configure appropriate thread pools
  • Monitor memory usage
  • Implement request timeouts

Security​

  • Implement authentication and authorization
  • Use HTTPS in production
  • Validate all inputs
juneau-examples-rest - REST API examplesjuneau-examples-rest-springboot - Spring Boot examplesJuneau Microservice Core - Core microservice componentsJuneau REST Server Basics - REST server fundamentals

Source Code​

The complete source code for the Jetty examples is available in the juneau-examples-rest-jetty module of the Apache Juneau project.

Contributing​

To contribute improvements to the Jetty examples:

  1. Follow the established patterns in the existing code
  2. Include comprehensive tests
  3. Update documentation when adding new features
  4. Ensure backward compatibility