📢 Documentation Update
This README has been updated to reflect our new Docusaurus-based documentation site. For the most current documentation, please visit the official Apache Juneau website.

Apache Juneau

Apache Juneau™ is a single cohesive Java ecosystem consisting of a comprehensive toolkit for marshalling POJOs to a wide variety of content types using a common framework, along with universal REST server and client APIs for creating Swagger-based self-documenting REST interfaces.

⚠️ Upgrading from 9.x? The project is currently developing the 10.0.0 release, which includes a number of breaking changes (the public ObjectRest class removed, SerializerSet/ParserSet lookups now returning Optional, the next-gen RestClient no longer implicitly defaulting to JSON, the juneau-assertions/juneau-bct/juneau-junit5 modules merged into a single juneau-test artifact, and the legacy juneau-my-jetty-microservice/juneau-examples-rest modules removed, among others). See the 10.0.0 Migration Guide for the full list before upgrading.

Key Features

• Universal Serialization - Marshal POJOs to JSON, XML, HTML, URL-Encoding, UON, MessagePack, CSV, and more
• REST Services - Create self-documenting REST interfaces with automatic Swagger/OpenAPI generation
• Microservices - Build lightweight, standalone microservices with embedded Jetty
• Configuration Management - Sophisticated configuration file API with variable resolution
• Fluent Assertions - Powerful testing framework with fluent-style assertions
• Type Conversion - Lightweight, MarshallingContext-free converter framework with caching and broad type support
• Large-Dataset Streaming - BeanSupplier/BeanConsumer/BeanChannel APIs for serializing and parsing large datasets without loading all elements into memory; supports direct database integration via lifecycle methods (begin/acceptThrows/onError/complete)
• MCP (Model Context Protocol) Support - First-party server and client support for exposing REST resources as MCP tools/prompts/resources, or consuming MCP servers from Java, for both the 2025-06-18 and 2026-07-28 protocol revisions
• Zero Dependencies - Core marshalling requires no external dependencies

MCP (Model Context Protocol) Support

Apache Juneau ships first-party MCP integration, built the same way as the rest of the framework: annotation-driven, POJO-based, no magic. The module family is split into revision-neutral cores plus thin adapters per protocol revision, so a 2025-06-18-only deployment never pulls in 2026-07-28-only dependencies (OAuth 2.1, JWT, reactive-streams SSE, etc.):

• juneau-bean-jsonrpc - revision-neutral JSON-RPC 2.0 envelope beans, with juneau-bean-mcp-v20250618 / juneau-bean-mcp-v20260728 adapters for each revision's wire beans.
• juneau-rest-server-mcp - revision-neutral server dispatch core, with juneau-rest-server-mcp-v20250618 / juneau-rest-server-mcp-v20260728 adapters for exposing tools, prompts, and resources (dedicated servlet or drop-in mixin, plain or Spring Boot).
• juneau-rest-client-mcp - revision-neutral client core, with juneau-rest-client-mcp-v20250618 / juneau-rest-client-mcp-v20260728 typed client facades, plus juneau-rest-client-mcp-auth for the client-side OAuth 2.1 acquisition flow.
• juneau-examples-mcp - a runnable first-party example (notes-service demo, with plain, Spring Boot, and OAuth-secured variants).

The 2026-07-28 revision is a strict superset of 2025-06-18 and is where new capability work (Multi-Round-Trip Requests/elicitation, subscriptions, cache hints, trace-context propagation) lands going forward. See MCP (Model Context Protocol) for the quickstart, setup guide, and full API reference.

Documentation & Resources

Official Resources

• Homepage - Official Apache Juneau website
• Staged Website - Preview of pending website changes
• Wiki - Community documentation and guides
• Pet Store App - Complete example application

Documentation

• Javadocs - Complete API documentation
• User Guide - Comprehensive framework documentation
• Why Choose Juneau? - Benefits and comparisons with alternatives
• Framework Comparisons - Compare Juneau with Jackson, Spring Boot, and JAX-RS
• Examples - Code examples and tutorials
  • juneau-examples-core - Core serialization examples
  • juneau-petstore - Canonical petstore showcase application (deployed under both Jetty/Microservice and Spring Boot)
• Test Reports - JUnit test execution results
• Dependencies - Project dependency analysis
• Project Reports - Complete Maven site reports

Note: The documentation is automatically updated and provides the most current project information.

Common Use Cases

Apache Juneau™ excels in the following scenarios:

• Marshalling Java beans to a variety of languages using zero dependencies - Serialize POJOs to JSON, XML, HTML, URL-Encoding, UON, OpenAPI, PlainText, CSV, SOAP, MessagePack, and RDF formats with minimal setup
• Creation of self-documenting Bean-based REST APIs for SpringBoot and Jetty applications - Build REST services with automatic Swagger documentation, content negotiation, and POJO-based request/response handling
• Creation of Java interface proxies on top of existing REST APIs - Generate type-safe client proxies that make REST calls feel like local method invocations
• Powerful INI-based configuration files - Manage application configuration with support for POJOs, arrays, collections, binary data, and real-time file watching
• Serverless unit testing of REST APIs - Test REST services without servlet containers using MockRestClient for fast, comprehensive testing
• Microservice development - Build lightweight microservices with embedded Jetty or Spring Boot integration
• Data transformation and mapping - Convert between different data formats and handle complex object hierarchies with swap mechanisms
• Bean-Centric Testing and fluent-style assertions - Write readable test assertions with comprehensive validation capabilities using juneau-test
• Content negotiation and HTTP/2 support - Handle multiple content types automatically with modern HTTP features

Getting Started in 5 Minutes

1. Add Dependency

<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-shaded-all</artifactId>
    <version>10.0.0-SNAPSHOT</version>
</dependency>

10.0.0 is currently under development (tracking -SNAPSHOT builds) and has not yet been released. See the Downloads page for the latest released version.

2. Serialize a POJO to JSON

import org.apache.juneau.json.*;

public class QuickStart {
    public static void main(String[] args) {
        // Create a simple POJO
        Person person = new Person("John", 30);
        
        // Serialize to JSON
        String json = Json.of(person);
        System.out.println(json);
        // Output: {"name":"John","age":30}
    }
    
    public static class Person {
        public String name;
        public int age;
        
        public Person(String name, int age) {
            this.name = name;
            this.age = age;
        }
    }
}

3. Parse JSON back to POJO

// Parse JSON back to POJO
Person parsed = Json.to(json, Person.class);
System.out.println(parsed.name); // Output: John

4. Create a REST API

import org.apache.juneau.rest.*;
import org.apache.juneau.rest.servlet.*;

@Rest(
    title="Hello World API",
    description="Simple REST API example"
)
public class HelloWorldResource extends BasicRestServlet {
    
    @RestGet("/hello/{name}")
    public String sayHello(@Path String name) {
        return "Hello " + name + "!";
    }
    
    @RestGet("/person")
    public Person getPerson() {
        return new Person("Jane", 25);
    }
}

5. Test Your API

import org.apache.juneau.rest.mock.*;

public class ApiTest {
    @Test
    public void testHello() throws Exception {
        String response = MockRestClient
            .create(HelloWorldResource.class)
            .json5()
            .build()
            .get("/hello/World")
            .run()
            .assertStatus().is(200)
            .getContent().asString();
        
        assertEquals("Hello World!", response);
    }
}

That's it! You now have:

• JSON serialization/parsing
• A working REST API with automatic content negotiation
• Built-in testing support
• Zero external dependencies

Next Steps

• Multi-format support: Try XML, HTML, or other formats
• Configuration files: Use juneau-config for INI-style configs
• Spring Boot integration: Add juneau-rest-server-springboot
• Examples: Check out our comprehensive examples

More Examples

XML Serialization

import org.apache.juneau.xml.*;

// Serialize to XML
String xml = Xml.of(person);
System.out.println(xml);
// Output: <object><name>John</name><age>30</age></object>

// Parse XML back to POJO
Person parsed = Xml.to(xml, Person.class);

HTML Serialization

import org.apache.juneau.html.*;

// Serialize to HTML table
String html = Html.of(person);
System.out.println(html);
// Output: <table><tr><th>name</th><td>John</td></tr><tr><th>age</th><td>30</td></tr></table>

Configuration Files

import org.apache.juneau.config.*;

// Create configuration
Config config = Config.create()
    .set("database.host", "localhost")
    .set("database.port", 5432)
    .set("features.enabled", true)
    .build();

// Read configuration
String host = config.get("database.host");
int port = config.get("database.port", Integer.class);
boolean enabled = config.get("features.enabled", Boolean.class);

REST Client Proxy

import org.apache.juneau.rest.client.*;
import org.apache.juneau.http.*;

// Define REST interface
@Remote("http://api.example.com")
public interface UserService {
    @Get("/users/{id}")
    User getUser(@Path String id);
    
    @Post("/users")
    User createUser(@Body User user);
}

// Use as regular Java interface
UserService service = RestClient.create().build().getRemote(UserService.class);
User user = service.getUser("123");

Testing REST APIs

import org.apache.juneau.rest.mock.*;

// Test without starting a server
@Test
public void testUserAPI() throws Exception {
    String response = MockRestClient
        .create(UserResource.class)
        .json5()
        .build()
        .get("/users/123")
        .run()
        .assertStatus().is(200)
        .getContent().asString();
    
    assertThat(response).contains("John");
}

Microservice with Jetty

import org.apache.juneau.microservice.*;

// Create microservice
Microservice microservice = Microservice.create()
    .servlet(UserResource.class)
    .port(8080)
    .build();

// Start server
microservice.start();

Description

Apache Juneau™ is a single cohesive Java ecosystem consisting of the following parts, grouped by aggregator module. For the complete, always-current per-artifact list, see the Juneau Ecosystem Overview.

• juneau-core - Core marshalling and support APIs, with no external dependencies unless noted:
  • juneau-commons - Shared low-level utilities used across the ecosystem, including the Simple Variable Language (SVL) for dynamic string processing.
  • juneau-marshall - A universal toolkit for marshalling POJOs to a variety of content types using a common framework with no external library dependencies.
  • juneau-marshall-rdf - Additional support for various RDF languages.
  • juneau-config - A sophisticated configuration file API.
  • juneau-test - Unified test-support API combining fluent-style assertions, Bean-Centric Testing, and JUnit 5 extensions (replaces the former juneau-assertions/juneau-bct/juneau-junit5 artifacts).
• juneau-bean - Predefined serializable beans: juneau-bean-atom, juneau-bean-common, juneau-bean-hal, juneau-bean-html5, juneau-bean-jsonapi, juneau-bean-jsonpatch, juneau-bean-jsonrpc, juneau-bean-jsonschema, juneau-bean-openapi-v3, juneau-bean-rfc7807, juneau-bean-swagger-v2 - such as HTML5, Swagger/OpenAPI, ATOM, HAL, JSON:API, JSON Patch, and RFC 7807 Problem Details. (See MCP Support above for the juneau-bean-mcp-* adapters.)
• juneau-rest - REST server and client APIs:
  • juneau-rest-common / juneau-rest-common-classic - REST APIs common to client and server side (next-gen vs. classic client stack).
  • juneau-rest-server - A universal REST server API for creating Swagger-based self-documenting REST interfaces using POJOs, simply deployed as one or more top-level servlets in any Servlet 3.1.0+ container. Includes Spring Boot and JAX-RS integration support.
  • juneau-rest-server-rdf - RDF support for the REST server.
  • juneau-rest-server-springboot - Spring Boot integration for juneau-rest-server.
  • juneau-rest-server-auth-jwt, -saml, -oauth, -oidc-rp and juneau-rest-auth-oauth-flow - Authentication/authorization add-ons (JWT, SAML, OAuth, OpenID Connect RP).
  • juneau-rest-server-metrics-micrometer, -tracing-otel, -management-logging - Observability add-ons (Micrometer metrics, OpenTelemetry tracing, request/response logging).
  • juneau-rest-server-datatables - Server-side processing adapter (plus browser-side helpers) for DataTables.
  • juneau-rest-server-reactive, -reactive-reactor - Reactive-streams (SSE) response support.
  • juneau-rest-server-view-jsp, -thymeleaf, -mustache, -freemarker - View-engine add-ons.
  • juneau-rest-client / juneau-rest-client-classic - A universal REST client API for interacting with Juneau or 3rd-party REST interfaces using POJOs and proxy interfaces (next-gen vs. classic client stack), with juneau-rest-client-apache-httpclient-45/-50, juneau-rest-client-jetty, and juneau-rest-client-okhttp transport backends.
  • juneau-rest-mock - REST testing API.
  • MCP client/server modules - see MCP Support above.
• juneau-microservice - juneau-microservice, juneau-microservice-jetty, juneau-microservice-tomcat, juneau-microservice-test, juneau-microservice-examples - Lightweight standalone microservice APIs (Jetty and Tomcat), plus a JUnit 5 test harness.
• juneau-sc - juneau-sc-server - Git-backed source-control configuration server integration (GitControl, etc.).
• juneau-secret-keychain - Opt-in SecretStore implementation backed by the macOS security keychain CLI (implements the SecretStore SPI in juneau-commons).
• juneau-examples - juneau-examples-core - Core code examples; juneau-examples-mcp - Runnable MCP example (notes-service demo).
• juneau-petstore - juneau-petstore-core - Shared petstore domain + REST resources; juneau-petstore-jetty - Jetty/Microservice deployment; juneau-petstore-springboot - Spring Boot deployment.
• juneau-shaded - Shaded (uber) JARs combining multiple Juneau modules for simplified dependency management, especially useful for Bazel builds: juneau-shaded-core, juneau-shaded-rest-client, juneau-shaded-rest-server, juneau-shaded-rest-server-springboot, and juneau-shaded-all.
• juneau-bundles - Curated dependency bundles pulling a coherent module set per deployment shape: juneau-microservice-jetty-bundle, juneau-microservice-tomcat-bundle, juneau-springboot-bundle, juneau-observability-otlp-bundle.
• juneau-bom - Published Maven Bill-of-Materials for version-aligning Juneau dependencies.
• juneau-distrib - Release distribution assembly.

Questions via email to dev@juneau.apache.org are always welcome.

Juneau is packed with features that may not be obvious at first. Users are encouraged to ask for code reviews by providing links to specific source files such as through GitHub. Not only can we help you with feedback, but it helps us understand usage patterns to further improve the product.

Features

• Fast memory-efficient serialization.
• Fast, safe, memory-efficient parsing. Parsers are not susceptible to deserialization attacks.
• KISS is our mantra! No auto-wiring. No code generation. No dependency injection. Just add it to your classpath and use it. Extremely simple unit testing!
• Enjoyable to use
• Tiny - ~1MB
• Exhaustively tested
• Lots of up-to-date documentation and examples
• Minimal library dependencies:
  • juneau-commons, juneau-marshall, juneau-bean-atom, juneau-bean-common, juneau-bean-html5, juneau-bean-jsonschema, juneau-bean-openapi-v3, juneau-config - No external dependencies. Entirely self-contained.
  • juneau-marshall-rdf - Optional RDF support. Requires Apache Jena 5.6.0+.
  • juneau-test - Requires opentest4j (JUnit Jupiter is a provided-scope dependency, supplied by your test runtime).
  • juneau-rest-server - Any Servlet 3.1.0+ container.
  • juneau-rest-client - Apache HttpClient 4.5+.
• Built on top of Servlet and Apache HttpClient APIs that allow you to use the newest HTTP/2 features such as request/response multiplexing and server push.

Repository Structure

This repository uses multiple branches to separate different concerns:

• master - Contains the main source code for Apache Juneau
• docs - Contains the Docusaurus-based documentation site
• asf-staging - Contains the staging/preview version of the website
• asf-site - Contains the production version of the website

When working with the repository, ensure you're on the correct branch for your task:

• For code changes, work in the master branch
• For documentation updates, work in the docs branch
• The asf-staging and asf-site branches are automatically updated during the release process

Building

Building requires:

• Apache Maven
• Java 17 is required to build and run.