📢 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-bct 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
Documentation
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-bct
- 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-bct - 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).
Questions via email to [email protected] 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-bct - 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 Juneaudocs - Contains the Docusaurus-based documentation siteasf-staging - Contains the staging/preview version of the websiteasf-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:
