<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Serializing Custom Data — Sponge 5.0.0 documentation</title>
<link rel="stylesheet" href="../../../_static/basic.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/sponge.css" type="text/css" />
<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.1/css/font-awesome.min.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro|Roboto:400italic,700italic,700,400|Montserrat:400,700" rel="stylesheet" type="text/css" />
<link rel="stylesheet" href="../../../_static/tomorrow.css" type="text/css" />
<link id="syntax-highlighting-ref" rel="stylesheet" href="../../../_static/tomorrow_night.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../',
VERSION: '5.0.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<script type="text/javascript" src="../../../_static/store.min.js"></script>
<script type="text/javascript" src="../../../_static/lights.js"></script>
<link rel="shortcut icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="top" title="Sponge 5.0.0 documentation" href="../../../index.html" />
<link rel="up" title="Custom Data" href="index.html" />
<link rel="next" title="Using Keys" href="../keys.html" />
<link rel="prev" title="Custom DataHolders" href="dataholders.html" />
<script type="text/javascript">
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59476017-2', 'auto');
ga('send', 'pageview');
</script>
{§#curver§}
{|#langs|}
<link rel="alternate" hreflang="{|crowdin_code|}" href="/{§currentversion§}/{|crowdin_code|}/">
{|/langs|}
{§/curver§}
<link rel="alternate" hreflang="x-default" href="/">
</head>
<body role="document" id="top">
<div class="topbar">
<div role="navigation" aria-label="related navigation">
<div class="sp-logo-container sp-not-mobileview sp-mobileview">
<a class="sp-logo-link" data-auto-route="true" href="/">
<img height="40px" id="site-logo" class="logo-big" alt="" src="https://www.spongepowered.org/assets/img/icons/spongie-mark.svg">
<span id="sp-site-title">Sponge</span>
</a>
<div class="sp-logo-bg"></div>
<div class="sp-logo-chevron"><i class="fa fa-fw fa-chevron-down"></i></div>
<div class="sp-logo-menu sp-skip-handler">
<ul class="sp-logo-dropdown" id="ddleft">
<a href="https://www.spongepowered.org"><li><i class="fa-fw fa fa-home"></i>Homepage</li></a>
<a href="https://forums.spongepowered.org"><li><i class="fa-fw fa fa-comments"></i>Forums</li></a>
<a href="https://github.com/SpongePowered"><li><i class="fa-fw fa fa-code"></i>Code</li></a>
<a class="sp-forums-home" href="https://docs.spongepowered.org"><li class="active"><i class="fa-fw fa fa-book"></i>Docs</li></a>
<a href="https://jd.spongepowered.org"><li><i class="fa-fw fa fa-graduation-cap"></i>Javadocs</li></a>
<a href="https://forums.spongepowered.org/c/plugins/plugin-releases"><li><i class="fa-fw fa fa-plug"></i>Plugins</li></a>
<a href="https://www.spongepowered.org/downloads"><li><i class="fa-fw fa fa-download"></i>Downloads</li></a>
<a href="https://www.spongepowered.org/chat"><li><i class="fa-fw fa fa-comment"></i>Chat</li></a>
</ul>
</div>
</div>
<div class="menu-right">
<div><i class="fa fa-fw fa-globe"></i></div>
<ul class="dropdown" id="ddlang">
{§#curver§}
{|#langs|}
<li><a href="/{§currentversion§}/{|crowdin_code|}/" class="lang"><img src="//d1ztvzf22lmr1j.cloudfront.net/images/flags/{|crowdin_code|}.png" alt="Flag for {|name|}"/></a></li>
{|/langs|}
{§/curver§}
</ul>
</div>
<div class="menu-right">
<div><i class="fa fa-fw fa-tag"></i><a>5.0.0</a></div>
<ul class="dropdown" id="ddvers">
<li><a href="/master/en/"><i class="fa fa-fw fa-tag"></i> latest</a></li>
{[#vers]}
<li><a href="/{[apiversion]}/en/"><i class="fa fa-fw fa-tag"></i> {[apiversion]}</a></li>
{[/vers]}
</ul>
</div>
<div class="menu-right">
<div title="Toggle syntax highlighting between light and dark" class="lights">
<i class="fa fa-fw fa-lightbulb-o"></i>
</div>
</div>
<div>
<ul class="controls">
<li>|</li>
<li><a href="../keys.html" title="Next Page"><i class="fa fa-fw fa-chevron-right"></i></a></li>
<li><a href="#top" title="To the top"><i class="fa fa-fw fa-chevron-up"></i></a></li>
<li><a href="../../../index.html" title="Home"><i class="fa fa-fw fa-home"></i></a></li>
<li><a href="dataholders.html" title="Previous Page"><i class="fa fa-fw fa-chevron-left"></i></a></li>
<li>|</li>
<li><a href="https://github.com/SpongePowered/SpongeDocs/blob/master/source/plugin/data/custom/serialization.rst" title="Edit on GitHub"><i class="fa fa-fw fa-github"></i></a></li>
</ul>
</div>
<h3>Navigation</h3>
</div>
</div>
<div class="container">
<div class="breadcrumbs">
<ul>
<li><a href="../../../index.html">Sponge 5.0.0 documentation</a><i class="fa fa-fw fa-chevron-right"></i></li>
<li><a href="../../index.html" >Creating a Plugin</a><i class="fa fa-fw fa-chevron-right"></i></li>
<li><a href="../index.html" >The Data API</a><i class="fa fa-fw fa-chevron-right"></i></li>
<li><a href="index.html" accesskey="U">Custom Data</a><i class="fa fa-fw fa-chevron-right"></i></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="display: none" role="search">
<form class="search" action="../../../search.html" method="get">
<div class="searchbox-inner">
<input class="field" type="text" name="q" autocomplete="off" />
<button class="submit" type="submit"><i class="fa fa-fw fa-search" aria-hidden="true"></i></button>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</div>
</form>
<p class="searchtip" style="font-size: 90%"></p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script><h3><a href="../../../index.html">Table Of Contents</a></h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../server/index.html">Creating a Server</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../../server/getting-started/index.html">Getting Started</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../../server/getting-started/jre.html">Installing Java</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/getting-started/migrating.html">Migrating to Sponge</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/getting-started/implementations/index.html">Choosing an Implementation</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../../../server/getting-started/implementations/spongeforge.html">Installing SpongeForge</a></li>
<li class="toctree-l4"><a class="reference internal" href="../../../server/getting-started/implementations/spongevanilla.html">Installing SpongeVanilla</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/getting-started/launch-script.html">Creating a Launch Script</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/getting-started/port-forward.html">Port Forwarding</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/getting-started/bungeecord.html">Using Sponge with BungeeCord</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/getting-started/configuration/index.html">Configuring Sponge</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../../../server/getting-started/configuration/hocon.html">Introduction to HOCON</a></li>
<li class="toctree-l4"><a class="reference internal" href="../../../server/getting-started/configuration/json.html">JSON Syntax</a></li>
<li class="toctree-l4"><a class="reference internal" href="../../../server/getting-started/configuration/sponge-conf.html">global.conf</a></li>
<li class="toctree-l4"><a class="reference internal" href="../../../server/getting-started/configuration/server-properties.html">server.properties</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../../server/management/index.html">Server Management</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../../server/management/whitelist.html">Managing the Whitelist</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/management/bans.html">Managing Bans</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/management/permissions.html">Managing Permissions</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/management/plugins.html">Installing Plugins</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/management/exploit-patches.html">Exploit Patches</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/management/performance-tweaks.html">Performance Tweaks</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../../server/spongineer/index.html">Becoming an Expert Spongineer</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../../server/spongineer/commands.html">Commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/spongineer/troubleshooting.html">Troubleshooting</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/spongineer/logs.html">Log Files</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/spongineer/debugging.html">Debugging</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../server/spongineer/bugreport.html">Reporting Bugs</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../preparing/index.html">Preparing for Development</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../../preparing/jdk.html">Installing the JDK</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../preparing/ide.html">Installing an IDE</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../preparing/text.html">Installing a Text Editor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../preparing/git.html">Installing Git</a></li>
</ul>
</li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Creating a Plugin</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../buildsystem.html">Build Systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../workspace/index.html">Setting Up Your Workspace</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../workspace/idea.html">Setting Up IntelliJ IDEA</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../workspace/eclipse.html">Setting Up Eclipse</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../project/index.html">Setting Up Your Project</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../project/gradle.html">Setting Up Gradle</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../project/maven.html">Setting Up Maven</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../plugin-identifier.html">Plugin Identifiers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../plugin-class.html">Main Plugin Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../lifecycle.html">Plugin Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../injection.html">Dependency Injection</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../practices.html">Best Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../optional/index.html">Optionals</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../optional/basic.html">Optionals Explained</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../optional/usage.html">Usage Examples</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../logging.html">Logging and Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../commands/index.html">Commands</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../commands/creating.html">Building a Command</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../commands/arguments.html">Argument Parsing</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../commands/flags.html">Command Flags</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../commands/childcommands.html">Child Commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../commands/service.html">The Command Manager</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../commands/commandcallable.html">Low-Level Command API</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../event/index.html">Events</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../event/listeners.html">Event Listeners</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../event/causes.html">Event Causes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../event/filters.html">Event Filters</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../event/custom.html">Custom Events</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../assets.html">The Asset API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../configuration/index.html">Configuring Plugins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../configuration/loaders.html">Configuration Loaders</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../configuration/nodes.html">Configuration Nodes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../configuration/serialization.html">Serializing Objects</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../text/index.html">Text</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../text/text.html">Creating Text</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../text/representations/index.html">Text Serializers</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../../text/representations/formatting-code-legacy.html">Formatting Code & Legacy Format</a></li>
<li class="toctree-l4"><a class="reference internal" href="../../text/representations/xml.html">TextXML Format</a></li>
<li class="toctree-l4"><a class="reference internal" href="../../text/representations/json.html">JSON Format</a></li>
<li class="toctree-l4"><a class="reference internal" href="../../text/representations/configurate.html">Configuration Format</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../../text/pagination.html">The Pagination Service</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../text/messagechannels.html">Message Channels</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../text/templates.html">TextTemplates</a></li>
</ul>
</li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">The Data API</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="index.html">Custom Data</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="datamanipulators.html">Custom DataManipulators</a></li>
<li class="toctree-l4"><a class="reference internal" href="dataholders.html">Custom DataHolders</a></li>
<li class="toctree-l4 current"><a class="current reference internal" href="#">Serializing Custom Data</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../keys.html">Using Keys</a></li>
<li class="toctree-l3"><a class="reference internal" href="../datamanipulators.html">Data Manipulators</a></li>
<li class="toctree-l3"><a class="reference internal" href="../transactions.html">Transactions</a></li>
<li class="toctree-l3"><a class="reference internal" href="../serialization.html">Serializing Data</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../blocks/index.html">Blocks</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../blocks/concepts.html">Concepts</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../blocks/accessing.html">Accessing Blocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../blocks/modifying.html">Modifying Blocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../blocks/tileentities.html">Tile Entities</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../blocks/virtualblock.html">Virtual Block Changes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../entities/index.html">Entities</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../entities/spawning.html">Spawning an Entity</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../entities/modifying.html">Modifying an Entity</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../items/index.html">Items</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../items/usage.html">Basic Item Usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../items/creating.html">Creating an ItemStack</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../trade-offers.html">Trade-Offers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../effects.html">Effects</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../scheduler.html">Scheduler</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../services.html">Services</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../database.html">Databases</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../permissions.html">Permissions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../bans.html">Bans</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../bookview.html">Book Views</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../economy/index.html">Economy</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../economy/basics.html">Basic Concepts</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../economy/using.html">Using the Economy API</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../economy/practices.html">Economy API Best Practices</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../economy/implementing.html">Implementing the Economy API</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../wgen/index.html">World Generation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../wgen/modifiers.html">WorldGeneratorModifiers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../wgen/customwgen.html">Modifying World Generation</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../manager.html">Plugin Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../game-profile-manager.html">Game Profile Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../offline-userplayer-data.html">Offline Player Data</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../debugging.html">Plugin Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../tab-lists.html">Tab Lists</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../plugin-meta.html">Plugin Metadata</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../ray-tracing.html">Ray Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../ore/index.html">Ore Documentation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../../ore/publish.html">Publishing Your Plugin</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../ore/security.html">Security</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../ore/api.html">Ore Web API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../../ore/routes/list-projects.html">List projects</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../ore/routes/project.html">Get Project</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../ore/routes/list-versions.html">List Project Versions</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../ore/routes/project-version.html">Get Project Version</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../ore/routes/list-users.html">List Users</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../ore/routes/user.html">Get User</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../ore/routes/download.html">Download Project Version</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../contributing/index.html">Contributing to Sponge</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../../contributing/guidelines.html">Contribution Guidelines</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../contributing/howtogit.html">How to Git(Hub)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../contributing/implementation/index.html">Developing Sponge</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../../../contributing/implementation/codestyle.html">Code Style</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../contributing/implementation/git-implementation.html">Git Workflow for API and Implementations</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../contributing/implementation/pr.html">Submitting a Pull-Request</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../contributing/implementation/debugging.html">Debugging Sponge Within the IDE</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../contributing/implementation/mixins.html">Mixins</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../contributing/implementation/datamanipulator.html">Implementing DataManipulators</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../../contributing/spongedocs.html">SpongeDocs Writing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../contributing/porting.html">Porting Sponge to Other Platforms</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../contributing/versioning.html">Versioning System and Repository Branch Layout</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../about/index.html">About the Sponge Project</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../../about/introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/structure.html">The Structure of the Sponge Project</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/future.html">Plans for the Future</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/license.html">License</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/posting.html">Forum Posting Guidelines</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/rules.html">Forum & IRC Rules</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/staff.html">Staff</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/glossary.html">Sponge Glossary</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/assets.html">Art Assets</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../about/history.html">The History of Sponge</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="serializing-custom-data">
<h1>Serializing Custom Data<a class="headerlink" href="#serializing-custom-data" title="Permalink to this headline">¶</a></h1>
<p>Without a method serializing and deserializng, your data will not persist across restarts. Sponge has a few different
ways to serialize/deserialize data based on the type of data:</p>
<ul class="simple">
<li><a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/serialization/DataSerializable.html">DataSerializable</a>s implement an interface to perform serialization, and use <a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/persistence/DataBuilder.html">DataBuilder</a> for
deserialization and creation</li>
<li><a class="reference internal" href="../datamanipulators.html"><span class="doc">DataManipulators</span></a> also implement <code class="docutils literal"><span class="pre">DataSerializable</span></code>, but instead use a
<a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/persistence/DataManipulatorBuilder.html">DataManipulatorBuilder</a> for deserialization and creation</li>
<li>Objects that do not or cannot implement <code class="docutils literal"><span class="pre">DataSerializable</span></code> use <a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/persistence/DataTranslator.html">DataTranslator</a> for both serialization
and deserialization</li>
</ul>
<p>This means that practically any object in Java can be saved to disk if it has been registered!</p>
<div class="section" id="reading-dataviews">
<h2>Reading DataViews<a class="headerlink" href="#reading-dataviews" title="Permalink to this headline">¶</a></h2>
<p>Whenever you’re reading a serialized object, it’s tempting to read all the individual values yourself in order to
manually create all the required objects (and their parameters) for your data. However, depending on the data saved in
the container there are a few ways ways that are far more convenient:</p>
<ul class="simple">
<li>Common java types such as <code class="docutils literal"><span class="pre">int</span></code>, <code class="docutils literal"><span class="pre">String</span></code>, <code class="docutils literal"><span class="pre">double</span></code>, <code class="docutils literal"><span class="pre">List</span></code> and <code class="docutils literal"><span class="pre">Map</span></code> can be retrieved using built-in
methods <code class="docutils literal"><span class="pre">getInt(DataQuery)</span></code>, <code class="docutils literal"><span class="pre">getString(DataQuery)</span></code>, etc. Lists of these types can also be retrieved in a
similar fashion, for example <code class="docutils literal"><span class="pre">getStringList(DataQuery)</span></code>.</li>
<li><code class="docutils literal"><span class="pre">DataSerializable</span></code> objects can be retrieved using <code class="docutils literal"><span class="pre">getSerializable(DataQuery,</span> <span class="pre">Class)</span></code> or
<code class="docutils literal"><span class="pre">getSerializableList(DataQuery,</span> <span class="pre">Class)</span></code>. Along with the path, you must also specify the <code class="docutils literal"><span class="pre">Class</span></code> of the
serializable type, such as <code class="docutils literal"><span class="pre">Home.class</span></code>.</li>
<li>Objects with a registered <code class="docutils literal"><span class="pre">DataTranslator</span></code> can be retrieved using <code class="docutils literal"><span class="pre">getObject(DataQuery,</span> <span class="pre">Class)</span></code> or
<code class="docutils literal"><span class="pre">getObjectList(DataQuery,</span> <span class="pre">Class)</span></code>. A full list of classes that are supported by default can be found in
<a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/persistence/DataTranslators.html">DataTranslators</a>.</li>
</ul>
<p>In all cases you need to specify a path using a <a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/DataQuery.html">DataQuery</a>. If your data has a corresponding <code class="docutils literal"><span class="pre">Key</span></code> this is
as easy as calling <code class="docutils literal"><span class="pre">key.getQuery()</span></code>. Otherwise, the easiest way to do this is with <code class="docutils literal"><span class="pre">DataQuery.of("name")</span></code>.</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">DataQueries can be used to reference data multiple nodes down a tree by using, for example,
<code class="docutils literal"><span class="pre">DataQuery.of("my",</span> <span class="pre">"custom",</span> <span class="pre">"data")</span></code>.</p>
</div>
</div>
<div class="section" id="databuilders">
<span id="custom-data-builders"></span><h2>DataBuilders<a class="headerlink" href="#databuilders" title="Permalink to this headline">¶</a></h2>
<p>To make an object serializable, first ensure that it implements <a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/serialization/DataSerializable.html">DataSerializable</a>. You must implement just
two methods:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">getContentVersion()</span></code> - this defined the current version of your data.</li>
<li><code class="docutils literal"><span class="pre">toContainer()</span></code> - this is what your builder will be given when attempting to deserialize and object. You can store
whatever you want in the returned <code class="docutils literal"><span class="pre">DataContainer</span></code>, so long as it is also serializable using one of the methods
above. Just use the <code class="docutils literal"><span class="pre">set(DataQuery,</span> <span class="pre">Object)</span></code> method to save your data to the given path.</li>
</ul>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">It is recommended that you save the version of your data to the container as well using <code class="docutils literal"><span class="pre">Queries.CONTENT_VERSION</span></code>
as the query. This will allow for versioning upgrades with <a class="reference internal" href="#content-updaters"><span class="std std-ref">DataContentUpdaters</span></a>.</p>
</div>
<p><strong>Code Example: Implementing toContainer</strong></p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">org.spongepowered.api.data.DataContainer</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.data.DataQuery</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.data.Queries</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.data.MemoryDataContainer</span><span class="o">;</span>
<span class="n">String</span> <span class="n">name</span> <span class="o">=</span> <span class="s">"Spongie"</span><span class="o">;</span>
<span class="nd">@Override</span>
<span class="kd">public</span> <span class="n">DataContainer</span> <span class="nf">toContainer</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="k">new</span> <span class="n">MemoryDataContainer</span><span class="o">()</span>
<span class="o">.</span><span class="na">set</span><span class="o">(</span><span class="n">DataQuery</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"Name"</span><span class="o">),</span> <span class="k">this</span><span class="o">.</span><span class="na">name</span><span class="o">)</span>
<span class="o">.</span><span class="na">set</span><span class="o">(</span><span class="n">Queries</span><span class="o">.</span><span class="na">CONTENT_VERSION</span><span class="o">,</span> <span class="n">getContentVersion</span><span class="o">());</span>
<span class="o">}</span>
</pre></div>
</div>
<p>The next part is to implement a <a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/persistence/DataBuilder.html">DataBuilder</a>. It’s recommended to extend <a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/persistence/AbstractDataBuilder.html">AbstractDataBuilder</a> as
it will try to upgrade your data if the version is less than the current version. There’s only one method you need to
implement - <code class="docutils literal"><span class="pre">build(DataView)</span></code>, or <code class="docutils literal"><span class="pre">buildContent(DataView)</span></code> if you’re using <code class="docutils literal"><span class="pre">AbstractDataBuilder</span></code>.</p>
<p>You’ll want to check that all the queries you want to retrieve are present using <code class="docutils literal"><span class="pre">DataView.contains(Key...)</span></code>. If not
the data is likely incomplete and you should return <code class="docutils literal"><span class="pre">Optional.empty()</span></code>.</p>
<p>If everything seems to be there, use the <code class="docutils literal"><span class="pre">getX</span></code> methods to construct the values and return a newly created object as
an <code class="docutils literal"><span class="pre">Optional</span></code>.</p>
<p>Finally, you need to register this builder so that it can be found by plugins. To do this, simply call
<code class="docutils literal"><span class="pre">DataManager#registerDataBuilder(Class,</span> <span class="pre">DataBuilder)</span></code> referencing the data class and an instance of the builder.</p>
</div>
<div class="section" id="datacontentupdaters">
<span id="content-updaters"></span><h2>DataContentUpdaters<a class="headerlink" href="#datacontentupdaters" title="Permalink to this headline">¶</a></h2>
<p>What happens if you change the layout of data in a new version release? <a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/persistence/DataContentUpdater.html">DataContentUpdater</a>s solve that
problem. If the serialized object is less than the current version, an <code class="docutils literal"><span class="pre">AbstractDataBuilder</span></code> will try and update the
data before passing it to the builder.</p>
<p>Each updater has an input version and an output version. You should take in the old data and change whatever is needed
to upgrade it to a newer layout. If it’s impossible to convert due to missing data, it may be possible instead to
provide a default value which is interpreted elsewhere - such as by the main builder or the object itself.</p>
<p>Finally, you must ensure that all <code class="docutils literal"><span class="pre">DataContentUpdater</span></code>s are registerered with
<code class="docutils literal"><span class="pre">DataManager#registerContentUpdater()</span></code> referencing the main data class - this will allow them to be discovered by
the builder.</p>
<p><strong>Code Example: Implenting a DataContentUpdater</strong></p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="n">org</span><span class="o">.</span><span class="na">spongepowered</span><span class="o">.</span><span class="na">api</span><span class="o">.</span><span class="na">data</span><span class="o">.</span><span class="na">persistence</span><span class="o">.</span><span class="na">DataContentUpdater</span>
<span class="n">org</span><span class="o">.</span><span class="na">spongepowered</span><span class="o">.</span><span class="na">api</span><span class="o">.</span><span class="na">text</span><span class="o">.</span><span class="na">Text</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">NameUpdater</span> <span class="kd">implements</span> <span class="n">DataContentUpdater</span> <span class="o">{</span>
<span class="nd">@Override</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="nf">getInputVersion</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="mi">1</span><span class="o">;</span>
<span class="o">}</span>
<span class="nd">@Override</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="nf">getOutputVersion</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="mi">2</span><span class="o">;</span>
<span class="o">}</span>
<span class="nd">@Override</span>
<span class="kd">public</span> <span class="n">DataView</span> <span class="nf">update</span><span class="o">(</span><span class="n">DataView</span> <span class="n">content</span><span class="o">)</span> <span class="o">{</span>
<span class="n">String</span> <span class="n">name</span> <span class="o">=</span> <span class="n">content</span><span class="o">.</span><span class="na">getString</span><span class="o">(</span><span class="n">DataQuery</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"Name"</span><span class="o">)).</span><span class="na">get</span><span class="o">();</span>
<span class="c1">// For example, version 2 uses a text for the name</span>
<span class="k">return</span> <span class="n">content</span><span class="o">.</span><span class="na">set</span><span class="o">(</span><span class="n">DataQuery</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"Name"</span><span class="o">),</span> <span class="n">Text</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">name</span><span class="o">));</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="datamanipulatorbuilders">
<h2>DataManipulatorBuilders<a class="headerlink" href="#datamanipulatorbuilders" title="Permalink to this headline">¶</a></h2>
<p>A <code class="docutils literal"><span class="pre">DataManipualatorBuilder</span></code> is very similar to <code class="docutils literal"><span class="pre">DataBuilder</span></code>, however it adds a few methods directly related to
deserializing manipulators:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">create()</span></code> should return a new manipulator with default values</li>
<li><code class="docutils literal"><span class="pre">createFrom(DataHolder)</span></code> is similar to the build method, but instead the values should be taken from the
<a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/DataHolder.html">DataHolder</a>. If there is no data to be taken from the holder, just return the output of <code class="docutils literal"><span class="pre">create()</span></code>. If
the data is incompatible with the <code class="docutils literal"><span class="pre">DataHolder</span></code>, you should instead return <code class="docutils literal"><span class="pre">Optional.empty()</span></code>.</li>
</ul>
<p>Just like <code class="docutils literal"><span class="pre">DataBuilder</span></code>, you should read and return your manipulator in the relevant <code class="docutils literal"><span class="pre">build</span></code> method.</p>
<p><code class="docutils literal"><span class="pre">DataManipulatorBuilder</span></code>s can make use of <a class="reference internal" href="#content-updaters"><span class="std std-ref">DataContentUpdaters</span></a> as well, as long as you implement
<code class="docutils literal"><span class="pre">AbstractDataBuilder</span></code>.</p>
<p>Registering a <code class="docutils literal"><span class="pre">DataManipulatorBuilder</span></code> is also similar to <code class="docutils literal"><span class="pre">DataBuilder</span></code> but uses the <code class="docutils literal"><span class="pre">register()</span></code> method. You
must reference both your mutable and immutable classes in the method, in addition to an instance of your builder.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You <strong>must</strong> reference the implementation classes if you have split the API from the implementaton.</p>
</div>
</div>
<div class="section" id="datatranslators">
<h2>DataTranslators<a class="headerlink" href="#datatranslators" title="Permalink to this headline">¶</a></h2>
<p>Often the objects you want to serialize are not objects that implement <code class="docutils literal"><span class="pre">DataSerializable</span></code>, such as <code class="docutils literal"><span class="pre">Vector3d</span></code> or
<code class="docutils literal"><span class="pre">Date</span></code>. To allow these objects you implelement a <a class="reference external" href="https://jd.spongepowered.org/5.0.0/org/spongepowered/api/data/persistence/DataTranslator.html">DataTranslator</a> which handles <em>both</em> the serialization
and deserialization of the object.</p>
<p>The implementation of <code class="docutils literal"><span class="pre">translate</span></code> is identical to <code class="docutils literal"><span class="pre">toContainer()</span></code> and <code class="docutils literal"><span class="pre">build(DataView)</span></code> for a
<code class="docutils literal"><span class="pre">DataSerializable</span></code> as shown above, except that an <code class="docutils literal"><span class="pre">InvalidDataException</span></code> is thrown if data is missing in place of
returning an <code class="docutils literal"><span class="pre">Optional</span></code>.</p>
<p>As with other data, ensure that you register the translator with
<code class="docutils literal"><span class="pre">DataManager#registerTranslator(Class,</span> <span class="pre">DataTranslator)</span></code>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer" role="contentinfo">
© Copyright 2014-2016, Sponge Contributors.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.1.
</div>
</div>
</body>
</html>