<!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>Optionals Explained — 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="Optionals" href="index.html" />
<link rel="next" title="Usage Examples" href="usage.html" />
<link rel="prev" title="Optionals" href="index.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="usage.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="index.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/optional/basic.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" accesskey="U">Optionals</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 current"><a class="reference internal" href="index.html">Optionals</a><ul class="current">
<li class="toctree-l3 current"><a class="current reference internal" href="#">Optionals Explained</a></li>
<li class="toctree-l3"><a class="reference internal" href="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"><a class="reference internal" href="../data/index.html">The Data API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../data/custom/index.html">Custom Data</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../data/custom/datamanipulators.html">Custom DataManipulators</a></li>
<li class="toctree-l4"><a class="reference internal" href="../data/custom/dataholders.html">Custom DataHolders</a></li>
<li class="toctree-l4"><a class="reference internal" href="../data/custom/serialization.html">Serializing Custom Data</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../data/keys.html">Using Keys</a></li>
<li class="toctree-l3"><a class="reference internal" href="../data/datamanipulators.html">Data Manipulators</a></li>
<li class="toctree-l3"><a class="reference internal" href="../data/transactions.html">Transactions</a></li>
<li class="toctree-l3"><a class="reference internal" href="../data/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="optionals-explained">
<h1>Optionals Explained<a class="headerlink" href="#optionals-explained" title="Permalink to this headline">¶</a></h1>
<p>Much of the Sponge API makes use of Java’s <cite>Optional</cite> system on object accessors, but if you’ve never used <code class="docutils literal"><span class="pre">Optional</span></code>
before this might seem like a bit of a peculiar way of doing things. You might be tempted to ask:
<em>“why do I need to perform an extra step when fetching something from an API object?”</em></p>
<p>This section gives a brief summary of <code class="docutils literal"><span class="pre">Optional</span></code> and explains how - and perhaps more importantly why -
it’s used throughout the Sponge API.</p>
<p>Let’s start with a little history, and look at how accessors - particularly “getters” - typically work when not making
use of <code class="docutils literal"><span class="pre">Optional</span></code>.</p>
<div class="section" id="implicit-nullable-contracts-and-why-they-suck">
<h2>1. Implicit Nullable Contracts and Why They Suck<a class="headerlink" href="#implicit-nullable-contracts-and-why-they-suck" title="Permalink to this headline">¶</a></h2>
<p>Let’s say we have a simple API object <code class="docutils literal"><span class="pre">Entity</span></code> with a <code class="docutils literal"><span class="pre">getFoo()</span></code> method which returns the Entity’s <code class="docutils literal"><span class="pre">Foo</span></code>.</p>
<img alt="../../_images/optionals1.png" src="../../_images/optionals1.png" />
<p>In the olden times of yore, our plugin might fetch and use the <code class="docutils literal"><span class="pre">Foo</span></code> from the entity using the <code class="docutils literal"><span class="pre">getter</span></code> like this:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kt">void</span> <span class="nf">someEventHandler</span><span class="o">(</span><span class="n">Entity</span> <span class="n">someEntity</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Foo</span> <span class="n">entityFoo</span> <span class="o">=</span> <span class="n">someEntity</span><span class="o">.</span><span class="na">getFoo</span><span class="o">();</span>
<span class="n">entityFoo</span><span class="o">.</span><span class="na">bar</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
<p>The problem arises because - when designing the API - we have to rely an <em>implicit</em> contract on the <code class="docutils literal"><span class="pre">getFoo</span></code> method
with respect to whether the method can (or cannot) return <code class="docutils literal"><span class="pre">null</span></code>. This <em>implicit contract</em> can be defined in one of
two ways:</p>
<ul class="simple">
<li><strong>In the javadoc</strong> - this is bad because it relies on the plugin author reading the javadoc for the method, and the contract may not be clear to the plugin author</li>
<li><strong>Using nullable annotations</strong> - this is not ideal because in general these annotations require a tool to be of any use, for example relying on the IDE or compiler to handle the annotations.</li>
</ul>
<img alt="../../_images/optionals2.png" src="../../_images/optionals2.png" />
<p>Let’s assume that the <code class="docutils literal"><span class="pre">getFoo()</span></code> method can - as part of its contract - return null. This suddenly means that our
code above is unsafe as it may result in a <code class="docutils literal"><span class="pre">NullPointerException</span></code> if <code class="docutils literal"><span class="pre">entityFoo</span></code> is null.</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kt">void</span> <span class="nf">someEventHandler</span><span class="o">(</span><span class="n">Entity</span> <span class="n">someEntity</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Foo</span> <span class="n">entityFoo</span> <span class="o">=</span> <span class="n">someEntity</span><span class="o">.</span><span class="na">getFoo</span><span class="o">();</span>
<span class="n">entityFoo</span><span class="o">.</span><span class="na">bar</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Let’s assume our plugin author is savvy to the nullable nature of our <code class="docutils literal"><span class="pre">getFoo</span></code> method and decides to fix the problem
with null checking. Assuming they have defined a local constant <code class="docutils literal"><span class="pre">Foo</span></code>, the resultant code looks like this:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kt">void</span> <span class="nf">someEventHandler</span><span class="o">(</span><span class="n">Entity</span> <span class="n">someEntity</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Foo</span> <span class="n">entityFoo</span> <span class="o">=</span> <span class="n">someEntity</span><span class="o">.</span><span class="na">getFoo</span><span class="o">();</span>
<span class="k">if</span> <span class="o">(</span><span class="n">entityFoo</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
<span class="n">entityFoo</span> <span class="o">=</span> <span class="n">MyPlugin</span><span class="o">.</span><span class="na">DEFAULT_FOO</span><span class="o">;</span>
<span class="o">}</span>
<span class="n">entityFoo</span><span class="o">.</span><span class="na">bar</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
<p>In this example, the plugin author is aware that the method can return null and has a constant available with a
default instance of <code class="docutils literal"><span class="pre">Foo</span></code> which can be used instead. Of course the plugin could just short-circuit the call entirely,
or it could attempt to fetch <cite>Foo</cite> from somewhere else. The key message is that handling nulls even in simple cases
can lead to spaghetti code quite quickly, and moreover relies on the plugin author to explicitly visit the method’s
contract to check whether a null check is necessary in the first place.</p>
<p>That’s not the only drawback however. Let’s consider the API over the longer term and assume that at the time the author
writes their plugin, they visit the method javadoc and see that the method is guaranteed to never return null
(since every <cite>Entity</cite> always has a <code class="docutils literal"><span class="pre">Foo</span></code> available). Great! No convoluted null check required!</p>
<p>However, let’s now assume that in a later version of the game, the game developers remove or deprecate the concept of
<code class="docutils literal"><span class="pre">Foo</span></code>. The API authors update the API accordingly and state that from now on the <code class="docutils literal"><span class="pre">getFoo()</span></code> method
<strong>can</strong> return <code class="docutils literal"><span class="pre">null</span></code> and write this into the method javadoc. Now there’s a problem: even diligent plugin authors who
checked the method contract when they first wrote their code are unwittingly handling the method incorrectly: with no
null check in place any code using the <code class="docutils literal"><span class="pre">Foo</span></code> returned from <code class="docutils literal"><span class="pre">getFoo</span></code> is going to raise an NPE.</p>
<p>Thus we can see that allowing implicit nullable contracts leaves us with a selection of pretty awful solutions to
choose from:</p>
<ul class="simple">
<li>Plugin authors can assume that <strong>all</strong> methods may return null and code defensively accordingly, however we’ve already seen that this leads to spaghetti code pretty quickly.</li>
<li>The API authors can define an implicit nullable contract on every API method, in an attempt to make null handling the plugin author’s problem, which only exacerbates the previous problem.</li>
<li>The API authors can assert that any implicit nullable contract they define will never be altered going forward. This means that in the eventuality that they need to handle the removal of a feature from the base game then they must either:</li>
</ul>
<blockquote>
<div><ul class="simple">
<li>Throw an exception - hardly elegant but certainly easier to diagnose than a loose NPE which may be triggered elsewhere in the codebase and be hard to track down</li>
<li>Return a “fake” object or invalid value - this means that consuming (plugin) code will continue to work, but creates an ever-increasing burden on the API developers going forward since every deprecated feature will require the creation of yet more fake objects. This could soon lead to the situation where a big chunk of the API is filled with junk objects whose only purpose is to support parts of the API which are no longer in service.</li>
</ul>
</div></blockquote>
<p>It should be pretty clear by now that there are some sizable headaches attached to <em>implicit</em> nullable contracts, made
all the more poignant when the API in question is a layer over an extremely unstable base product. Fortunately,
there is a better way:</p>
</div>
<div class="section" id="optional-and-the-explicit-nullable-contract">
<h2>2. Optional and the Explicit Nullable Contract<a class="headerlink" href="#optional-and-the-explicit-nullable-contract" title="Permalink to this headline">¶</a></h2>
<p>As mentioned above, APIs for Minecraft are in a difficult situation. Ultimately they need to provide a platform with
a <em>reasonable amount of implied stability</em> atop a platform (the game) with <em>absolutely no amount of implied stability</em>.
Thus any API for Minecraft needs to be designed with full awareness that any aspect of the game is liable to change at
any time for any reason in any way imaginable; up to and including being removed altogether!</p>
<p>This volatility is what leads to the problem with nullable method contracts described above.</p>
<p><cite>Optional</cite> solves the above problems by replacing <em>implicit contracts</em> with <em>explicit</em> ones. The API never advertises,
<em>“here is your object, kthxbai”</em>, instead it presents accessors with a
<em>“here is a box which may or may not contain the object you asked for, ymmv”</em>.</p>
<img alt="../../_images/optionals3.png" src="../../_images/optionals3.png" />
<p>By encoding the possibility of returning <code class="docutils literal"><span class="pre">null</span></code> into an explicit contract, we replace the concept of
<em>null checking</em> with the more nuanced concept of <em>may not exist</em>. We also stipulate this contract <em>from day one</em>.</p>
<p>So what does this mean?</p>
<p>In a nutshell, no longer do plugin authors have to worry about the possibility of <code class="docutils literal"><span class="pre">null</span></code> being returned. Instead the
very possibility of a particular object not being available becomes encoded in the very fabric of their plugin code.
This has the same level of inherent safety as constantly performing null-checks, but with the benefit of much more
elegant and readable code in order to do so.</p>
<p>To see why, let’s take a look at the above example, converted to use a <code class="docutils literal"><span class="pre">getFoo</span></code> method which returns
<code class="docutils literal"><span class="pre">Optional<Foo></span></code> instead:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kt">void</span> <span class="nf">someEventHandler</span><span class="o">(</span><span class="n">Entity</span> <span class="n">someEntity</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Optional</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="n">entityFoo</span> <span class="o">=</span> <span class="n">someEntity</span><span class="o">.</span><span class="na">getFoo</span><span class="o">();</span>
<span class="k">if</span> <span class="o">(</span><span class="n">entityFoo</span><span class="o">.</span><span class="na">isPresent</span><span class="o">())</span> <span class="o">{</span>
<span class="n">entityFoo</span><span class="o">.</span><span class="na">get</span><span class="o">().</span><span class="na">bar</span><span class="o">();</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>You may note that this example looks very much like a standard null-check, however the use of <code class="docutils literal"><span class="pre">Optional</span></code> actually
carries a little more information in the same amount of code. For example, it is not necessary for someone reading
the above code to check the method contract, it is clear that the method may not return a value, and the handling
of the value’s absence is explicit and clear.</p>
<p>So what? Our explicit contract in this case results in basically the same amount of code as a null check - albeit
one that is contractually <em>enforced</em> by the getter. <em>“Whoop de do,”</em> you say, <em>“so what?”</em></p>
<p>Well the <cite>Optional</cite> boxing allows us to take some of the traditionally more awkward aspects of null-checking and
make them more elegant: consider the following code:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kt">void</span> <span class="nf">someEventHandler</span><span class="o">(</span><span class="n">Entity</span> <span class="n">someEntity</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Foo</span> <span class="n">entityFoo</span> <span class="o">=</span> <span class="n">someEntity</span><span class="o">.</span><span class="na">getFoo</span><span class="o">().</span><span class="na">orElse</span><span class="o">(</span><span class="n">MyPlugin</span><span class="o">.</span><span class="na">DEFAULT_FOO</span><span class="o">);</span>
<span class="n">entityFoo</span><span class="o">.</span><span class="na">bar</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Hold the phone! Did we just replace the tedious null-check-and-default-assignment from the example above with a
single line of code? Yes indeed we did. In fact, for simple use cases we can even dispense with the assignment:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kt">void</span> <span class="nf">someEventHandler</span><span class="o">(</span><span class="n">Entity</span> <span class="n">someEntity</span><span class="o">)</span> <span class="o">{</span>
<span class="n">someEntity</span><span class="o">.</span><span class="na">getFoo</span><span class="o">().</span><span class="na">orElse</span><span class="o">(</span><span class="n">MyPlugin</span><span class="o">.</span><span class="na">DEFAULT_FOO</span><span class="o">).</span><span class="na">bar</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
<p>This is perfectly safe provided that <code class="docutils literal"><span class="pre">MyPlugin.DEFAULT_FOO</span></code> is always available.</p>
<p>Consider the following example with two entities, using an implicit nullable contract we want to use <code class="docutils literal"><span class="pre">Foo</span></code> from the
first entity, or if not available use <code class="docutils literal"><span class="pre">Foo</span></code> from the second <code class="docutils literal"><span class="pre">entity</span></code>, and fall back on our default if neither is
available:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kt">void</span> <span class="nf">someEventHandler</span><span class="o">(</span><span class="n">Entity</span> <span class="n">someEntity</span><span class="o">,</span> <span class="n">Entity</span> <span class="n">entity2</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Foo</span> <span class="n">entityFoo</span> <span class="o">=</span> <span class="n">someEntity</span><span class="o">.</span><span class="na">getFoo</span><span class="o">();</span>
<span class="k">if</span> <span class="o">(</span><span class="n">entityFoo</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
<span class="n">entityFoo</span> <span class="o">=</span> <span class="n">entity2</span><span class="o">.</span><span class="na">getFoo</span><span class="o">();</span>
<span class="o">}</span>
<span class="k">if</span> <span class="o">(</span><span class="n">entityFoo</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
<span class="n">entityFoo</span> <span class="o">=</span> <span class="n">MyPlugin</span><span class="o">.</span><span class="na">DEFAULT_FOO</span><span class="o">;</span>
<span class="o">}</span>
<span class="n">entityFoo</span><span class="o">.</span><span class="na">bar</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Using <code class="docutils literal"><span class="pre">Optional</span></code> we can encode this much much more cleanly as:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kt">void</span> <span class="nf">someEventHandler</span><span class="o">(</span><span class="n">Entity</span> <span class="n">someEntity</span><span class="o">,</span> <span class="n">Entity</span> <span class="n">entity2</span><span class="o">)</span> <span class="o">{</span>
<span class="n">someEntity</span><span class="o">.</span><span class="na">getFoo</span><span class="o">().</span><span class="na">orElse</span><span class="o">(</span><span class="n">entity2</span><span class="o">.</span><span class="na">getFoo</span><span class="o">().</span><span class="na">orElse</span><span class="o">(</span><span class="n">MyPlugin</span><span class="o">.</span><span class="na">DEFAULT_FOO</span><span class="o">)).</span><span class="na">bar</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
<p>This is merely the tip of the <code class="docutils literal"><span class="pre">Optional</span></code> iceberg. In java 8 <code class="docutils literal"><span class="pre">Optional</span></code> also supports the <code class="docutils literal"><span class="pre">Consumer</span></code> and
<code class="docutils literal"><span class="pre">Supplier</span></code> interfaces, allowing lambas to be used for <em>absent</em> failover. Usage examples for those can be found on the
<a class="reference internal" href="usage.html"><span class="doc">Usage Examples</span></a> page.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Another explanation on the rationale behind avoiding null references can be found on
<a class="reference external" href="https://github.com/google/guava/wiki/UsingAndAvoidingNullExplained/">Guava: Using And Avoiding Null Explained</a>.
Beware that the guava <code class="docutils literal"><span class="pre">Optional</span></code> class mentioned in the linked article is different from java’s
<code class="docutils literal"><span class="pre">java.util.Optional</span></code> and therefore will have method names different from those used here.</p>
</div>
</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>