Package org.apache.juneau.marshall

Annotation Interface ParentProperty

@Target({METHOD,FIELD}) @Retention(RUNTIME) @Inherited public @interface ParentProperty
Identifies a setter method or field for adding a parent reference to a child object.

This annotation is used by parsers to automatically establish parent-child relationships when parsing nested objects. When a child object is created within a parent object (e.g., in a list or as a property), the parser automatically sets the parent reference on the child.

Requirements:
  • Must be an instance method or field (not static)
  • For methods: Must accept exactly one parameter (the parent object type)
  • For fields: Can be any type (typically the parent object type)
  • The method or field does not need to be public (will be made accessible automatically)

Can be used in the following locations:

  • Bean setter methods or fields
  • @Rest-annotated classes and @RestOp-annotated methods when used with @ParentPropertyApply
Example:

public class AddressBook { public List<Person> people; } public class Person { @ParentProperty public AddressBook addressBook; // Automatically set to the enclosing AddressBook (the intervening List is skipped). public String name; public char sex; } // Or using a setter method: public class Person { private AddressBook parent; @ParentProperty protected void setParent(AddressBook parent) { this.parent = parent; } public String name; public char sex; }

When It's Called:
  • During parsing when a child object is created within a parent object
  • The parser automatically calls the setter or sets the field with a reference to the parent object
  • This allows child objects to navigate back to their parent if needed
Parent resolution through collections and maps:
  • A collection/map element's @ParentProperty is set to the nearest enclosing bean, skipping any intervening collections, maps, or arrays. In the example above, each Person lives inside a List<Person>, yet its addressBook back-reference receives the enclosing AddressBook bean, not the List. The same holds through arbitrarily deep nesting (e.g. List<List<Person>>, Map<String,List<Person>>).
  • A bean at the document root (or directly inside a top-level collection) has no enclosing bean, so its @ParentProperty is left null.
Cyclic graphs and serialization:
  • When a @ParentProperty back-reference is also a normally-visible bean property (e.g. a public field or getter, as in the example above), it forms a parent-to-child/child-to-parent cycle. Unlike Jackson's @JsonBackReference, Juneau does not auto-omit the @ParentProperty member on the write (serialize) side — the annotation is a parse-time convenience only. This is intentional.
  • Under the default serializer configuration (detectRecursions=false, ignoreRecursions=false), serializing such a cyclic graph produces finite but semantically-incomplete output: the traversal is silently truncated at maxDepth (default 100). No exception is thrown — maxDepth is a size guard, not a cycle detector.
  • To fail-fast on cycles with a clear error, enable detectRecursions — a MarshallingRecursionException (surfaced as a serialize exception) is thrown.
  • To omit the back-reference and round-trip cleanly, enable ignoreRecursions — the repeated node is emitted as null, and parsing re-injects the parent via this annotation.

Putting it together, the AddressBook/List<Person> graph above round-trips cleanly when the back-reference is omitted on serialize and re-injected on parse:

Serializer serializer = JsonSerializer.create().ignoreRecursions().build(); String json = serializer.serialize(addressBook); AddressBook parsed = JsonParser.DEFAULT.parse(json, AddressBook.class); Person person = parsed.people.get(0); assertTrue(person.addressBook == parsed); // Parent re-injected through the List.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    description
    Optional description for the exposed API.

  • Element Details

    • description

      String[] description
      Optional description for the exposed API.
      Returns:
      The annotation value.
      Since:
      9.2.0
      Default:
      {}