| <!doctype html><html lang=en-US dir=ltr class="docs-wrapper plugin-docs plugin-id-default docs-version-1.5.0 docs-doc-page docs-doc-id-guide/java/json_support" data-has-hydrated=false><head><meta charset=UTF-8><meta name=generator content="Docusaurus v3.10.1"><title data-rh=true>JSON Support | Apache Fory™</title><meta data-rh=true name=viewport content="width=device-width, initial-scale=1.0"/><meta data-rh=true property=og:url content=https://fory.apache.org/docs/guide/java/json_support /><meta data-rh=true property=og:locale content=en_US /><meta data-rh=true property=og:locale:alternate content=zh_CN /><meta data-rh=true name=docusaurus_locale content=en-US /><meta data-rh=true name=docsearch:language content=en-US /><meta data-rh=true http-equiv=Content-Security-Policy content="frame-src 'self' https://ghbtns.com/;"/><meta data-rh=true property=og:image content=https://fory.apache.org/img/logo.png /><meta data-rh=true property=og:image:width content=1500 /><meta data-rh=true property=og:image:height content=1500 /><meta data-rh=true name=twitter:card content=summary_large_image /><meta data-rh=true name=twitter:image content=https://fory.apache.org/img/logo.png /><meta data-rh=true name=docusaurus_version content=1.5.0 /><meta data-rh=true name=docusaurus_tag content=docs-default-1.5.0 /><meta data-rh=true name=docsearch:version content=1.5.0 /><meta data-rh=true name=docsearch:docusaurus_tag content=docs-default-1.5.0 /><meta data-rh=true property=og:title content="JSON Support | Apache Fory™"/><meta data-rh=true name=description content="Fory JSON is Apache Fory's thread-safe Java JSON codec. It supports Java objects, records,"/><meta data-rh=true property=og:description content="Fory JSON is Apache Fory's thread-safe Java JSON codec. It supports Java objects, records,"/><link data-rh=true rel=icon href=/img/favicon.ico /><link data-rh=true rel=canonical href=https://fory.apache.org/docs/guide/java/json_support /><link data-rh=true rel=alternate href=https://fory.apache.org/docs/guide/java/json_support hreflang=en-US /><link data-rh=true rel=alternate href=https://fory.apache.org/zh-CN/docs/guide/java/json_support hreflang=zh-CN /><link data-rh=true rel=alternate href=https://fory.apache.org/docs/guide/java/json_support hreflang=x-default /><script data-rh=true type=application/ld+json>{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://fory.apache.org/docs/guide/java/","name":"Java","position":1},{"@type":"ListItem","item":"https://fory.apache.org/docs/guide/java/json_support","name":"JSON Support","position":2}]}</script><link rel=alternate type=application/rss+xml href=/blog/rss.xml title="Apache Fory™ RSS Feed"><link rel=alternate type=application/atom+xml href=/blog/atom.xml title="Apache Fory™ Atom Feed"><script type=text/javascript>"fury.apache.org"===window.location.host&&(window.location.href="https://fory.apache.org"),function(){for(var o=window.location.pathname,a=["guide","introduction","start"],n=0;n<a.length;n++){var t=a[n],i=RegExp("^((?:/[a-z]{2}-[A-Z]{2})?/docs(?:/(?:next|[0-9]+.[0-9]+))?)/docs/"+t+"(/.*)?$"),c=o.match(i);if(c){var r=c[1]+"/"+t+(c[2]||"");window.location.replace(r+window.location.search+window.location.hash);return}}}()</script><link rel=stylesheet href=/assets/css/styles.3a1edaa1.css /><script src=/assets/js/runtime~main.55aa8297.js defer></script><script src=/assets/js/main.800519c3.js defer></script></head><body><svg style="display: none;"><defs> |
| <symbol id=theme-svg-external-link viewBox="0 0 24 24"><path fill=currentColor d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol> |
| </defs></svg> |
| <script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||"light"),document.documentElement.setAttribute("data-theme-choice",t||"light")}(),function(){try{for(var[t,e]of new URLSearchParams(window.location.search).entries())if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id=__docusaurus><div role=region aria-label="Skip to main content"><a class=skipToContent_fXgn href=#__docusaurus_skipToContent_fallback>Skip to main content</a></div><nav aria-label=Main class="theme-layout-navbar navbar navbar--fixed-top"><div class=navbar__inner><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded=false class="navbar__toggle clean-btn" type=button><svg width=30 height=30 viewBox="0 0 30 30" aria-hidden=true><path stroke=currentColor stroke-linecap=round stroke-miterlimit=10 stroke-width=2 d="M4 7h22M4 15h22M4 23h22"/></svg></button><a class=navbar__brand href=/><div class=navbar__logo><img src=/img/fory-logo-light.png alt="Apache Fory™ Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"/><img src=/img/fory-logo-dark.png alt="Apache Fory™ Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"/></div><b class="navbar__title text--truncate"></b></a><a aria-current=page class="navbar__item navbar__link navbar__link--active" href=/docs/introduction/overview>Docs</a><a class="navbar__item navbar__link" href=/docs/specification/xlang_serialization_spec>Specification</a><a class="navbar__item navbar__link" href=/docs/community/>Community</a><a class="navbar__item navbar__link" href=/user>Users</a><a class="navbar__item navbar__link" href=/download>Download</a><a class="navbar__item navbar__link" href=/blog>Blog</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link>ASF</a><ul class=dropdown__menu><li><a href=https://www.apache.org/ target=_blank rel="noopener noreferrer" class=dropdown__link>Foundation</a><li><a href=https://www.apache.org/licenses/ target=_blank rel="noopener noreferrer" class=dropdown__link>License</a><li><a href=https://www.apache.org/events/current-event.html target=_blank rel="noopener noreferrer" class=dropdown__link>Events</a><li><a href=https://privacy.apache.org/policies/privacy-policy-public.html target=_blank rel="noopener noreferrer" class=dropdown__link>Privacy</a><li><a href=https://www.apache.org/security/ target=_blank rel="noopener noreferrer" class=dropdown__link>Security</a><li><a href=https://www.apache.org/foundation/sponsorship.html target=_blank rel="noopener noreferrer" class=dropdown__link>Sponsorship</a><li><a href=https://www.apache.org/foundation/thanks.html target=_blank rel="noopener noreferrer" class=dropdown__link>Thanks</a><li><a href=https://www.apache.org/foundation/policies/conduct.html target=_blank rel="noopener noreferrer" class=dropdown__link>Code of Conduct</a></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class=navbar__link aria-haspopup=true aria-expanded=false role=button href=/docs/guide/java/json_support>1.5.0</a><ul class=dropdown__menu><li><a class=dropdown__link href=/docs/next/guide/java/json_support>dev</a><li><a aria-current=page class="dropdown__link dropdown__link--active" href=/docs/guide/java/json_support>1.5.0</a><li><a class=dropdown__link href=/docs/1.4.0/guide/java/json_support>1.4.0</a><li><a class=dropdown__link href=/docs/1.3.0/introduction/overview>1.3.0</a><li><a class=dropdown__link href=/docs/1.2.0/introduction/overview>1.2.0</a><li><a class=dropdown__link href=/docs/1.1.0/introduction/overview>1.1.0</a><li><a class=dropdown__link href=/docs/1.0.0/introduction/overview>1.0.0</a><li><a class=dropdown__link href=/docs/0.17/introduction/overview>0.17</a><li><a class=dropdown__link href=/docs/0.16/introduction/overview>0.16</a><li><a class=dropdown__link href=/docs/0.15/introduction/overview>0.15</a><li><a class=dropdown__link href=/docs/0.14/introduction/overview>0.14</a><li><a class=dropdown__link href=/docs/0.13/introduction/overview>0.13</a><li><a class=dropdown__link href=/docs/0.12/introduction/overview>0.12</a><li><a class=dropdown__link href=/docs/0.11/introduction/overview>0.11</a><li><a class=dropdown__link href=/docs/0.10/introduction/overview>0.10</a></ul></div><a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class="navbar__item navbar__link header-github-link" aria-label="GitHub repository"></a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link><svg viewBox="0 0 24 24" width=20 height=20 aria-hidden=true class=iconLanguage_nlXk><path fill=currentColor d="M12.87 15.07l-2.54-2.51.03-.03c1.74-1.94 2.98-4.17 3.71-6.53H17V4h-7V2H8v2H1v1.99h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"/></svg>English</a><ul class=dropdown__menu><li><a href=/docs/guide/java/json_support target=_self rel="noopener noreferrer" class="dropdown__link dropdown__link--active" lang=en-US>English</a><li><a href=/zh-CN/docs/guide/java/json_support target=_self rel="noopener noreferrer" class=dropdown__link lang=zh-CN>简体中文</a></ul></div><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type=button disabled title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill=currentColor d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill=currentColor d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill=currentColor d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"/></svg></button></div><div class=navbarSearchContainer_Bca1><div class=navbar__search><span aria-label="expand searchbar" role=button class=search-icon tabindex=0></span><input id=search_input_react type=search placeholder=Loading... aria-label=Search class="navbar__search-input search-bar" disabled/></div></div></div></div><div role=presentation class=navbar-sidebar__backdrop></div></nav><div id=__docusaurus_skipToContent_fallback class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class=docsWrapper_hBAB><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type=button></button><div class=docRoot_UBD9><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class=sidebarViewport_aRkj><div class=sidebar_njMd><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=true href=/docs/introduction/overview><span title=Introduction class=categoryLinkLabel_W154>Introduction</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/introduction/overview><span title=Overview class=linkLabel_WmDU>Overview</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/introduction/benchmark><span title=Benchmark class=linkLabel_WmDU>Benchmark</span></a></ul><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=true href=/docs/start/install><span title=Start class=categoryLinkLabel_W154>Start</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/start/install><span title=Install class=linkLabel_WmDU>Install</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/start/usage><span title=Usage class=linkLabel_WmDU>Usage</span></a></ul><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=false href=/docs/compiler/><span title="Schema IDL & Compiler" class=categoryLinkLabel_W154>Schema IDL & Compiler</span></a></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role=button aria-expanded=true href=/docs/guide/java/><span title=Guide class=categoryLinkLabel_W154>Guide</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--active" tabindex=0 href=/docs/guide/java/><span title=Java class=categoryLinkLabel_W154>Java</span></a><button aria-label="Collapse sidebar category 'Java'" aria-expanded=true type=button class="clean-btn menu__caret"></button></div><ul class=menu__list><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/basic_serialization><span title="Basic Serialization" class=linkLabel_WmDU>Basic Serialization</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/xlang_serialization><span title="Xlang Serialization" class=linkLabel_WmDU>Xlang Serialization</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/native_serialization><span title="Native Serialization" class=linkLabel_WmDU>Native Serialization</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/configuration><span title=Configuration class=linkLabel_WmDU>Configuration</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/type_registration><span title="Type Registration" class=linkLabel_WmDU>Type Registration</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/schema_evolution><span title="Schema Evolution" class=linkLabel_WmDU>Schema Evolution</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/schema_metadata><span title="Schema Metadata" class=linkLabel_WmDU>Schema Metadata</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/static_generated_serializers><span title="Static Generated Serializers" class=linkLabel_WmDU>Static Generated Serializers</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/object_copy><span title="Object Copy" class=linkLabel_WmDU>Object Copy</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/compression><span title=Compression class=linkLabel_WmDU>Compression</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/custom_serializers><span title="Custom Serializers" class=linkLabel_WmDU>Custom Serializers</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/row_format><span title="Row Format" class=linkLabel_WmDU>Row Format</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/virtual_threads><span title="Virtual Threads" class=linkLabel_WmDU>Virtual Threads</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/graalvm_support><span title="GraalVM Support" class=linkLabel_WmDU>GraalVM Support</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/android_support><span title="Android Support" class=linkLabel_WmDU>Android Support</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/advanced_features><span title="Advanced Features" class=linkLabel_WmDU>Advanced Features</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/grpc_support><span title="gRPC Support" class=linkLabel_WmDU>gRPC Support</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class=menu__link tabindex=0 href=/docs/guide/java/troubleshooting><span title=Troubleshooting class=linkLabel_WmDU>Troubleshooting</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link menu__link--active" aria-current=page tabindex=0 href=/docs/guide/java/json_support><span title="JSON Support" class=linkLabel_WmDU>JSON Support</span></a></ul><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/python/><span title=Python class=categoryLinkLabel_W154>Python</span></a><button aria-label="Expand sidebar category 'Python'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/rust/><span title=Rust class=categoryLinkLabel_W154>Rust</span></a><button aria-label="Expand sidebar category 'Rust'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/cpp/><span title=C++ class=categoryLinkLabel_W154>C++</span></a><button aria-label="Expand sidebar category 'C++'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/go/><span title=Go class=categoryLinkLabel_W154>Go</span></a><button aria-label="Expand sidebar category 'Go'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/javascript/><span title=JavaScript class=categoryLinkLabel_W154>JavaScript</span></a><button aria-label="Expand sidebar category 'JavaScript'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/csharp/><span title=C# class=categoryLinkLabel_W154>C#</span></a><button aria-label="Expand sidebar category 'C#'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/swift/><span title=Swift class=categoryLinkLabel_W154>Swift</span></a><button aria-label="Expand sidebar category 'Swift'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/dart/><span title=Dart class=categoryLinkLabel_W154>Dart</span></a><button aria-label="Expand sidebar category 'Dart'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/scala/><span title=Scala class=categoryLinkLabel_W154>Scala</span></a><button aria-label="Expand sidebar category 'Scala'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/kotlin/><span title=Kotlin class=categoryLinkLabel_W154>Kotlin</span></a><button aria-label="Expand sidebar category 'Kotlin'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/guide/xlang/><span title="Cross Language" class=categoryLinkLabel_W154>Cross Language</span></a><button aria-label="Expand sidebar category 'Cross Language'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div></ul></ul></nav></div></div></aside><main class=docMainContainer_TBSr><div class="container padding-top--md padding-bottom--lg"><div class=row><div class="col docItemCol_VOVn"><div class=docItemContainer_Djhp><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label=Breadcrumbs><ul class=breadcrumbs><li class=breadcrumbs__item><a aria-label="Home page" class=breadcrumbs__link href=/><svg viewBox="0 0 24 24" class=breadcrumbHomeIcon_YNFT><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill=currentColor /></svg></a><li class=breadcrumbs__item><span class=breadcrumbs__link>Guide</span><li class=breadcrumbs__item><a class=breadcrumbs__link href=/docs/guide/java/><span>Java</span></a><li class="breadcrumbs__item breadcrumbs__item--active"><span class=breadcrumbs__link>JSON Support</span></ul></nav><span class="theme-doc-version-badge badge badge--secondary">Version: 1.5.0</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type=button class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>JSON Support</h1></header><p>Fory JSON is Apache Fory's thread-safe Java JSON codec. It supports Java objects, records, |
| immutable creator-based classes, common JDK types, generic containers, custom complete-value |
| codecs, and finite annotation-declared polymorphism through interpreted and runtime-generated |
| codecs.</p> |
| <p>Fory JSON is separate from Fory's binary native and xlang protocols. Use JSON for interoperable |
| text payloads such as HTTP APIs, browser traffic, logs, and configuration. Use the binary protocol |
| when you need reference identity, circular graphs, cross-language schema metadata, or Fory's |
| binary-only features.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=requirements-and-installation>Requirements and installation<a href=#requirements-and-installation class=hash-link aria-label="Direct link to Requirements and installation" title="Direct link to Requirements and installation" translate=no></a></h2> |
| <p>Fory JSON supports Java 8 and later on standard JDKs, GraalVM native images, and Android. Java |
| records are supported on Java 17 and later.</p> |
| <p>Fory JSON is available from Maven Central.</p> |
| <p>Maven:</p> |
| <div class="language-xml codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-xml codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token tag punctuation" style=color:#393A34><</span><span class="token tag" style=color:#00009f>dependency</span><span class="token tag punctuation" style=color:#393A34>></span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token tag punctuation" style=color:#393A34><</span><span class="token tag" style=color:#00009f>groupId</span><span class="token tag punctuation" style=color:#393A34>></span><span class="token plain">org.apache.fory</span><span class="token tag punctuation" style=color:#393A34></</span><span class="token tag" style=color:#00009f>groupId</span><span class="token tag punctuation" style=color:#393A34>></span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token tag punctuation" style=color:#393A34><</span><span class="token tag" style=color:#00009f>artifactId</span><span class="token tag punctuation" style=color:#393A34>></span><span class="token plain">fory-json</span><span class="token tag punctuation" style=color:#393A34></</span><span class="token tag" style=color:#00009f>artifactId</span><span class="token tag punctuation" style=color:#393A34>></span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token tag punctuation" style=color:#393A34><</span><span class="token tag" style=color:#00009f>version</span><span class="token tag punctuation" style=color:#393A34>></span><span class="token plain">1.5.0</span><span class="token tag punctuation" style=color:#393A34></</span><span class="token tag" style=color:#00009f>version</span><span class="token tag punctuation" style=color:#393A34>></span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token tag punctuation" style=color:#393A34></</span><span class="token tag" style=color:#00009f>dependency</span><span class="token tag punctuation" style=color:#393A34>></span><br/></div></code></pre></div></div> |
| <p>Gradle:</p> |
| <div class="language-kotlin codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-kotlin codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token function" style=color:#d73a49>implementation</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-literal singleline string" style=color:#e3116c>"org.apache.fory:fory-json:1.5.0"</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <p>Keep all Fory modules on the same version.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jdk-25-and-later>JDK 25 and later<a href=#jdk-25-and-later class=hash-link aria-label="Direct link to JDK 25 and later" title="Direct link to JDK 25 and later" translate=no></a></h3> |
| <p>Open <code>java.lang.invoke</code> to Fory core. On the classpath:</p> |
| <div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">--add-opens</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">java.base/java.lang.invoke</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">ALL-UNNAMED</span><br/></div></code></pre></div></div> |
| <p>On the module path:</p> |
| <div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">--add-opens</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">java.base/java.lang.invoke</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">org.apache.fory.core</span><br/></div></code></pre></div></div> |
| <p>Fory JSON's JPMS module name is <code>org.apache.fory.json</code>.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=quick-start>Quick start<a href=#quick-start class=hash-link aria-label="Direct link to Quick start" title="Direct link to Quick start" translate=no></a></h2> |
| <p>Create one <code>ForyJson</code> instance and reuse it. It is thread-safe and has no close lifecycle.</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>nio</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>charset</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">StandardCharsets</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">JsonExample</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>static</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token class-name">ForyJson</span><span class="token plain"> </span><span class="token constant" style=color:#36acaa>JSON</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>static</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>static</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>void</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>main</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">String</span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> args</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> input </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>7</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"Alice"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> text </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token constant" style=color:#36acaa>JSON</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toJson</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">input</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>byte</span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> utf8 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token constant" style=color:#36acaa>JSON</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toJsonBytes</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">input</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> fromText </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token constant" style=color:#36acaa>JSON</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>fromJson</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">text</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> fromUtf8 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token constant" style=color:#36acaa>JSON</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>fromJson</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">utf8</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">System</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">out</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>println</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">text</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">System</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">out</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>println</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">utf8</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token class-name">StandardCharsets</span><span class="token punctuation" style=color:#393A34>.</span><span class="token constant" style=color:#36acaa>UTF_8</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">System</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">out</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>println</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fromText</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">name </span><span class="token operator" style=color:#393A34>+</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>" / "</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>+</span><span class="token plain"> fromUtf8</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">name</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Unknown input properties are skipped unless a read-enabled Any field or any-setter receives them. |
| Null object properties are omitted by default. Default JSON member discovery order is not a |
| compatibility contract; use <code>JsonPropertyOrder</code> or <code>JsonProperty.index</code> when emitted member order |
| must be explicit.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=reading-and-writing>Reading and writing<a href=#reading-and-writing class=hash-link aria-label="Direct link to Reading and writing" title="Direct link to Reading and writing" translate=no></a></h2> |
| <p>Fory JSON supports String and UTF-8 byte input/output. There is no <code>InputStream</code> parsing API.</p> |
| <table><thead><tr><th>Operation<th>Runtime type<th>Declared <code>Class</code><th>Declared <code>TypeRef</code><tbody><tr><td>String output<td><code>toJson(value)</code><td><code>toJson(value, type)</code><td><code>toJson(value, typeRef)</code><tr><td>UTF-8 bytes<td><code>toJsonBytes(value)</code><td><code>toJsonBytes(value, type)</code><td><code>toJsonBytes(value, typeRef)</code><tr><td>UTF-8 <code>OutputStream</code><td><code>writeJsonTo(value, out)</code><td><code>writeJsonTo(value, type, out)</code><td><code>writeJsonTo(value, typeRef, out)</code><tr><td>String input<td>-<td><code>fromJson(text, type)</code><td><code>fromJson(text, typeRef)</code><tr><td>UTF-8 input<td>-<td><code>fromJson(bytes, type)</code><td><code>fromJson(bytes, typeRef)</code></table> |
| <p>Parsing consumes exactly one value and rejects trailing non-whitespace. String and byte-array |
| outputs are detached from internal buffers.</p> |
| <p><code>writeJsonTo</code> buffers the complete document, performs one <code>OutputStream.write</code>, and neither flushes |
| nor closes the stream. It is not incremental streaming. I/O failures are wrapped in |
| <code>ForyJsonException</code>.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=generic-and-declared-types>Generic and declared types<a href=#generic-and-declared-types class=hash-link aria-label="Direct link to Generic and declared types" title="Direct link to Generic and declared types" translate=no></a></h3> |
| <p>Use <code>TypeRef</code> for generic roots:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">List</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>reflect</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">TypeRef</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">TypeRef</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">User</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> usersType </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">TypeRef</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">User</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token generics punctuation" style=color:#393A34>></span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">User</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> users </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> json</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>fromJson</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"[{\"id\":7,\"name\":\"Alice\"}]"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> usersType</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">String</span><span class="token plain"> encoded </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> json</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toJson</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">users</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> usersType</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>Typed writes require fully bound types and reject wildcards and type variables. Values must be |
| assignable to the declared raw type. The declared schema controls serialization, including nested |
| generic element types and closed subtype metadata.</p> |
| <p>Use a declared base type when it owns <code>JsonSubTypes</code>:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token class-name">Shape</span><span class="token plain"> shape </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">Circle</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">json</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toJson</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">shape</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Concrete runtime representation</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">json</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toJson</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">shape</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token class-name">Shape</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Configured Shape subtype representation</span><br/></div></code></pre></div></div> |
| <p>For <code>List<Shape></code>, use <code>new TypeRef<List<Shape>>() {}</code> so each element retains the declared subtype |
| schema.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=thread-safety-and-code-generation>Thread safety and code generation<a href=#thread-safety-and-code-generation class=hash-link aria-label="Direct link to Thread safety and code generation" title="Direct link to Thread safety and code generation" translate=no></a></h2> |
| <p><code>ForyJson</code> is immutable and thread-safe after <code>build()</code>. Registered and annotation-selected |
| <code>JsonValueCodec</code> instances and type checkers are shared and must also be thread-safe.</p> |
| <p>Code generation and asynchronous compilation are enabled by default. Disable them for diagnostics |
| or environments that prohibit runtime compilation:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token class-name">ForyJson</span><span class="token plain"> json </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withCodegen</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withAsyncCompilation</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p><code>withConcurrencyLevel</code> sets the maximum number of root operations that execute concurrently. |
| Additional callers wait until one of those fixed execution states is available. Root APIs on one |
| <code>ForyJson</code> instance are not reentrant: a custom codec must continue through the concrete reader or |
| writer passed to it instead of calling <code>toJson</code>, <code>toJsonBytes</code>, <code>writeJsonTo</code>, or <code>fromJson</code> on that |
| instance.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=object-mapping>Object mapping<a href=#object-mapping class=hash-link aria-label="Direct link to Object mapping" title="Direct link to Object mapping" translate=no></a></h2> |
| <p>Default discovery merges members with the same Java logical property name:</p> |
| <ul> |
| <li class="">eligible instance fields across the hierarchy, regardless of Java visibility;</li> |
| <li class="">public non-static <code>getX()</code> and boolean <code>isX()</code> getters;</li> |
| <li class="">public non-static void <code>setX(value)</code> setters.</li> |
| </ul> |
| <p>Static, transient, synthetic, and <code>Class<?></code> fields are excluded. Class-valued accessors and |
| <code>getClass()</code> are excluded. An annotation on an ineligible member fails rather than becoming a |
| silent no-op.</p> |
| <p>An ordinary final field is a write source but not a mutable read sink. Use a record, <code>JsonCreator</code>, |
| or custom codec for immutable construction. Records use their canonical constructor.</p> |
| <p>Enable field-only discovery with:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token class-name">ForyJson</span><span class="token plain"> json </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withFieldMode</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>In field mode, getter/setter annotations are invalid. For ordinary properties, unknown members are |
| skipped and duplicate members use the last value. Polymorphic discriminator members are stricter |
| and must occur exactly once. JSON null is rejected for primitive targets. Most reference targets |
| return null, but a selected built-in or custom codec may define another result; declared Optional |
| targets return the corresponding empty Optional.</p> |
| <p>An ordinary class with a no-argument constructor runs it before readable properties are assigned, |
| so missing properties retain values established by field initializers or the constructor. On an |
| ordinary JVM, a class without such a constructor is allocated without running its constructors or |
| field initializers, and missing properties retain JVM zero or null values. Android cannot construct |
| an ordinary class without a usable no-argument constructor. GraalVM native image on JDK 25 and |
| later also requires one for most ordinary classes; the supported exception is a <code>Serializable</code> |
| class whose first non-serializable superclass is <code>Object</code>.</p> |
| <p>For portable construction, use a record, <code>JsonCreator</code>, or a no-argument constructor. Do not use an |
| ordinary constructor as a deserialization completion hook: property assignment follows a |
| no-argument constructor, while constructor-bypassing paths do not run it.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=supported-java-types>Supported Java types<a href=#supported-java-types class=hash-link aria-label="Direct link to Supported Java types" title="Direct link to Supported Java types" translate=no></a></h2> |
| <table><thead><tr><th>Group<th>Types and behavior<tbody><tr><td>Scalars<td>Primitive and boxed booleans/numbers/chars, strings and string builders, <code>BigInteger</code>, <code>BigDecimal</code>, Fory half-precision numbers, enums<tr><td>Containers<td>Primitive/boxed/object arrays; collection, list, set, queue, deque, blocking, sorted, and navigable interfaces; map, sorted-map, navigable-map, and concurrent-map interfaces; supported concrete implementations; <code>EnumSet</code>; <code>EnumMap</code>; <code>Optional</code> variants; atomic values and arrays<tr><td>Time<td><code>Date</code>, <code>Calendar</code>, <code>TimeZone</code>, Java time types, supported chronology dates, optional <code>java.sql.Date</code>, <code>Time</code>, and <code>Timestamp</code><tr><td>Other JDK<td><code>UUID</code>, <code>URI</code>, <code>File</code>, <code>Path</code>, <code>Locale</code>, <code>Charset</code>, <code>Currency</code>, <code>Pattern</code>, <code>BitSet</code>, <code>ByteBuffer</code><tr><td>Optional libraries<td>Guava <code>ImmutableList</code>, <code>ImmutableSet</code>, <code>ImmutableSortedSet</code>, <code>ImmutableMap</code>, <code>ImmutableBiMap</code>, <code>ImmutableSortedMap</code>, and <code>ImmutableIntArray</code> when Guava is present<tr><td>Objects<td>Mutable concrete classes, records, creator classes, <code>JsonObject</code>, <code>JsonArray</code></table> |
| <p>Interfaces are reconstructed with appropriate standard mutable implementations. <code>ArrayBlockingQueue</code>, |
| <code>Arrays.asList</code> results, JDK immutable collections, empty/singleton/unmodifiable wrappers, |
| constructor-constrained implementations, and unlisted Guava immutable implementations cannot be |
| reconstructed. Guava remains optional.</p> |
| <p>Non-finite float/double values use quoted <code>"NaN"</code>, <code>"Infinity"</code>, and <code>"-Infinity"</code> tokens.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=built-in-representations>Built-in representations<a href=#built-in-representations class=hash-link aria-label="Direct link to Built-in representations" title="Direct link to Built-in representations" translate=no></a></h3> |
| <table><thead><tr><th>Java type<th>JSON representation<tbody><tr><td>Enum<td>Constant name string<tr><td><code>Date</code>, <code>Calendar</code>, <code>java.sql.Date</code>, <code>Time</code>, <code>Timestamp</code><td>Epoch-millisecond number<tr><td><code>TimeZone</code><td>Time-zone ID string<tr><td>Java time and supported chronology date types<td>Standard textual string<tr><td><code>UUID</code>, <code>URI</code>, <code>File</code>, <code>Path</code>, <code>Locale</code>, <code>Charset</code>, <code>Currency</code>, <code>Pattern</code><td>Type-specific text string; <code>File</code> and <code>Path</code> use path text, <code>Locale</code> uses a language tag, and <code>Pattern</code> loses flags<tr><td><code>BitSet</code><td>Array of signed <code>long</code> words<tr><td><code>ByteBuffer</code><td>Array of signed byte values from position to limit<tr><td>Optional and atomic wrappers<td>Contained scalar, array, or value directly</table> |
| <p><code>Calendar</code> is reconstructed as a new <code>GregorianCalendar</code>, so its original subtype, time zone, and |
| other configuration are not retained. A null Optional reference and an empty Optional both write |
| JSON null; reading JSON null as a declared Optional type returns the corresponding empty Optional.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=dynamic-json-trees>Dynamic JSON trees<a href=#dynamic-json-trees class=hash-link aria-label="Direct link to Dynamic JSON trees" title="Direct link to Dynamic JSON trees" translate=no></a></h3> |
| <p>Reading <code>Object.class</code> produces natural JSON values:</p> |
| <table><thead><tr><th>JSON<th>Java<tbody><tr><td>Object<td><code>JsonObject</code><tr><td>Array<td><code>JsonArray</code><tr><td>String/boolean/null<td><code>String</code>, <code>Boolean</code>, null<tr><td>Integer<td><code>Long</code>, or <code>BigInteger</code> outside long range<tr><td>Fraction/exponent<td><code>Double</code></table> |
| <p><code>JsonObject</code> preserves insertion order and <code>JsonArray</code> is mutable.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=map-keys>Map keys<a href=#map-keys class=hash-link aria-label="Direct link to Map keys" title="Direct link to Map keys" translate=no></a></h3> |
| <p>Declared keys support String, byte, short, int, long, their boxed types, and enums. <code>Object</code> keys |
| can write String, number, boolean, character, and enum values, but read back as strings. Null keys |
| are rejected.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=builder-configuration>Builder configuration<a href=#builder-configuration class=hash-link aria-label="Direct link to Builder configuration" title="Direct link to Builder configuration" translate=no></a></h2> |
| <table><thead><tr><th>Method<th>Default<th>Effect<tbody><tr><td><code>writeNullFields</code><td><code>false</code><td>Default null-property inclusion<tr><td><code>withCodegen</code><td><code>true</code><td>Generated object codecs<tr><td><code>withAsyncCompilation</code><td><code>true</code><td>Asynchronous generated-code compilation<tr><td><code>withFieldMode</code><td><code>false</code><td>Field-only discovery when true<tr><td><code>withPropertyNamingStrategy</code><td><code>LOWER_CAMEL_CASE</code><td>Naming of properties without explicit names<tr><td><code>withClassLoader</code><td>Snapshotted context loader, then Fory loader<td>Resolve annotation subtype class names<tr><td><code>maxDepth</code><td><code>20</code><td>Maximum nested object/array depth<tr><td><code>withMaxCachedFieldNames</code><td><code>DEFAULT_MAX_CACHED_FIELD_NAMES</code> (<code>8192</code>)<td>Field-name cache entries per reader; zero disables it<tr><td><code>withConcurrencyLevel</code><td><code>max(1, 2 * processors)</code><td>Maximum concurrent root operations<tr><td><code>withBufferSizeLimitBytes</code><td>2 MiB<td>Reusable capacity retained by each pooled writer<tr><td><code>registerCodec</code><td>None<td>Exact-class complete-value codec<tr><td><code>registerMixin</code><td>None<td>Annotation Mixin for its exact declared target<tr><td><code>withTypeChecker</code><td>None<td>Application policy in addition to Fory's disallow list</table> |
| <p>Depth, concurrency, and retained buffer limits must be positive. The cached-field-name limit applies |
| independently to each reader; zero disables the cache, and the setting does not limit accepted |
| input. The buffer setting does not limit output size. Builder changes after <code>build()</code> do not mutate |
| an existing runtime.</p> |
| <p>In a GraalVM native image, runtime code generation and asynchronous compilation are automatically |
| disabled. Every other builder option keeps the behavior described above.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=annotations>Annotations<a href=#annotations class=hash-link aria-label="Direct link to Annotations" title="Direct link to Annotations" translate=no></a></h2> |
| <p>Fory JSON provides <code>JsonProperty</code>, <code>JsonPropertyOrder</code>, <code>JsonIgnore</code>, <code>JsonAnyProperty</code>, |
| <code>JsonAnyGetter</code>, <code>JsonAnySetter</code>, <code>JsonCreator</code>, <code>JsonCodec</code>, <code>JsonValue</code>, <code>JsonRawValue</code>, |
| <code>JsonBase64</code>, <code>JsonUnwrapped</code>, and <code>JsonSubTypes</code> as mapping annotations under |
| <code>org.apache.fory.json.annotation</code>. <code>JsonType</code> is a separate build-time generation marker. They are |
| not Jackson, Gson, or Fory binary-protocol annotations.</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">LinkedHashMap</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">Map</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">PropertyNamingStrategy</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonAnyGetter</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonAnyProperty</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonAnySetter</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonBase64</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonCodec</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonCreator</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonIgnore</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonMixin</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonMixinRemove</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonProperty</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonPropertyOrder</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonRawValue</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonSubTypes</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonType</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonValue</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonUnwrapped</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p><code>JsonType</code> asks the annotation processor to generate direct property and creator operations plus |
| the exact retention rules for an eligible concrete object model. A directly annotated |
| <code>JsonValue</code> Record also receives a companion so its value accessor and canonical constructor work |
| after Android desugaring. The same generated companion is used on the JVM, Android, and GraalVM |
| Native Image. The annotation is not inherited; a concrete subtype needs its own direct annotation |
| to receive a companion. See |
| <a class="" href=/docs/guide/java/graalvm_support>GraalVM Support</a> and <a class="" href=/docs/guide/java/android_support>Android Support</a> for setup. |
| A directly annotated model that uses the default object codec requires that generated companion; |
| the runtime reports a configuration error if the processor output is missing.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=mixins>Mixins<a href=#mixins class=hash-link aria-label="Direct link to Mixins" title="Direct link to Mixins" translate=no></a></h3> |
| <p>Use a Mixin to configure an existing class without changing its source:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonMixin</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonProperty</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonUnwrapped</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token annotation punctuation" style=color:#393A34>@JsonMixin</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">target </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">ThirdPartyUser</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>abstract</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">ThirdPartyUserMixin</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"user_id"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonUnwrapped</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">prefix </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"address_"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">Address</span><span class="token plain"> address</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">ForyJson</span><span class="token plain"> json </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>registerMixin</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">ThirdPartyUserMixin</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>The source must be a named abstract class or interface, must not be local or anonymous, must not |
| extend or implement another type, and is never instantiated. An annotated source field, method, |
| constructor, or parameter selects an existing target declaration by its Java signature. The source |
| cannot invent a Java field, method, constructor, generic type, subtype implementation, or executable |
| body. It may assign supported JSON roles such as property, creator, factory, subtype table, or value |
| representation to matching declarations that already exist on the target. Every Java type, access |
| operation, invocation, and runtime value still comes from the target.</p> |
| <p>Registration is exact-target only. A base-class registration does not change a subclass, and an |
| interface registration does not change an implementation. A subclass Mixin may select a member |
| that the subclass inherits, but the resulting annotation applies only while that exact subclass is |
| mapped.</p> |
| <p>All Fory JSON mapping annotations are supported: <code>JsonAnyGetter</code>, <code>JsonAnyProperty</code>, |
| <code>JsonAnySetter</code>, <code>JsonBase64</code>, <code>JsonCodec</code>, <code>JsonCreator</code>, <code>JsonIgnore</code>, <code>JsonProperty</code>, |
| <code>JsonPropertyOrder</code>, <code>JsonRawValue</code>, <code>JsonSubTypes</code>, <code>JsonUnwrapped</code>, and <code>JsonValue</code>. <code>JsonType</code> |
| cannot be added or removed because it controls build-time generation rather than the JSON schema.</p> |
| <p>A source annotation replaces the target annotation of the same type on the matched declaration. |
| The complete annotation is replaced, so omitted members use their declared defaults instead of |
| inheriting values from the target annotation. Other annotation types on that target declaration |
| remain effective.</p> |
| <p>Use <code>JsonMixinRemove</code> to make selected target annotations ineffective:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonMixin</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonMixinRemove</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonRawValue</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token annotation punctuation" style=color:#393A34>@JsonMixin</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">target </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">ThirdPartyMessage</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>abstract</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">QuotedMessageMixin</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonMixinRemove</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">JsonRawValue</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> body</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Removal affects only the matched declaration in the exact-target configuration. Removing |
| <code>JsonRawValue</code> restores ordinary quoted String output; removing <code>JsonBase64</code> restores the ordinary |
| <code>byte[]</code> representation; removing <code>JsonUnwrapped</code> restores a nested object property. Type-level |
| removal can mask inherited <code>JsonCodec</code> or <code>JsonPropertyOrder</code> declarations for the exact target. |
| Removing an absent annotation is harmless, but the selector must still match exactly one target |
| declaration. A source cannot both declare and remove the same annotation type on one declaration.</p> |
| <p>Only one source is enabled for an exact target in a built runtime. Registering a different source |
| for the same target replaces the earlier registration, while registering the same source again is |
| idempotent. <code>build()</code> snapshots the current last-registration-wins mapping; a later registration on |
| the builder does not change a previously built <code>ForyJson</code>. A source with no mapping annotations is |
| a no-op; registering it after another source for the same target clears the earlier overlay for |
| subsequent builds.</p> |
| <p>A <code>JsonCodec</code> supplied by a Mixin is the target's effective annotation and follows the ordinary |
| codec precedence below. In particular, an exact <code>registerCodec</code> registration wins over a type-level |
| Mixin codec, while a type-level Mixin codec wins over the built-in mapping for that target.</p> |
| <p>Records use their existing field, accessor, and canonical-constructor parameter declarations. A |
| Mixin does not introduce a separate record-component model. Use source selectors for those real |
| declarations and keep repeated annotations consistent as required by normal record property |
| mapping.</p> |
| <p>On Android and GraalVM Native Image, compile non-empty Mixin sources with the Fory annotation |
| processor so required generated operations and platform configuration are available. See |
| <a class="" href=/docs/guide/java/android_support>Android Support</a> and <a class="" href=/docs/guide/java/graalvm_support>GraalVM Support</a>.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsonproperty><code>JsonProperty</code><a href=#jsonproperty class=hash-link aria-label="Direct link to jsonproperty" title="Direct link to jsonproperty" translate=no></a></h3> |
| <p>An annotation on a field, getter, or setter configures the complete merged logical property:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"user_id"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">include </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">JsonProperty</span><span class="token class-name punctuation" style=color:#393A34>.</span><span class="token class-name">Include</span><span class="token punctuation" style=color:#393A34>.</span><span class="token constant" style=color:#36acaa>ALWAYS</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> displayName</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">index </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> email</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>Supported inclusion values are:</p> |
| <ul> |
| <li class=""><code>DEFAULT</code>: inherit <code>writeNullFields</code>;</li> |
| <li class=""><code>ALWAYS</code>: include null;</li> |
| <li class=""><code>NON_NULL</code>: omit null.</li> |
| </ul> |
| <p><code>index</code> controls relative serialization order. Indexed properties are written in ascending index |
| order before unindexed properties. Indexes must be non-negative, may contain gaps, and must be |
| unique among writable properties. <code>-1</code> means unspecified; lower values are invalid. An index on a |
| setter-only, creator-only, or write-ignored property is invalid.</p> |
| <p>Inclusion affects writing only. Identical repeated declarations are allowed; conflicting explicit |
| names, indexes, or non-default policies fail. Two properties cannot normalize to the same JSON |
| name. <code>JsonProperty</code> cannot be combined with an Any logical property or declared on a |
| <code>JsonAnySetter</code>. <code>NON_EMPTY</code>, aliases, and formatting are unsupported.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsonpropertyorder><code>JsonPropertyOrder</code><a href=#jsonpropertyorder class=hash-link aria-label="Direct link to jsonpropertyorder" title="Direct link to jsonpropertyorder" translate=no></a></h3> |
| <p>Use <code>JsonPropertyOrder</code> to combine a named prefix, property indexes, and final-name alphabetic |
| ordering:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonPropertyOrder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"id"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"display_name"</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> alphabetic </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">index </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>20</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"display_name"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> index </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> displayName</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> address</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>The output order is <code>id</code>, <code>display_name</code>, <code>name</code>, <code>address</code>, then <code>age</code>:</p> |
| <div class="language-json codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-json codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"id"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"display_name"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"Alice"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"name"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"alice"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"address"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"x"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"age"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>30</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>The named prefix is written first. Remaining indexed properties follow in ascending index order. |
| When <code>alphabetic = true</code>, remaining unindexed properties are sorted by final JSON name; otherwise |
| they keep their existing relative order. Use <code>@JsonPropertyOrder(alphabetic = true)</code> when no named |
| prefix is needed. Alphabetic comparison uses Java's natural, case-sensitive String order and does |
| not depend on the locale.</p> |
| <p>Order entries match the final JSON name first and the Java logical property name second. This lets |
| <code>display_name</code> match an explicit <code>JsonProperty</code> name while an unannotated <code>displayName</code> can still be |
| addressed by either <code>display_name</code> under <code>SNAKE_CASE</code> or its Java name <code>displayName</code>.</p> |
| <p>The list may be empty only when <code>alphabetic</code> is true. Its entries must be non-empty, unique writable |
| properties; unknown and duplicate entries fail when the object metadata is built. A subclass |
| declaration replaces both settings from its superclass as a whole; declarations are not merged. If |
| the subclass has no declaration, the nearest superclass declaration is used and resolved against the |
| subclass properties. Interface declarations are not considered.</p> |
| <p>Property order affects serialization only. Deserialization remains name-based and accepts members |
| in any order. Subtype discriminators remain before user properties.</p> |
| <p>An unwrapped group also occupies one position, selected by the group's Java logical property name. |
| Its child members remain adjacent and retain the child's own order.</p> |
| <p>A write-enabled <code>JsonAnyProperty</code> or <code>JsonAnyGetter</code> participates as one position identified by its |
| Java logical property name:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonPropertyOrder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"id"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"properties"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"timestamp"</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Event</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonAnyProperty</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Map</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">String</span><span class="token generics punctuation" style=color:#393A34>,</span><span class="token generics"> </span><span class="token generics class-name">Object</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> properties</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> timestamp</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>The position emits every <code>properties</code> entry in Map iteration order between <code>id</code> and <code>timestamp</code>; it |
| does not emit a member named <code>properties</code>. Naming strategies do not transform the Any ordering |
| name. Input-only Any fields and <code>JsonAnySetter</code> have no write position. Dynamic keys cannot appear |
| in <code>JsonPropertyOrder</code>, and alphabetic ordering never sorts entries inside the Map.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=naming-strategy>Naming strategy<a href=#naming-strategy class=hash-link aria-label="Direct link to Naming strategy" title="Direct link to Naming strategy" translate=no></a></h3> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token class-name">ForyJson</span><span class="token plain"> json </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withPropertyNamingStrategy</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">PropertyNamingStrategy</span><span class="token punctuation" style=color:#393A34>.</span><span class="token constant" style=color:#36acaa>SNAKE_CASE</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>The default <code>LOWER_CAMEL_CASE</code> preserves the discovered Java logical property name. <code>SNAKE_CASE</code> |
| maps <code>userName</code> to <code>user_name</code>, <code>URLValue</code> to <code>url_value</code>, and <code>version2FA</code> to <code>version2_fa</code>. |
| Explicit <code>JsonProperty</code> names, parameter-local creator names, and subtype discriminator properties |
| bypass the strategy. Dynamic Any keys also bypass it.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsonignore><code>JsonIgnore</code><a href=#jsonignore class=hash-link aria-label="Direct link to jsonignore" title="Direct link to jsonignore" translate=no></a></h3> |
| <p><code>JsonIgnore</code> is field-targeted and controls both directions of the complete logical property:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonIgnore</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">ignoreRead </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ignoreWrite </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> serverManagedValue</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>Both flags default to true. Accessors cannot restore an ignored direction, and <code>JsonProperty</code> |
| cannot override it. Fory core's <code>Expose</code> has no effect in Fory JSON.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsonvalue><code>JsonValue</code><a href=#jsonvalue class=hash-link aria-label="Direct link to jsonvalue" title="Direct link to jsonvalue" translate=no></a></h3> |
| <p>Use <code>JsonValue</code> when one exact <code>String</code> member is the complete JSON representation of its owning |
| type. Fory writes it as an ordinary quoted and escaped JSON string instead of an object:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonCreator</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonValue</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">UserId</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCreator</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">UserId</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">String</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonValue</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>value</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>The method may use any name but must be public, non-static, zero-argument, and return exactly |
| <code>String</code>. A field must be an eligible non-static instance field. Only one effective member is |
| allowed, and an unannotated override suppresses an inherited method annotation.</p> |
| <p>The annotation controls writing on its own. Reading requires a <code>JsonCreator</code> constructor or public |
| static factory with one exact <code>String</code> parameter, empty <code>JsonCreator.value()</code>, and no <code>JsonProperty</code> |
| on the parameter. This shape is inferred as the reverse String constructor; no creator mode is |
| needed. Existing property-based creator forms are unchanged. JSON null maps directly to Java null |
| without invoking the value member or creator.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsonrawvalue><code>JsonRawValue</code><a href=#jsonrawvalue class=hash-link aria-label="Direct link to jsonrawvalue" title="Direct link to jsonrawvalue" translate=no></a></h3> |
| <p>Use <code>JsonRawValue</code> on a fixed ordinary <code>String</code> property whose contents are already one complete |
| JSON value:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonRawValue</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Response</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> status</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonRawValue</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> body</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>For <code>body = "{\"id\":1}"</code>, Fory emits the object directly at the <code>body</code> value position. It does not |
| quote, escape, parse, validate, or normalize the String. This is a trusted write-only escape hatch; |
| invalid or attacker-controlled content can make the entire output invalid or change its structure. |
| Java null follows the property's existing inclusion rule and is written as JSON null when included.</p> |
| <p>Reading is unchanged and still expects a JSON string. A raw object or array written through the |
| property cannot be read back into that <code>String</code>. The annotation does not apply to setters, creator |
| parameters, Any declarations, container elements, or Map values, and it cannot share an occurrence |
| with <code>JsonCodec</code>. |
| As an occurrence-local representation, it keeps the raw String shape even when the value type has |
| an exact builder-registered codec.</p> |
| <p>Neither annotation collects unknown sibling fields. Unknown fields are skipped unless an existing |
| <code>JsonAnyProperty</code> or <code>JsonAnyGetter</code>/<code>JsonAnySetter</code> mapping owns them. Combining <code>JsonValue</code> and |
| <code>JsonRawValue</code> on the same String member writes the owning object as a trusted raw root value, but |
| does not add a raw-fragment read contract.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsonbase64><code>JsonBase64</code><a href=#jsonbase64 class=hash-link aria-label="Direct link to jsonbase64" title="Direct link to jsonbase64" translate=no></a></h3> |
| <p>Use <code>JsonBase64</code> on one exact <code>byte[]</code> field or getter to represent it as a quoted standard Base64 |
| JSON string:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonBase64</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Attachment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonBase64</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>byte</span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> content</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Bytes <code>{1, 2, 3}</code> are written as <code>{"content":"AQID"}</code> and decoded back to the original array. |
| Encoding and decoding do not create an intermediate String. Null handling follows the property's |
| normal inclusion rule.</p> |
| <p>The annotation is not a type-use annotation and does not affect ordinary <code>byte[]</code> properties, |
| container elements, or Map values. It cannot share a logical property with <code>JsonRawValue</code>, an |
| occurrence <code>JsonCodec</code>, or an Any declaration. The equivalent explicit codec is |
| <code>@JsonCodec(Base64ByteArrayCodec.class)</code>.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsonunwrapped><code>JsonUnwrapped</code><a href=#jsonunwrapped class=hash-link aria-label="Direct link to jsonunwrapped" title="Direct link to jsonunwrapped" translate=no></a></h3> |
| <p>Use <code>JsonUnwrapped</code> when an object-valued property should keep its Java object boundary but place |
| its members in the containing JSON object:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>annotation</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonUnwrapped</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonUnwrapped</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">prefix </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"name_"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Name</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Name</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> first</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> last</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>This writes <code>{"age":18,"name_first":"Ada","name_last":"Lovelace"}</code> instead of a |
| nested <code>name</code> object. <code>prefix</code> and <code>suffix</code> apply to every final child name after <code>JsonProperty</code> and |
| the configured naming strategy. Nested groups compose these transformations from the inside out.</p> |
| <p>A null child emits no members. During reading, the child is created only when at least one |
| flattened member is present. A missing group preserves a mutable parent's initialized value and |
| leaves a record or creator argument at its normal missing-property default. Partial input creates |
| the child and uses ordinary defaults for its other members.</p> |
| <p>Mutable classes, records, and <code>JsonCreator</code> classes are supported as parents and children. A |
| parameter-local creator parameter can define a read-only group; its required <code>JsonProperty</code> value |
| identifies the Java argument and is not a wrapper name. The containing parent may be parameterized, |
| but each unwrapped child and intermediate must be an exact raw, non-generic class using the standard |
| Fory object mapping.</p> |
| <p>The complete group occupies one position in parent serialization order. Position it with |
| <code>JsonProperty.index</code>, or list its Java logical property name in <code>JsonPropertyOrder</code>. Child ordering |
| is preserved inside the group. Input matches parent fixed properties first, flattened properties |
| second, and dynamic Any members last.</p> |
| <p>Fory rejects duplicate final names, recursive chains made only of unwrapped properties, |
| parameterized children, JSON Any children, polymorphic or custom-codec child roots, and scalar, |
| array, collection, or Map children. Flatten Maps with <code>JsonAnyProperty</code>, <code>JsonAnyGetter</code>, or |
| <code>JsonAnySetter</code>. An unwrapped property cannot use <code>JsonProperty.value</code>, a non-default |
| <code>JsonProperty.include</code>, or <code>JsonCodec</code>; ordinary leaf properties inside the child keep their normal |
| annotations.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=dynamic-object-members>Dynamic object members<a href=#dynamic-object-members class=hash-link aria-label="Direct link to Dynamic object members" title="Direct link to Dynamic object members" translate=no></a></h3> |
| <p>Use <code>JsonAnyProperty</code> to flatten a <code>Map<String, V></code> field into the containing JSON object and store |
| otherwise unknown input members:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Event</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonAnyProperty</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Map</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">String</span><span class="token generics punctuation" style=color:#393A34>,</span><span class="token generics"> </span><span class="token generics class-name">Object</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> properties </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">LinkedHashMap</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>For <code>properties</code> containing <code>"source" -> "mobile"</code>, the result contains <code>"source":"mobile"</code> |
| beside <code>id</code>; no nested <code>properties</code> member is written. The field reads and writes by default. |
| <code>JsonIgnore</code> may select one direction, but it cannot disable both. During reading, Fory reuses an |
| existing Map or initializes a null non-final field on the first unknown member. A readable final |
| field on an ordinary mutable object must already contain a mutable Map. Records and property-list |
| <code>JsonCreator</code> types instead receive the accumulated Map through their construction argument.</p> |
| <p>Use <code>JsonAnyGetter</code> and <code>JsonAnySetter</code> for method-backed writing and reading:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Event</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token class-name">Map</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">String</span><span class="token generics punctuation" style=color:#393A34>,</span><span class="token generics"> </span><span class="token generics class-name">Object</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> properties </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">LinkedHashMap</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonAnyGetter</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Map</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">String</span><span class="token generics punctuation" style=color:#393A34>,</span><span class="token generics"> </span><span class="token generics class-name">Object</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> </span><span class="token function" style=color:#d73a49>getProperties</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> properties</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonAnySetter</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>void</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>putProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token class-name">Object</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> properties</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>put</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">name</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>An any-getter must be a public instance method with no arguments and a <code>Map<String, V></code> return type. |
| An any-setter must be a public instance method with signature <code>void method(String, V)</code>. Either may |
| be used independently. When paired, their resolved value types must match after primitive types are |
| boxed. A primitive any-setter value rejects JSON null. Any-setters are not supported on records or |
| types using <code>JsonCreator</code>.</p> |
| <p>A read-enabled <code>JsonAnyProperty</code> on a record component supplies that component from unknown input. |
| In property-list creator mode, a read-enabled Any field must correspond to one listed creator |
| argument; parameter-local creator mode cannot bind it. A write-only Any field or any-getter cannot |
| occupy a creator argument. If one claims a record component, that component receives its normal |
| Java default during reading.</p> |
| <p>An any-getter claims its complete Java logical property: both <code>getProperties()</code> and <code>properties()</code> |
| claim <code>properties</code>, so same-named ordinary fields and accessors are not mapped again as a fixed |
| member. Fory does not infer a differently named backing field; use <code>JsonIgnore</code> if that field must |
| not be mapped separately. An any-setter has no logical property name and does not claim a field.</p> |
| <p>The logical name is used only for grouping and <code>JsonPropertyOrder</code>; it is not a fixed JSON member. |
| An input member with that name is a dynamic entry rather than a nested aggregate. The same output |
| key remains valid unless another fixed property conflicts with it.</p> |
| <p>One effective type hierarchy may use either one Any field or up to one any-getter and one |
| any-setter. Field-backed and method-backed forms cannot be mixed, and method annotations are invalid |
| in field mode. An unannotated override disables an inherited method annotation. <code>JsonProperty</code> is |
| invalid on an any-setter and on every member claimed by an Any field or getter. A same-named field |
| cannot use <code>JsonIgnore</code> to suppress an any-getter's write direction, and its <code>ignoreRead</code> flag does |
| not disable a separate any-setter.</p> |
| <p>Dynamic keys are emitted unchanged in Map iteration order. A null Map emits nothing, while a null |
| Map value emits JSON null regardless of fixed-property null settings. Null and non-String output |
| keys are rejected. Raw Maps, wildcard or unresolved keys, and non-String key types are invalid. |
| Declared fixed members, including members excluded from reading, are not delivered to an Any |
| input. An output key that conflicts with a fixed property is rejected. Fory does not inspect an Any |
| Map for a key that duplicates an inline subtype discriminator; such a key emits a duplicate JSON |
| member. Applications must keep dynamic keys distinct from the active discriminator. Repeated |
| unknown names replace the Map value; an any-setter is called for every occurrence. Escaped input |
| names are decoded before delivery.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsoncreator><code>JsonCreator</code><a href=#jsoncreator class=hash-link aria-label="Direct link to jsoncreator" title="Direct link to jsoncreator" translate=no></a></h3> |
| <p>The compact mode lists existing Java logical property names in parameter order and reuses their |
| normalized metadata:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCreator</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"id"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"name"</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Parameter-local mode gives every parameter an explicit JSON name and permits creator-only inputs:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonCreator</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>static</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>create</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"user_id"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"display_name"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">id</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>The modes cannot be mixed. Compact names must be non-empty and unique, their count must match the |
| parameter count, and compact parameters cannot also declare <code>JsonProperty</code>. Parameter-local mode |
| requires a non-empty, unique <code>JsonProperty</code> name on every parameter. The creator is the complete |
| read schema and setters do not run after it.</p> |
| <p>For a type with <code>JsonValue</code>, the empty form also accepts exactly one <code>String</code> parameter without |
| <code>JsonProperty</code> and reconstructs the owning value from its ordinary JSON string representation.</p> |
| <p>Exactly one creator is allowed. It must be public, have at least one parameter, and be neither |
| varargs nor generic. A factory is also static, declares the target class as its exact return type, |
| and returns a non-null value whose runtime class is exactly the target. Missing references use null, |
| missing primitives use zero, duplicate members use the last value, and explicit primitive null |
| fails. Records cannot declare a property-based <code>JsonCreator</code>; a record with <code>JsonValue</code> may annotate |
| its one-String canonical constructor for the value form.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=jsonsubtypes><code>JsonSubTypes</code><a href=#jsonsubtypes class=hash-link aria-label="Direct link to jsonsubtypes" title="Direct link to jsonsubtypes" translate=no></a></h3> |
| <p><code>JsonSubTypes</code> defines a complete finite table on an interface or abstract base. Each entry has a |
| case-sensitive logical name and exactly one Java source: a class literal or trusted binary |
| <code>className</code>. JSON never supplies class names or expands the table.</p> |
| <p>Default property inclusion:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonSubTypes</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> property </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"kind"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonSubTypes.Type</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Circle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"circle"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonSubTypes.Type</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> className </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"com.example.shape.Rectangle"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"rectangle"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>interface</span><span class="token plain"> </span><span class="token class-name">Shape</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <div class="language-json codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-json codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"kind"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"circle"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"radius"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>The discriminator is emitted first but may appear at any direct input member position. It must |
| occur exactly once, contain a known String name, and not collide with a subtype property.</p> |
| <p>Wrapper object:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonSubTypes</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> inclusion </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">JsonSubTypes</span><span class="token class-name punctuation" style=color:#393A34>.</span><span class="token class-name">Inclusion</span><span class="token punctuation" style=color:#393A34>.</span><span class="token constant" style=color:#36acaa>WRAPPER_OBJECT</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token annotation punctuation" style=color:#393A34>@JsonSubTypes.Type</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Circle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"circle"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>interface</span><span class="token plain"> </span><span class="token class-name">Shape</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <div class="language-json codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-json codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"circle"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"radius"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Wrapper array:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonSubTypes</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> inclusion </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">JsonSubTypes</span><span class="token class-name punctuation" style=color:#393A34>.</span><span class="token class-name">Inclusion</span><span class="token punctuation" style=color:#393A34>.</span><span class="token constant" style=color:#36acaa>WRAPPER_ARRAY</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token annotation punctuation" style=color:#393A34>@JsonSubTypes.Type</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Circle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"circle"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>interface</span><span class="token plain"> </span><span class="token class-name">Shape</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <div class="language-json codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-json codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>"circle"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"radius"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>]</span><br/></div></code></pre></div></div> |
| <table><thead><tr><th>Inclusion<th><code>property</code><th>Value rule<tbody><tr><td><code>PROPERTY</code><td>Required and non-empty<td>Ordinary subtype object members<tr><td><code>WRAPPER_OBJECT</code><td>Must be empty<td>Complete subtype value<tr><td><code>WRAPPER_ARRAY</code><td>Must be empty<td>Complete subtype value as element 1</table> |
| <p>Wrapper inclusions support exact custom subtype codecs. Logical names and resolved concrete, |
| assignable classes must each be unique. Only exact listed runtime classes are accepted; listing a |
| parent does not admit descendants. The annotation is read from the declared base itself and is not |
| inherited from another annotated base. Null is plain JSON null unless codec precedence selects a |
| custom complete-value codec for the declared base, replacing the annotation. Readers accept only |
| the configured shape, so changing inclusion is a wire-format change. At GraalVM native-image |
| runtime, annotate the base with <code>JsonType</code> and use class literals instead of <code>className</code>. Listed |
| class-literal subtypes are registered automatically.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=custom-codecs>Custom codecs<a href=#custom-codecs class=hash-link aria-label="Direct link to Custom codecs" title="Direct link to Custom codecs" translate=no></a></h2> |
| <p><code>JsonValueCodec<T></code> reads and writes one complete JSON value, including null, through Fory's |
| concrete String/UTF-8 writers and Latin-1/UTF-16/UTF-8 readers. It is a direct streaming-value SPI, |
| not a JSON abstract syntax tree (AST) codec. It never handles Map keys; <code>MapKeyCodec</code> owns JSON |
| object member names.</p> |
| <p>For an application codec with the same semantics in every representation, extend |
| <code>AbstractJsonValueCodec<T></code> and implement the JSON shape once:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>math</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">BigDecimal</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>codec</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">AbstractJsonValueCodec</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>reader</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonReader</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>writer</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">JsonWriter</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>extends</span><span class="token plain"> </span><span class="token class-name">AbstractJsonValueCodec</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Money</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@Override</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>void</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>write</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">JsonWriter</span><span class="token plain"> writer</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>if</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>==</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>null</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> writer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>writeNull</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>else</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> writer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>writeBigDecimal</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">value</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">amount</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@Override</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>read</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">JsonReader</span><span class="token plain"> reader</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> reader</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>tryReadNullToken</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>?</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>null</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">reader</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>readBigDecimal</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token class-name">BigDecimal</span><span class="token plain"> amount</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">Money</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">BigDecimal</span><span class="token plain"> amount</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">amount </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> amount</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><code>AbstractJsonValueCodec</code> adds one virtual method call per operation. For a |
| performance-sensitive codec, or when behavior depends on a concrete reader or writer, implement |
| <code>JsonValueCodec<T></code> directly and provide all five representation-specific methods.</p> |
| <p>Register it once:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">ForyJson</span><span class="token plain"> json </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>registerCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Money</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>The parent property still controls its name, ignore direction, and null inclusion before the codec |
| runs. An emitted property and every array, collection, map-value, Optional, or atomic-reference |
| position delegate the complete value, including null. The registered codec instance is shared |
| concurrently and must be thread-safe. A custom codec on a subtype is compatible with wrapper |
| inclusion, not inline property inclusion. A codec on the base replaces its <code>JsonSubTypes</code> |
| annotation.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=selecting-codecs-with-jsoncodec>Selecting codecs with <code>JsonCodec</code><a href=#selecting-codecs-with-jsoncodec class=hash-link aria-label="Direct link to selecting-codecs-with-jsoncodec" title="Direct link to selecting-codecs-with-jsoncodec" translate=no></a></h3> |
| <p>Use <code>@JsonCodec</code> on a class, record, enum, or interface to declare its default complete-value |
| codec. The positional form is shorthand for <code>value</code>:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">AccountCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>interface</span><span class="token plain"> </span><span class="token class-name">Account</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">RetailAccount</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>implements</span><span class="token plain"> </span><span class="token class-name">Account</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Type declarations are inherited through both superclasses and interfaces. The most-specific |
| declaration wins. Unrelated declarations using the same codec are consistent; unrelated |
| declarations using different codecs fail instead of depending on reflection order.</p> |
| <p>On a field or effective ordinary getter, <code>value</code> replaces the complete property value. The same |
| annotation is supported on an effective setter value parameter, a <code>JsonCreator</code> constructor or |
| factory parameter, and a record component through Java's field, accessor, and constructor-parameter |
| propagation:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Invoice</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> total</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> tax</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> discount</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>getTax</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> tax</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>void</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>setDiscount</span><span class="token punctuation" style=color:#393A34>(</span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> discount</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">discount </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> discount</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCreator</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Invoice</span><span class="token punctuation" style=color:#393A34>(</span><span class="token annotation punctuation" style=color:#393A34>@JsonProperty</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"total"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token plain"> total</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">total </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> total</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Use a child member when the standard container should remain in control and only its direct child |
| needs a custom codec:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">List</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">Map</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">Optional</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>concurrent</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>atomic</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">AtomicReference</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>concurrent</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>atomic</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">AtomicReferenceArray</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">InvoiceGroup</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">elementCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Money</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> items</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">elementCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> itemArray</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">elementCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">AtomicReferenceArray</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Money</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> atomicItems</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">contentCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Optional</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Money</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> optional</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">contentCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">AtomicReference</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Money</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> current</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">keyCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">CurrencyKeyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> valueCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Map</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Currency</span><span class="token generics punctuation" style=color:#393A34>,</span><span class="token generics"> </span><span class="token generics class-name">Money</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> byCurrency</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>The child members have these meanings:</p> |
| <table><thead><tr><th>Member<th>Supported current value<th>Direct child handled by the codec<tbody><tr><td><code>elementCodec</code><td><code>Collection<E></code>, <code>E[]</code>, <code>AtomicReferenceArray<E></code><td><code>E</code><tr><td><code>contentCodec</code><td><code>Optional<T></code>, <code>AtomicReference<T></code><td><code>T</code><tr><td><code>keyCodec</code><td><code>Map<K, V></code><td>JSON member name for <code>K</code><tr><td><code>valueCodec</code><td><code>Map<K, V></code><td>direct <code>V</code> value</table> |
| <p>A custom Map-key codec converts between the declared key and a JSON member name:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>java</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>util</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">Locale</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>json</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>codec</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import class-name">MapKeyCodec</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">CurrencyKeyCodec</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>implements</span><span class="token plain"> </span><span class="token class-name">MapKeyCodec</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@Override</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>toName</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Object</span><span class="token plain"> key</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Currency</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> key</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>name</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toLowerCase</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Locale</span><span class="token punctuation" style=color:#393A34>.</span><span class="token constant" style=color:#36acaa>ROOT</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token annotation punctuation" style=color:#393A34>@Override</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Object</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>fromName</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token class-name">Currency</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>valueOf</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">name</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toUpperCase</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Locale</span><span class="token punctuation" style=color:#393A34>.</span><span class="token constant" style=color:#36acaa>ROOT</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Code that used the removed type-use form should move the codec to the owning declaration:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// Before</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">List</span><span class="token operator" style=color:#393A34><</span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token class-name">Money</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> items</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Now</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">elementCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Money</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> items</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>Use <code>contentCodec</code> for an <code>Optional</code> or <code>AtomicReference</code>, <code>valueCodec</code> for a Map value, and |
| <code>elementCodec</code> for an array or <code>AtomicReferenceArray</code> element.</p> |
| <p><code>Iterable<E></code> values that are not <code>Collection<E></code> do not support <code>elementCodec</code>. Use <code>value</code> when a |
| complete codec should own such a value.</p> |
| <p>Child configuration is intentionally one level deep. For <code>List<List<Money>></code>, <code>elementCodec</code> |
| handles each complete <code>List<Money></code>. For <code>Money[][]</code>, it handles each <code>Money[]</code>. To customize a |
| deeper descendant, implement a codec for the complete current value and select it with <code>value</code>.</p> |
| <p><code>value</code> is mutually exclusive with every child member because it already owns the complete current |
| value. An empty annotation, an unsupported child member, or an outer complete codec combined with |
| a child member fails during model construction. A configured direct child must resolve to a |
| concrete type; raw containers, direct wildcards, and unresolved direct type variables are rejected.</p> |
| <p><code>JsonAnyProperty</code> and <code>JsonAnyGetter</code> flatten their Map into the enclosing object. Configure their |
| dynamic values with <code>valueCodec</code>:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token annotation punctuation" style=color:#393A34>@JsonAnyProperty</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token annotation punctuation" style=color:#393A34>@JsonCodec</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">valueCodec </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">MoneyCodec</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">Map</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">String</span><span class="token generics punctuation" style=color:#393A34>,</span><span class="token generics"> </span><span class="token generics class-name">Money</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> extra</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>The first <code>JsonAnySetter</code> parameter is the String property name. Its second parameter may use |
| <code>@JsonCodec(value = ...)</code> or another configuration valid for that parameter's own shape.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=codec-precedence-and-repeated-declarations>Codec precedence and repeated declarations<a href=#codec-precedence-and-repeated-declarations class=hash-link aria-label="Direct link to Codec precedence and repeated declarations" title="Direct link to Codec precedence and repeated declarations" translate=no></a></h3> |
| <p>Fory resolves each current value in this order:</p> |
| <table><thead><tr><th style=text-align:right>Priority<th>Source<tbody><tr><td style=text-align:right>1<td>Current property or parameter <code>JsonCodec</code><tr><td style=text-align:right>2<td>Exact <code>registerCodec</code> registration<tr><td style=text-align:right>3<td>Exact-target type <code>JsonCodec</code> after Mixin overlay<tr><td style=text-align:right>4<td>Inherited-frontier type <code>JsonCodec</code> declaration<tr><td style=text-align:right>5<td>Built-in or default JSON mapping</table> |
| <p>One logical property may expose the annotation from its field, getter, setter parameter, creator |
| parameter, or record propagation. Repeated configurations must be identical; Fory does not merge |
| partial configurations from different declarations. An unannotated effective override suppresses |
| an inherited method annotation.</p> |
| <p>A child member replaces only that direct child. Unconfigured Map siblings continue through the |
| normal precedence. If an exact registration or type declaration supplies a complete codec for the |
| outer container, a property child member is unreachable and therefore rejected.</p> |
| <p>Map keys are JSON object member names and use <code>MapKeyCodec</code>, not <code>JsonValueCodec</code>. A custom key |
| codec class follows the same construction rules as a value codec. Null Map keys are rejected, and |
| decoded keys must match the declared key type.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=codec-construction-and-platform-support>Codec construction and platform support<a href=#codec-construction-and-platform-support class=hash-link aria-label="Direct link to Codec construction and platform support" title="Direct link to Codec construction and platform support" translate=no></a></h3> |
| <p>An annotation codec class must be public, concrete, top-level or static nested, and have a public |
| no-argument constructor. One instance is shared by all annotated sites and concurrent operations of |
| the built <code>ForyJson</code>, so it must be thread-safe. Use <code>registerCodec(Target.class, instance)</code> when a |
| complete-value codec needs configuration.</p> |
| <p>In a named Java module, export or open the codec package to <code>org.apache.fory.json</code>. When an inherited |
| type-declaration codec is used for a more specific target, every decoded value must be null or |
| assignable to that target.</p> |
| <p>The annotation has the same FIELD, METHOD, and PARAMETER behavior on the JVM, Android, and GraalVM |
| Native Image. Ordinary Android classes may omit <code>JsonType</code> and provide equivalent exact rules. |
| Android-desugared Records, including <code>JsonValue</code> Records, require processor-generated operations |
| from either a direct <code>JsonType</code> declaration or a compiled exact <code>JsonMixin</code> pair. GraalVM object |
| models follow the build-time workflow in |
| <a class="" href=/docs/guide/java/graalvm_support>GraalVM Support</a>.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=type-validation-and-untrusted-input>Type validation and untrusted input<a href=#type-validation-and-untrusted-input class=hash-link aria-label="Direct link to Type validation and untrusted input" title="Direct link to Type validation and untrusted input" translate=no></a></h2> |
| <p>Fory JSON always applies its fixed disallow list. Add an application policy with:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token class-name">ForyJson</span><span class="token plain"> json </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">ForyJson</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withTypeChecker</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">className</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> context</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>-></span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> className</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>startsWith</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"com.example.model."</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token operator" style=color:#393A34>||</span><span class="token plain"> className</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>equals</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"java.util.List"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token operator" style=color:#393A34>||</span><span class="token plain"> className</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>equals</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"java.util.Map"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>Allow every application model and non-built-in container type that the declared schema uses. The |
| checker applies while application types are prepared for serialization and parsing and must be |
| thread-safe. Built-in scalars normally skip the custom checker, but selecting an application codec |
| for a built-in target makes that target subject to the checker. Custom codecs cannot bypass the |
| fixed disallow list.</p> |
| <p><code>withClassLoader</code> fixes subtype <code>className</code> resolution. Otherwise <code>build()</code> snapshots the thread |
| context class loader and falls back to the Fory JSON loader.</p> |
| <p><code>maxDepth</code> is not an input-size or memory quota. Enforce request size, timeout, and resource limits |
| at the transport boundary. <code>Class</code>, <code>URL</code>, <code>InetAddress</code>, and <code>InetSocketAddress</code> are unsupported by |
| default. URL and arbitrary unsupported Number/CharSequence subclasses require exact custom codecs.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=limits-and-unsupported-features>Limits and unsupported features<a href=#limits-and-unsupported-features class=hash-link aria-label="Direct link to Limits and unsupported features" title="Direct link to Limits and unsupported features" translate=no></a></h2> |
| <ul> |
| <li class="">No shared-reference identity or circular-reference protocol. Use Fory binary when needed.</li> |
| <li class="">No open polymorphism, JSON class-name IDs, subtype discovery, or runtime subtype-table extension.</li> |
| <li class="">No InputStream parser, incremental <code>OutputStream</code> writer on the <code>ForyJson</code> root API, or |
| pretty-print configuration.</li> |
| <li class="">No Jackson/Gson annotation compatibility.</li> |
| <li class="">No aliases, views, filters, injection, managed/back references, object identity annotations, root |
| wrapping, or format annotations.</li> |
| <li class="">Fory core's <code>Expose</code> is ignored.</li> |
| </ul> |
| <p>Circular graphs eventually fail <code>maxDepth</code>; they are not reconstructed.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=errors-and-troubleshooting>Errors and troubleshooting<a href=#errors-and-troubleshooting class=hash-link aria-label="Direct link to Errors and troubleshooting" title="Direct link to Errors and troubleshooting" translate=no></a></h2> |
| <table><thead><tr><th>Symptom<th>Action<tbody><tr><td><code>ForyJsonException</code><td>Check JSON grammar, target type, mapping support, depth, trailing content, or output cause<tr><td><code>InsecureException</code><td>Check Fory's disallow list and the configured type checker<tr><td>Builder <code>IllegalArgumentException</code><td>Check the configured depth, concurrency, retained-buffer, and cached-field-name limits<tr><td>Declared write fails<td>Remove wildcard/type variables and pass an assignable value; primitive declarations reject null<tr><td>Immutable value is empty<td>Use a record, valid creator, or custom codec<tr><td><code>JsonValue</code> read fails<td>Add one plain <code>String</code> creator, or register an exact custom codec<tr><td>Raw JSON output is invalid<td>Supply one trusted, complete JSON value to the <code>JsonRawValue</code> property<tr><td>Ordinary object cannot be created<td>Add a usable no-argument constructor, use a record or creator, or register a codec<tr><td>Ordinary accessor annotation fails<td>Use an eligible public JavaBean accessor and disable field mode<tr><td>Any annotation fails<td>Use one field form or one valid method pair with resolved <code>Map<String, V></code> types<tr><td>Codec annotation fails<td>Resolve same-node or hierarchy conflicts, hidden nested overrides, or codec constructor access<tr><td>Subtype fails<td>Write with the declared base, list the exact runtime class, and use the configured wire shape<tr><td>Collection fails<td>Target a supported interface/common implementation or register a codec</table> |
| <p>Creator failures other than <code>Error</code> are wrapped with their original cause. User codec code may |
| still throw its own runtime exceptions.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=related-java-guides>Related Java guides<a href=#related-java-guides class=hash-link aria-label="Direct link to Related Java guides" title="Direct link to Related Java guides" translate=no></a></h2> |
| <ul> |
| <li class=""><a class="" href=/docs/guide/java/>Java serialization overview</a></li> |
| <li class=""><a class="" href=/docs/guide/java/native_serialization>Native binary serialization</a></li> |
| <li class=""><a class="" href=/docs/guide/java/xlang_serialization>Xlang binary serialization</a></li> |
| <li class=""><a class="" href=/docs/guide/java/configuration>Java configuration</a></li> |
| <li class=""><a class="" href=/docs/guide/java/troubleshooting>Troubleshooting</a></li> |
| </ul></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href=https://github.com/apache/fory-site/tree/main/docs/guide/java/json-support.md target=_blank rel="noopener noreferrer" class=theme-edit-this-page><svg fill=currentColor height=20 width=20 viewBox="0 0 40 40" class=iconEdit_Z9Sw aria-hidden=true><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"/></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href=/docs/guide/java/troubleshooting><div class=pagination-nav__sublabel>Previous</div><div class=pagination-nav__label>Troubleshooting</div></a><a class="pagination-nav__link pagination-nav__link--next" href=/docs/guide/python/><div class=pagination-nav__sublabel>Next</div><div class=pagination-nav__label>Python Serialization Guide</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href=#requirements-and-installation class="table-of-contents__link toc-highlight">Requirements and installation</a><ul><li><a href=#jdk-25-and-later class="table-of-contents__link toc-highlight">JDK 25 and later</a></ul><li><a href=#quick-start class="table-of-contents__link toc-highlight">Quick start</a><li><a href=#reading-and-writing class="table-of-contents__link toc-highlight">Reading and writing</a><ul><li><a href=#generic-and-declared-types class="table-of-contents__link toc-highlight">Generic and declared types</a></ul><li><a href=#thread-safety-and-code-generation class="table-of-contents__link toc-highlight">Thread safety and code generation</a><li><a href=#object-mapping class="table-of-contents__link toc-highlight">Object mapping</a><li><a href=#supported-java-types class="table-of-contents__link toc-highlight">Supported Java types</a><ul><li><a href=#built-in-representations class="table-of-contents__link toc-highlight">Built-in representations</a><li><a href=#dynamic-json-trees class="table-of-contents__link toc-highlight">Dynamic JSON trees</a><li><a href=#map-keys class="table-of-contents__link toc-highlight">Map keys</a></ul><li><a href=#builder-configuration class="table-of-contents__link toc-highlight">Builder configuration</a><li><a href=#annotations class="table-of-contents__link toc-highlight">Annotations</a><ul><li><a href=#mixins class="table-of-contents__link toc-highlight">Mixins</a><li><a href=#jsonproperty class="table-of-contents__link toc-highlight"><code>JsonProperty</code></a><li><a href=#jsonpropertyorder class="table-of-contents__link toc-highlight"><code>JsonPropertyOrder</code></a><li><a href=#naming-strategy class="table-of-contents__link toc-highlight">Naming strategy</a><li><a href=#jsonignore class="table-of-contents__link toc-highlight"><code>JsonIgnore</code></a><li><a href=#jsonvalue class="table-of-contents__link toc-highlight"><code>JsonValue</code></a><li><a href=#jsonrawvalue class="table-of-contents__link toc-highlight"><code>JsonRawValue</code></a><li><a href=#jsonbase64 class="table-of-contents__link toc-highlight"><code>JsonBase64</code></a><li><a href=#jsonunwrapped class="table-of-contents__link toc-highlight"><code>JsonUnwrapped</code></a><li><a href=#dynamic-object-members class="table-of-contents__link toc-highlight">Dynamic object members</a><li><a href=#jsoncreator class="table-of-contents__link toc-highlight"><code>JsonCreator</code></a><li><a href=#jsonsubtypes class="table-of-contents__link toc-highlight"><code>JsonSubTypes</code></a></ul><li><a href=#custom-codecs class="table-of-contents__link toc-highlight">Custom codecs</a><ul><li><a href=#selecting-codecs-with-jsoncodec class="table-of-contents__link toc-highlight">Selecting codecs with <code>JsonCodec</code></a><li><a href=#codec-precedence-and-repeated-declarations class="table-of-contents__link toc-highlight">Codec precedence and repeated declarations</a><li><a href=#codec-construction-and-platform-support class="table-of-contents__link toc-highlight">Codec construction and platform support</a></ul><li><a href=#type-validation-and-untrusted-input class="table-of-contents__link toc-highlight">Type validation and untrusted input</a><li><a href=#limits-and-unsupported-features class="table-of-contents__link toc-highlight">Limits and unsupported features</a><li><a href=#errors-and-troubleshooting class="table-of-contents__link toc-highlight">Errors and troubleshooting</a><li><a href=#related-java-guides class="table-of-contents__link toc-highlight">Related Java guides</a></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Community</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://lists.apache.org/list.html?dev@fory.apache.org target=_blank rel="noopener noreferrer" class=footer__link-item>Mailing list<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://join.slack.com/t/fory-project/shared_invite/zt-1u8soj4qc-ieYEu7ciHOqA2mo47llS8A target=_blank rel="noopener noreferrer" class=footer__link-item>Slack<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://twitter.com/ApacheFory target=_blank rel="noopener noreferrer" class=footer__link-item>Twitter<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Docs</div><ul class="footer__items clean-list"><li class=footer__item><a class=footer__link-item href=/docs/start/install>Install</a><li class=footer__item><a class=footer__link-item href=/docs/start/usage>Usage</a><li class=footer__item><a class=footer__link-item href=/docs/introduction/benchmark>Benchmark</a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Repositories</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class=footer__link-item>Apache Fory™<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://github.com/apache/fory-site target=_blank rel="noopener noreferrer" class=footer__link-item>Website<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div></div><div class="footer__bottom text--center"><div class=margin-bottom--sm><a href=https://apache.org/ rel="noopener noreferrer" class=footerLogoLink_BH7S><img src=/img/asf_logo.svg alt="ASF Logo" class="footer__logo themedComponent_mlkZ themedComponent--light_NVdE" width=200 /><img src=/img/asf_logo.svg alt="ASF Logo" class="footer__logo themedComponent_mlkZ themedComponent--dark_xIcU" width=200 /></a></div><div class=footer__copyright><div> |
| <p> |
| Copyright © 2026 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. <br/> |
| Apache Fory, Fory, Apache, the Apache Logo and the Apache Fory logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. |
| </p> |
| </div></div></div></div></footer></div></body> |
