This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new b7eceb2e3f Marshall module improvements
b7eceb2e3f is described below
commit b7eceb2e3f95b7e48f96526300ff6b5aa4d30eae
Author: James Bognar <[email protected]>
AuthorDate: Sat Dec 6 10:04:53 2025 -0500
Marshall module improvements
---
.../org/apache/juneau/annotation/NameProperty.java | 56 +++++++++++++++++++---
.../apache/juneau/annotation/ParentProperty.java | 56 ++++++++++++++++++----
.../docs/topics/02.04.07.NamePropertyAnnotation.md | 55 +++++++++++++++++----
.../topics/02.04.08.ParentPropertyAnnotation.md | 53 +++++++++++++++++---
4 files changed, 189 insertions(+), 31 deletions(-)
diff --git
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/NameProperty.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/NameProperty.java
index 811be469d3..1120ac7bcd 100644
---
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/NameProperty.java
+++
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/NameProperty.java
@@ -22,18 +22,62 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
- * Identifies a setter as a method for setting the name of a POJO as it's
known by its parent object.
+ * Identifies a setter method or field for setting the name of a POJO as it's
known by its parent object.
+ *
+ * <p>
+ * This annotation is used by parsers to automatically set the name/key of an
object when parsing structured data
+ * (e.g., JSON maps, XML elements). A common use case is when parsing a map
where the map key should be stored
+ * as a property on the bean.
+ *
+ * <h5 class='section'>Requirements:</h5>
+ * <ul class='spaced-list'>
+ * <li>Must be an <strong>instance</strong> method or field (not static)
+ * <li>For methods: Must accept exactly one parameter of type <c>String</c>
+ * <li>For fields: Must be of type <c>String</c>
+ * <li>The method or field does not need to be public (will be made
accessible automatically)
+ * </ul>
*
* <p>
* Can be used in the following locations:
* <ul>
- * <li>Bean getter/setter/field.
- * <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated
methods when an {@link #on()} value is specified.
+ * <li>Bean setter methods or fields
+ * <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated
methods when an {@link #on()} value is specified
* </ul>
*
- * <h5 class='section'>Notes:</h5><ul>
- * <li class='note'>
- * The annotated field or method does not need to be public.
+ * <h5 class='section'>Example:</h5>
+ * <p class='bjava'>
+ * <jc>// JSON being parsed:</jc>
+ * <jc>// {</jc>
+ * <jc>// "id1": {name: "John Smith", sex: "M"},</jc>
+ * <jc>// "id2": {name: "Jane Doe", sex: "F"}</jc>
+ * <jc>// }</jc>
+ *
+ * <jk>public class</jk> Person {
+ * <ja>@NameProperty</ja>
+ * <jk>public</jk> String id; <jc>// Gets set to "id1" or "id2"
from map key</jc>
+ *
+ * <jk>public</jk> String name;
+ * <jk>public</jk> <jk>char</jk> sex;
+ * }
+ *
+ * <jc>// Or using a setter method:</jc>
+ * <jk>public class</jk> Person {
+ * <jk>private</jk> String id;
+ *
+ * <ja>@NameProperty</ja>
+ * <jk>protected void</jk> setName(String <jv>name</jv>) {
+ * <jk>this</jk>.id = <jv>name</jv>;
+ * }
+ *
+ * <jk>public</jk> String name;
+ * <jk>public</jk> <jk>char</jk> sex;
+ * }
+ * </p>
+ *
+ * <h5 class='section'>When It's Called:</h5>
+ * <ul class='spaced-list'>
+ * <li>During parsing when an object is created as a value in a
map/collection
+ * <li>The parser automatically calls the setter or sets the field with
the key/name from the parent structure
* </ul>
*
* <h5 class='section'>See Also:</h5><ul>
diff --git
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/ParentProperty.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/ParentProperty.java
index de5b1243e9..c061faf871 100644
---
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/ParentProperty.java
+++
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/ParentProperty.java
@@ -22,21 +22,61 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
- * Identifies a setter as a method for adding a parent reference to a child
object.
+ * Identifies a setter method or field for adding a parent reference to a
child object.
+ *
+ * <p>
+ * 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.
+ *
+ * <h5 class='section'>Requirements:</h5>
+ * <ul class='spaced-list'>
+ * <li>Must be an <strong>instance</strong> method or field (not static)
+ * <li>For methods: Must accept exactly one parameter (the parent object
type)
+ * <li>For fields: Can be any type (typically the parent object type)
+ * <li>The method or field does not need to be public (will be made
accessible automatically)
+ * </ul>
*
* <p>
* Can be used in the following locations:
* <ul>
- * <li>Bean getter/setter/field.
- * <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated
methods when an {@link #on()} value is specified.
+ * <li>Bean setter methods or fields
+ * <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated
methods when an {@link #on()} value is specified
* </ul>
*
- * <p>
- * Used by the parsers to add references to parent objects in child objects.
+ * <h5 class='section'>Example:</h5>
+ * <p class='bjava'>
+ * <jk>public class</jk> AddressBook {
+ * <jk>public</jk> List<Person> people;
+ * }
+ *
+ * <jk>public class</jk> Person {
+ * <ja>@ParentProperty</ja>
+ * <jk>public</jk> AddressBook addressBook; <jc>// Automatically
set to containing AddressBook</jc>
+ *
+ * <jk>public</jk> String name;
+ * <jk>public</jk> <jk>char</jk> sex;
+ * }
+ *
+ * <jc>// Or using a setter method:</jc>
+ * <jk>public class</jk> Person {
+ * <jk>private</jk> AddressBook parent;
+ *
+ * <ja>@ParentProperty</ja>
+ * <jk>protected void</jk> setParent(AddressBook <jv>parent</jv>) {
+ * <jk>this</jk>.parent = <jv>parent</jv>;
+ * }
+ *
+ * <jk>public</jk> String name;
+ * <jk>public</jk> <jk>char</jk> sex;
+ * }
+ * </p>
*
- * <h5 class='section'>Notes:</h5><ul>
- * <li class='note'>
- * The annotated field or method does not need to be public.
+ * <h5 class='section'>When It's Called:</h5>
+ * <ul class='spaced-list'>
+ * <li>During parsing when a child object is created within a parent object
+ * <li>The parser automatically calls the setter or sets the field with a
reference to the parent object
+ * <li>This allows child objects to navigate back to their parent if needed
* </ul>
*
* <h5 class='section'>See Also:</h5><ul>
diff --git a/juneau-docs/docs/topics/02.04.07.NamePropertyAnnotation.md
b/juneau-docs/docs/topics/02.04.07.NamePropertyAnnotation.md
index 7dfb18da6d..5e4f429acd 100644
--- a/juneau-docs/docs/topics/02.04.07.NamePropertyAnnotation.md
+++ b/juneau-docs/docs/topics/02.04.07.NamePropertyAnnotation.md
@@ -3,28 +3,63 @@ title: "@NameProperty Annotation"
slug: NamePropertyAnnotation
---
-The <a href="/site/apidocs/org/apache/juneau/annotation/NameProperty.html"
target="_blank">@NameProperty</a> annotation is used to identify a setter
-as a method for setting the name of a POJO as it's known by its parent object.
+The <a href="/site/apidocs/org/apache/juneau/annotation/NameProperty.html"
target="_blank">@NameProperty</a> annotation is used to identify a setter
method or field for setting the name of a POJO as it's known by its parent
object.
-A commonly-used case is when you're parsing a JSON map containing beans where
one of the bean properties is the key used
-in the map.
+This annotation is used by parsers to automatically set the name/key of an
object when parsing structured data (e.g., JSON maps, XML elements). A common
use case is when parsing a map where the map key should be stored as a property
on the bean.
+
+## Requirements
+
+- Must be an **instance** method or field (not static)
+- For methods: Must accept exactly one parameter of type `String`
+- For fields: Must be of type `String`
+- The method or field does not need to be public (will be made accessible
automatically)
+
+## Usage
+
+Can be applied to:
+- Bean setter methods or fields
+- `@Rest`-annotated classes and `@RestOp`-annotated methods when using the
`on()` parameter
+
+## Example
+
+### Using a Field
```js
-// JSON
+// JSON being parsed:
{
- id1: {name: 'John Smith', sex: 'M'},
- id2: {name: 'Jane Doe', sex: 'F'}
+ "id1": {name: "John Smith", sex: "M"},
+ "id2": {name: "Jane Doe", sex: "F"}
}
```
```java
public class Person {
-
@NameProperty
- public String id; // Value gets assigned from object key
+ public String id; // Gets set to "id1" or "id2" from map key
public String name;
+ public char sex;
+}
+```
+### Using a Setter Method
+
+```java
+public class Person {
+ private String id;
+
+ @NameProperty
+ protected void setName(String name) {
+ this.id = name;
+ }
+
+ public String name;
public char sex;
}
-```
\ No newline at end of file
+```
+
+## When It's Called
+
+- During parsing when an object is created as a value in a map/collection
+- The parser automatically calls the setter or sets the field with the
key/name from the parent structure
+- This allows the bean to know its key/name within the parent container
diff --git a/juneau-docs/docs/topics/02.04.08.ParentPropertyAnnotation.md
b/juneau-docs/docs/topics/02.04.08.ParentPropertyAnnotation.md
index ffcde13774..7bda420e40 100644
--- a/juneau-docs/docs/topics/02.04.08.ParentPropertyAnnotation.md
+++ b/juneau-docs/docs/topics/02.04.08.ParentPropertyAnnotation.md
@@ -3,25 +3,64 @@ title: "@ParentProperty Annotation"
slug: ParentPropertyAnnotation
---
-The <a href="/site/apidocs/org/apache/juneau/annotation/ParentProperty.html"
target="_blank">@ParentProperty</a> annotation is used to identify a
-setter as a method for adding a parent reference to a child object.
+The <a href="/site/apidocs/org/apache/juneau/annotation/ParentProperty.html"
target="_blank">@ParentProperty</a> annotation is used to identify a setter
method or field for adding a parent reference to a child object.
-A commonly-used case is when you're parsing beans and a child bean has a
reference to a parent bean.
+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)
+
+## Usage
+
+Can be applied to:
+- Bean setter methods or fields
+- `@Rest`-annotated classes and `@RestOp`-annotated methods when using the
`on()` parameter
+
+## Example
+
+### Using a Field
```java
public class AddressBook {
- public List people;
+ public List<Person> people;
}
public class Person {
-
@ParentProperty
- public AddressBook addressBook; // A reference to the containing address
book.
+ public AddressBook addressBook; // Automatically set to containing
AddressBook
public String name;
+ public char sex;
+}
+```
+
+### Using a Setter Method
+```java
+public class AddressBook {
+ public List<Person> people;
+}
+
+public class Person {
+ private AddressBook parent;
+
+ @ParentProperty
+ protected void setParent(AddressBook parent) {
+ this.parent = parent;
+ }
+
+ public String name;
public char sex;
}
```
-Parsers will automatically set this field for you in the child beans.
+## 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
+- Useful for bidirectional relationships where child objects need access to
their parent context
