Skip to main content

HOCON

Juneau supports converting arbitrary POJOs to and from HOCON (Human-Optimized Config Object Notation) using native serializers and parsers. HOCON is a superset of JSON used extensively in the JVM ecosystem (Akka, Play Framework, sbt, Apache Spark, Kafka, Flink) for configuration files. It extends JSON with path expressions, = as key-value separator, unquoted strings, object merging, substitutions (${var}), triple-quoted multi-line strings, and optional root braces.

The HoconSerializer converts POJOs to HOCON format, and the HoconParser creates POJOs from HOCON.

HOCON support is included in juneau-marshall.

Maven
<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-marshall</artifactId>
    <version>${juneau.version}</version>
</dependency>

Quick Start​

// A simple bean
public class Person {
    public String name;
    public int age;
    public Person() {}
    public Person(String name, int age) { this.name = name; this.age = age; }
}

// Serialize to HOCON
Person alice = new Person("Alice", 30);
String hocon = Hocon.of(alice);

Produces:

name = Alice
age = 30

Parsing​

// Parse HOCON into a bean
Person parsed = Hocon.to(hocon, Person.class);

// Parse into a map
JsonMap map = Hocon.to(hocon, JsonMap.class);

// Parse with path expressions
String pathExpr = "database.host = localhost\ndatabase.port = 5432";
JsonMap config = Hocon.to(pathExpr, JsonMap.class);

Serialization Modes​

// Readable mode (default) - = separator, unquoted strings, root braces omitted
String hocon = Hocon.DEFAULT.of(bean);

// With root braces
String braced = HoconSerializer.DEFAULT_BRACES.write(bean);

// Compact mode - single line
String compact = HoconSerializer.DEFAULT_COMPACT.write(bean);

HOCON Syntax Highlights​

  • Key-value separators: = (convention), : (JSON-style), or space-brace for objects
  • Path expressions: a.b.c = value expands to nested objects
  • Unquoted strings: Keys and simple values need not be quoted
  • Object merging: Duplicate keys merge instead of overwrite
  • += array append: list += item appends to an array or creates [item] if the key does not exist
  • Substitutions: ${var} and ${?var} (optional) resolved after parse
  • Self-referential substitution: path = ${path}"/bin" appends to the previous value (e.g. /usr → /usr/bin)
  • Value concatenation: Adjacent values concatenate: path = /usr "/local" → "/usr/local"
  • Array concatenation: [1, 2] [3, 4] → [1, 2, 3, 4]
  • Object concatenation: {a: 1} {b: 2} → {a: 1, b: 2}
  • Triple-quoted strings: """...""" for multi-line
  • Comments: # and // single-line
  • Optional root braces: Top-level {} can be omitted

Bean-to-HOCON Mapping​

  • Maps and beans → HOCON objects
  • Collections and arrays → HOCON arrays
  • Strings → Unquoted (when safe), quoted, or triple-quoted
  • Numbers → HOCON numbers
  • Booleans → true / false
  • Null → null
  • ObjectSwaps → Applied for non-primitive types (dates, enums, etc.)

Media Types​

  • Produces: application/hocon
  • Accepts: application/hocon

REST Integration​

// HOCON support is included via BasicUniversalConfig (there is no dedicated HOCON-only config interface).
@Rest
public class MyResource extends RestServlet implements BasicUniversalConfig { ... }

Round-Trip Notes​

  • Path expressions are parsed; serialization always uses nested-brace form
  • Substitutions (${var}) are resolved during parse; the serializer writes concrete values
  • Strings equal to true, false, null, or parseable as numbers are quoted on output to prevent ambiguity

Annotations​

@HoconConfig sets serializer/parser properties on a REST class or method (see Context Annotations). All attributes are strings ("true"/"false"); unset means "inherit".

AttributeDescription
useEqualsSignUse = as the key-value separator (default true).
useUnquotedStringsOmit quotes for simple string values.
useUnquotedKeysOmit quotes for simple keys.
omitRootBracesOmit the root object braces.
useNewlineSeparatorsSeparate members with newlines instead of commas.
resolveSubstitutionsResolve ${var} substitutions while parsing.
rankOrdering relative to other config annotations.
@Rest
@HoconConfig(omitRootBraces="true", useEqualsSign="true")
public class MyResource extends BasicRestServlet { ... }

@Hocon is a marker annotation (no attributes) for classes, methods and fields. @HoconApply applies an @Hocon to other classes/members via on()/onClass() (see Dynamically Applied Annotations).

See Also