You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2026/08/12 18:46:04 UTC
(juneau) branch docs updated: TODO-351 B-marshall-2/3: rename marshall.swap framework SPI package to swap.spi; rename swap.spi Builder to PojoBuilder (10.0 breaking-change window)
This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new 8f6d0f7999 TODO-351 B-marshall-2/3: rename marshall.swap framework SPI package to swap.spi; rename swap.spi Builder to PojoBuilder (10.0 breaking-change window)
8f6d0f7999 is described below
commit 8f6d0f79993d83a636d842b81ed00cde67995ecf
Author: James Bognar <ja...@apache.org>
AuthorDate: Wed Aug 12 14:45:55 2026 -0400
TODO-351 B-marshall-2/3: rename marshall.swap framework SPI package to swap.spi; rename swap.spi Builder to PojoBuilder (10.0 breaking-change window)
---
pages/topics/03.03.09.PojoBuilders.md | 4 ++--
pages/topics/03.13.00.Swaps.md | 2 +-
pages/topics/03.13.03.PerMediaTypeSwaps.md | 2 +-
pages/topics/03.13.07.SurrogateClasses.md | 2 +-
pages/topics/03.21.PojoCategories.md | 2 +-
pages/topics/03.31.02.OpenApiSerializers.md | 20 ++++++++++----------
static/ai/juneau-knowledge.jsonl | 6 +++---
7 files changed, 19 insertions(+), 19 deletions(-)
diff --git a/pages/topics/03.03.09.PojoBuilders.md b/pages/topics/03.03.09.PojoBuilders.md
index 20a20b9358..cee28b43e9 100644
--- a/pages/topics/03.03.09.PojoBuilders.md
+++ b/pages/topics/03.03.09.PojoBuilders.md
@@ -78,7 +78,7 @@ The first can be accomplished through **any** of the following:
```java
public static Builder create() {...}
```
-- A public constructor on the POJO class that takes in a single parameter that implements the <a href="/site/apidocs/org/apache/juneau/marshall/swap/Builder.html" target="_blank">Builder</a> interface.
+- A public constructor on the POJO class that takes in a single parameter that implements the <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/PojoBuilder.html" target="_blank">PojoBuilder</a> interface.
The builder class must have a public no-arg constructor.
```java
public MyBean(Builder builder) {...}
@@ -104,7 +104,7 @@ The second can be accomplished through **any** of the following:
<tree>
<node-0><java-annotation><a href="/site/apidocs/org/apache/juneau/commons/Builder.html" target="_blank">org.apache.juneau.commons.Builder</a></java-annotation></node-0>
-<node-0><java-abstract-class><a href="/site/apidocs/org/apache/juneau/marshall/swap/Builder.html" target="_blank">org.apache.juneau.marshall.swap.Builder</a></java-abstract-class></node-0>
+<node-0><java-abstract-class><a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/PojoBuilder.html" target="_blank">org.apache.juneau.marshall.swap.spi.PojoBuilder</a></java-abstract-class></node-0>
</tree>
:::
\ No newline at end of file
diff --git a/pages/topics/03.13.00.Swaps.md b/pages/topics/03.13.00.Swaps.md
index ab483f5787..5475b7336e 100644
--- a/pages/topics/03.13.00.Swaps.md
+++ b/pages/topics/03.13.00.Swaps.md
@@ -4,7 +4,7 @@ title: "Swap"
slug: Swaps
---
-<a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">Swaps</a> are a critical component of Juneau.
+<a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">Swaps</a> are a critical component of Juneau.
They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.
Swaps are, simply put, 'object swappers' that swap in serializable objects for non-serializable ones during serialization, and vis-versa during parsing.
diff --git a/pages/topics/03.13.03.PerMediaTypeSwaps.md b/pages/topics/03.13.03.PerMediaTypeSwaps.md
index ca26b34baa..06e7876828 100644
--- a/pages/topics/03.13.03.PerMediaTypeSwaps.md
+++ b/pages/topics/03.13.03.PerMediaTypeSwaps.md
@@ -5,7 +5,7 @@ slug: PerMediaTypeSwaps
Swaps can also be defined per-media-type.
-The <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html#forMediaTypes()" target="_blank">ObjectSwap.forMediaTypes()</a> method can be
+The <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html#forMediaTypes()" target="_blank">ObjectSwap.forMediaTypes()</a> method can be
overridden to provide a set of media types that the swap is invoked on.
It's also possible to define multiple swaps against the same object as long as they're differentiated by media type.
diff --git a/pages/topics/03.13.07.SurrogateClasses.md b/pages/topics/03.13.07.SurrogateClasses.md
index d572c12bb1..56adfd98b1 100644
--- a/pages/topics/03.13.07.SurrogateClasses.md
+++ b/pages/topics/03.13.07.SurrogateClasses.md
@@ -62,5 +62,5 @@ WriterSerializer serializer = JsonSerializer
When the serializer encounters the non-serializable class, it will serialize an instance of the surrogate instead.
:::info See Also
-<java-interface><a href="/site/apidocs/org/apache/juneau/marshall/swap/Surrogate.html" target="_blank">Surrogate</a></java-interface>
+<java-interface><a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/Surrogate.html" target="_blank">Surrogate</a></java-interface>
:::
\ No newline at end of file
diff --git a/pages/topics/03.21.PojoCategories.md b/pages/topics/03.21.PojoCategories.md
index 8158ab1f48..236becc9bb 100644
--- a/pages/topics/03.21.PojoCategories.md
+++ b/pages/topics/03.21.PojoCategories.md
@@ -193,7 +193,7 @@ The following chart shows POJOs categorized into groups and whether they can be
<td colSpan={4}>
<b>Swapped objects</b><br />
<span style={{fontWeight: 'normal', fontSize: '0.9em'}}>
- Objects that are not directly serializable but have <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwaps</a> associated with them.
+ Objects that are not directly serializable but have <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwaps</a> associated with them.
The purpose of a POJO swap is to convert an object to another object that is easier to serialize and parse.
<br /><i>Note: As of 9.5.0, date/time types (`Calendar`, `Date`, `Temporal` subtypes, `XMLGregorianCalendar`, `Duration`, `Period`)
are handled natively and no longer require swaps. Swap classes remain available as override mechanisms.</i>
diff --git a/pages/topics/03.31.02.OpenApiSerializers.md b/pages/topics/03.31.02.OpenApiSerializers.md
index e3ce4a50fb..229227d377 100644
--- a/pages/topics/03.31.02.OpenApiSerializers.md
+++ b/pages/topics/03.31.02.OpenApiSerializers.md
@@ -153,7 +153,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• Any POJO transformable to a `byte[]` via:<br/>
- `public byte[] toBytes() {...}`<br/>
- `public byte[] toFoo() {...}` (any method starting with "to")<br/>
- - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+ - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -164,7 +164,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• Any POJO transformable to a <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Calendar.html" target="_blank">Calendar</a> via:<br/>
- `public Calendar toCalendar() {...}`<br/>
- `public Calendar toFoo() {...}` (any method starting with "to")<br/>
- - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+ - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -177,7 +177,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/String.html" target="_blank">String</a> (default)<br/>
• Any POJO transformable to a <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/String.html" target="_blank">String</a> via:<br/>
- `public String toString() {...}`<br/>
- - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+ - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -190,7 +190,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• Any POJO transformable to a <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Boolean.html" target="_blank">Boolean</a> via:<br/>
- `public Boolean toBoolean() {...}`<br/>
- `public Boolean toFoo() {...}` (any method starting with "to")<br/>
- - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+ - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -203,7 +203,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• Any POJO transformable to an <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Integer.html" target="_blank">Integer</a> via:<br/>
- `public Integer toInteger() {...}`<br/>
- `public Integer toFoo() {...}` (any method starting with "to")<br/>
- - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+ - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -215,7 +215,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• Any POJO transformable to a <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Long.html" target="_blank">Long</a> via:<br/>
- `public Long toLong() {...}`<br/>
- `public Long toFoo() {...}` (any method starting with "to")<br/>
- - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+ - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -228,7 +228,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• Any POJO transformable to a <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Float.html" target="_blank">Float</a> via:<br/>
- `public Float toFloat() {...}`<br/>
- `public Float toFoo() {...}` (any method starting with "to")<br/>
- - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+ - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -240,7 +240,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• Any POJO transformable to a <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Double.html" target="_blank">Double</a> via:<br/>
- `public Double toDouble() {...}`<br/>
- `public Double toFoo() {...}` (any method starting with "to")<br/>
- - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+ - Any POJO transformable via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -250,7 +250,7 @@ Here are the rules of POJO types allowed for various type/format combinations:
• Arrays or `Collections` of any defaults on this list<br/>
• Any POJO transformable to arrays of the default types (e.g. `Integer[]`, `Boolean[][]`, etc...)<br/>
For example: `public Boolean[][] toFoo() {...}` (any method starting with "to")<br/>
-• Any POJO transformable to arrays of the default types via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+• Any POJO transformable to arrays of the default types via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
@@ -263,7 +263,7 @@ For example: `public Boolean[][] toFoo() {...}` (any method starting with "to")<
<td>
• `Map<String,Object>` (default)<br/>
• Beans with properties of anything on this list<br/>
-• Any POJO transformable to a map via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html" target="_blank">ObjectSwap</a>
+• Any POJO transformable to a map via an <a href="/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html" target="_blank">ObjectSwap</a>
</td>
</tr>
<tr>
diff --git a/static/ai/juneau-knowledge.jsonl b/static/ai/juneau-knowledge.jsonl
index 6196310ef7..689352fe75 100644
--- a/static/ai/juneau-knowledge.jsonl
+++ b/static/ai/juneau-knowledge.jsonl
@@ -151,14 +151,14 @@
{"description": "The Juneau parsers have the ability to parse into complex data types that consist of multidimensional arrays and nested\n`Maps` and `Collections` using the methods below:\n\n<tree>\n<node-0><java-class><a href=\"/site/apidocs/org/apache/juneau/marshall/parser/Parser.html\" target=\"_blank\">Parser</a></java-class></node-0>\n<node-1><java-method><a href=\"/site/apidocs/org/apache/juneau/marshall/parser/Parser.html#<init>(org.apache.juneau.marshall.parser.Parser.Builder)\" [...]
{"description": "Juneau provides **first-class, direct serializer/parser support** for a wide range of JDK datatypes \u2014 no\nextra modules, no opt-in registration, no swap setup required for the common cases. This page enumerates the\nsupported types, their default wire forms, and the per-type knobs that let you adjust the wire form across\nall formats.\n\n## Design principle: first-class > swaps\n\nJuneau handles common JDK datatypes through **direct serializer/parser code paths plus [...]
{"description": "On top of the serializers and parsers are the <a href=\"/site/apidocs/org/apache/juneau/marshall/serializer/SerializerSet.html\" target=\"_blank\">SerializerSet</a> and <a href=\"/site/apidocs/org/apache/juneau/marshall/parser/ParserSet.html\" target=\"_blank\">ParserSet</a> classes.\nThese classes allow serializers and parsers to be grouped and retrieved by W3C-compliant HTTP `Accept` and\n`Content-Type` values...\n\n```java\n// Construct a new serializer group with con [...]
-{"description": "<a href=\"/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html\" target=\"_blank\">Swaps</a> are a critical component of Juneau.\nThey allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.\n\nSwaps are, simply put, 'object swappers' that swap in serializable objects for non-serializable ones during serialization, and vis-versa during parsing.\n\nSome examples of non-serializable objects are `File`, `Reader`, `Iterable`, [...]
+{"description": "<a href=\"/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html\" target=\"_blank\">Swaps</a> are a critical component of Juneau.\nThey allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.\n\nSwaps are, simply put, 'object swappers' that swap in serializable objects for non-serializable ones during serialization, and vis-versa during parsing.\n\nSome examples of non-serializable objects are `File`, `Reader`, `Iterab [...]
{"description": "By default, all serializers and parsers have built in `ObjectSwaps` defined for the following common data types:\n\n:::note\nAs of 9.5.0, `Iterator`, `Iterable`, `Stream`, and `Enumeration` types are serialized natively without swaps.\nThe `IteratorSwap` and `EnumerationSwap` classes have been removed.\nSee [Release 9.5.0](/docs/release-notes/9.5.0) for details.\n:::\n\n:::note\nAs of 9.5.0, date/time types (`Calendar`, `Date`, `Temporal` subtypes, `XMLGregorianCalendar` [...]
{"description": "Various methods can be defined on a class directly to affect how it gets serialized.\nThis can often be simpler than using `ObjectSwaps`.\n\nObjects serialized as `Strings` can be parsed back into their original objects by implementing one of the following methods on the class:\n\n- `public static T fromString(String)` method.\n \n Any of the following method names also work:\n - `valueOf(String)`\n - `parse(String)`\n - `parseString(String)`\n - `forName(String)`\ [...]
-{"description": "Swaps can also be defined per-media-type.\n\nThe <a href=\"/site/apidocs/org/apache/juneau/marshall/swap/ObjectSwap.html#forMediaTypes()\" target=\"_blank\">ObjectSwap.forMediaTypes()</a> method can be\noverridden to provide a set of media types that the swap is invoked on.\n\nIt's also possible to define multiple swaps against the same object as long as they're differentiated by media type.\n\nWhen multiple swaps are defined, the best-match media type is used.\n\nIn the [...]
+{"description": "Swaps can also be defined per-media-type.\n\nThe <a href=\"/site/apidocs/org/apache/juneau/marshall/swap/spi/ObjectSwap.html#forMediaTypes()\" target=\"_blank\">ObjectSwap.forMediaTypes()</a> method can be\noverridden to provide a set of media types that the swap is invoked on.\n\nIt's also possible to define multiple swaps against the same object as long as they're differentiated by media type.\n\nWhen multiple swaps are defined, the best-match media type is used.\n\nIn [...]
{"description": "In the previous sections, we defined two-way swaps, meaning swaps where the original objects could be reconstructing\nduring parsing.\nHowever, there are certain kinds of objects that we may want to support for serializing but that are not possible to\nreconstruct during parsing.\nFor these, we can use one-way object swaps.\n\nA one-way swap is simply an object transform that only implements the `swap()` method.\nThe `unswap()` method is simply left unimplemented.\n\n::: [...]
{"description": "<a href=\"/site/apidocs/org/apache/juneau/marshall/Swap.html\" target=\"_blank\">@Swap</a> can be used to associate a swap class using an annotation.\nThis is often cleaner than using the builder `swaps()` method since you can keep your swap class near your POJO class.\n\n```java\n@Swap(MyObjectSwap.class)\npublic class MyPojo {\n ...\n}\n\n// Sample swap for converting MyPojo classes to a simple string.\npublic class MyObjectSwap extends ObjectSwap {\n @Override / [...]
{"description": "The <a href=\"/site/apidocs/org/apache/juneau/marshall/Swap.html#template()\" target=\"_blank\">@Swap(template)</a> annotation allows you to associate\narbitrary contextual strings with swaps.\nThe primary purpose is for providing template names, such as for Apache FreeMarker, therefore the name 'template'.\nHowever, the usage of the string is open-ended.\n\nFor example, you could pair a template string like so:\n\n```java\n@Swap(impl=FreeMarkerSwap.class, template=\"MyP [...]
-{"description": "Surrogate classes are very similar in concept to `ObjectSwaps` except they're simpler to define.\n\nFor example, let's say we want to be able to serialize the following class but it's not serializable for some reason\n(for example, there are no properties exposed):\n\n```java\n// Not serializable because it's not a bean because it has no public properties.\npublic class MyNonSerializableClass {\n protected String foo;\n}\n```\n\nThis could be solved with the following [...]
+{"description": "Surrogate classes are very similar in concept to `ObjectSwaps` except they're simpler to define.\n\nFor example, let's say we want to be able to serialize the following class but it's not serializable for some reason\n(for example, there are no properties exposed):\n\n```java\n// Not serializable because it's not a bean because it has no public properties.\npublic class MyNonSerializableClass {\n protected String foo;\n}\n```\n\nThis could be solved with the following [...]
{"description": "In the section [Swaps](/docs/topics/Swaps), you were introduced to annotations that can be applied to bean classes, methods,\nfields, and constructors such as <a href=\"/site/apidocs/org/apache/juneau/commons/bean/BeanType.html\" target=\"_blank\">@BeanType</a>:\n\n```java\n// Address class with only street/city/state properties (in that order).\n// All other properties are ignored.\n@BeanType(properties=\"street,city,state\")\npublic class Address { ... }\n```\n\nAn alt [...]
{"description": "While parsing into beans, Juneau attempts to determine the class types of bean properties through reflection on the bean\nproperty getter or setter.\nOften this is insufficient if the property type is an interface or abstract class that cannot be instantiated.\nThis is where bean names and dictionaries come into play.\n\nBean names and dictionaries are used for identifying class types when they cannot be inferred through reflection.\nBean classes are given names through [...]
{"description": "In addition to the [bean type name](/docs/topics/XmlBeanTypeNameAnnotation) support, Juneau provides\nsimplified support for **bean subtypes** via the\n<a href=\"/site/apidocs/org/apache/juneau/marshall/Marshalled.html#dictionary()\" target=\"_blank\">@Marshalled(dictionary=\u2026)</a>\nattribute declared on a parent bean class.\n\nBean subtypes are similar in concept to bean type names, with two convenience differences:\n\n- You declare the list of possible subclasses t [...]