<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Configuration Loaders — Sponge 6.0.0 documentation</title>
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/spongedocs.css" type="text/css" />
<link rel="index" title="Index"
href="../../genindex.html"/> <link rel="search" title="Search" href="../../search.html"/> <link rel="top" title="Sponge 6.0.0 documentation" href="../../index.html"/> <link rel="up" title="Configuring Plugins" href="index.html"/> <link rel="next" title="Configuration Nodes" href="nodes.html"/> <link rel="prev" title="Configuring Plugins" href="index.html"/>
<!-- Google Analytics -->
<script>
(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','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59476017-2', 'auto');
ga('send', 'pageview');
</script>
<script src="../../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<div id="sp-logo-container" class="page-scroll">
<a class="logo" href="../../index.html">
<img src="../../_static/spongie-mark-dark.svg">
<span>Sponge</span>
<i class="fa fa-fw fa-chevron-down"></i>
</a>
<div id="sp-logo-menu">
<ul id="sp-logo-dropdown">
<li><a href="https://www.spongepowered.org"><i class="fa-fw fa fa-home"></i>Homepage</a></li>
<li><a href="https://forums.spongepowered.org"><i class="fa-fw fa fa-comments"></i>Forums</a></li>
<li><a href="https://github.com/SpongePowered"><i class="fa-fw fa fa-code"></i>Code</a></li>
<li class="active"><a href="https://docs.spongepowered.org"><i class="fa-fw fa fa-book"></i>Docs</a></li>
<li><a href="https://jd.spongepowered.org"><i class="fa-fw fa fa-graduation-cap"></i>Javadocs</a></li>
<li><a href="https://forums.spongepowered.org/c/plugins/plugin-releases"><i class="fa-fw fa fa-plug"></i>Plugins</a></li>
<li><a href="https://www.spongepowered.org/downloads"><i class="fa-fw fa fa-download"></i>Downloads</a></li>
<li><a href="https://www.spongepowered.org/chat"><i class="fa-fw fa fa-comment"></i>Chat</a></li>
</ul>
</div>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div> </div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../server/index.html">Creating a Server</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../preparing/index.html">Preparing for Development</a></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></li>
<li class="toctree-l2"><a class="reference internal" href="../project/index.html">Setting Up Your Project</a></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/index.html">Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="../optional/index.html">Optionals</a></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></li>
<li class="toctree-l2"><a class="reference internal" href="../event/index.html">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="../assets.html">The Asset API</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">Configuring Plugins</a><ul class="current">
<li class="toctree-l3 current"><a class="current reference internal" href="#">Configuration Loaders</a></li>
<li class="toctree-l3"><a class="reference internal" href="nodes.html">Configuration Nodes</a></li>
<li class="toctree-l3"><a class="reference internal" href="serialization.html">Serializing Objects</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../text/index.html">Text</a></li>
<li class="toctree-l2"><a class="reference internal" href="../data/index.html">The Data API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../blocks/index.html">Blocks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../entities/index.html">Entities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../items/index.html">Items</a></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></li>
<li class="toctree-l2"><a class="reference internal" href="../wgen/index.html">World Generation</a></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>
<li class="toctree-l2"><a class="reference internal" href="../internals/index.html">Implementation-dependent Plugins</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../ore/index.html">Ore Documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../contributing/index.html">Contributing to Sponge</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../about/index.html">About the Sponge Project</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">Sponge</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html">Docs</a> »</li>
<li><a href="../index.html">Creating a Plugin</a> »</li>
<li><a href="index.html">Configuring Plugins</a> »</li>
<li>Configuration Loaders</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/SpongePowered/SpongeDocs/blob/BestPractises/source/plugin/configuration/loaders.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="configuration-loaders">
<h1>Configuration Loaders<a class="headerlink" href="#configuration-loaders" title="Permalink to this headline">¶</a></h1>
<p>Let’s break down how Configurate works, beginning with the loading process. Configurate provides
<a class="reference external" href="http://zml2008.github.io/configurate/apidocs/ninja/leaping/configurate/loader/ConfigurationLoader.html">ConfigurationLoader</a>s for common configuration formats, standing as the manager of the physical
configuration file, allowing you to save and load data from the given resource. They also allow you to load empty
configurations, giving you the option of hard-coding default values or loading from a pre-written file.</p>
<div class="section" id="getting-your-loader">
<h2>Getting your Loader<a class="headerlink" href="#getting-your-loader" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The default <a class="reference external" href="http://zml2008.github.io/configurate/apidocs/ninja/leaping/configurate/loader/ConfigurationLoader.html">ConfigurationLoader</a> can be used instead if you’re using HOCON; see the
<a class="reference internal" href="index.html"><span class="doc">main configuration page</span></a>.</p>
</div>
<p>First, let’s grab a new <a class="reference external" href="http://zml2008.github.io/configurate/apidocs/ninja/leaping/configurate/hocon/HoconConfigurationLoader.html">HoconConfigurationLoader</a> that points to our configuration file.</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">java.nio.file.Path</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">ninja.leaping.configurate.commented.CommentedConfigurationNode</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">ninja.leaping.configurate.hocon.HoconConfigurationLoader</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">ninja.leaping.configurate.loader.ConfigurationLoader</span><span class="o">;</span>
<span class="n">Path</span> <span class="n">potentialFile</span> <span class="o">=</span> <span class="n">getConfigPath</span><span class="o">();</span>
<span class="n">ConfigurationLoader</span><span class="o"><</span><span class="n">CommentedConfigurationNode</span><span class="o">></span> <span class="n">loader</span> <span class="o">=</span>
<span class="n">HoconConfigurationLoader</span><span class="o">.</span><span class="na">builder</span><span class="o">().</span><span class="na">setPath</span><span class="o">(</span><span class="n">potentialFile</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
</pre></div>
</div>
<p>The loader will also hold a generic type depending what kind of node it will build. These <em>Configuration Nodes</em> will be
discussed in <a class="reference internal" href="nodes.html"><span class="doc">a later section</span></a>.</p>
<p><code class="docutils literal"><span class="pre">ConfigurationLoader</span></code>s usually hold a builder for you to statically access and create a new instance of the loader of
your desired type. For a basic configuration, we don’t really need to specify anything other than the file we want to
load from and/or save to, so all we’ll do is tell it exactly that, using
<code class="docutils literal"><span class="pre">HoconConfigurationLoader.builder().setPath(path)</span></code>. We then tell the builder to build the instance (<code class="docutils literal"><span class="pre">build()</span></code>) for
it and store it in a variable.</p>
<p>Of course, this isn’t the only way to load a file. The builder also has the method <code class="docutils literal"><span class="pre">setURL(URL)</span></code>, in case you want
to load a resource without using a <code class="docutils literal"><span class="pre">Path</span></code> object. Bear in mind that configuration loaders created from an <code class="docutils literal"><span class="pre">URL</span></code>
are read-only as they have no way of writing back data to the URL.</p>
<p>This functionality may be used to bundle default configurations with your plugin jar file and load them as initial
configuration to be edited by the server administrator (or your plugin itself).</p>
</div>
<div class="section" id="loading-and-saving">
<h2>Loading and Saving<a class="headerlink" href="#loading-and-saving" title="Permalink to this headline">¶</a></h2>
<p>Once you obtained your <code class="docutils literal"><span class="pre">ConfigurationLoader</span></code> you can use it to obtain an empty <a class="reference external" href="http://zml2008.github.io/configurate/apidocs/ninja/leaping/configurate/ConfigurationNode.html">ConfigurationNode</a> using the
<code class="docutils literal"><span class="pre">createEmptyNode()</span></code> method.</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">ninja.leaping.configurate.ConfigurationNode</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">ninja.leaping.configurate.ConfigurationOptions</span><span class="o">;</span>
<span class="n">Path</span> <span class="n">potentialFile</span> <span class="o">=</span> <span class="n">getConfigPath</span><span class="o">();</span>
<span class="n">ConfigurationLoader</span><span class="o"><</span><span class="n">CommentedConfigurationNode</span><span class="o">></span> <span class="n">loader</span> <span class="o">=</span> <span class="n">HoconConfigurationLoader</span><span class="o">.</span><span class="na">builder</span><span class="o">().</span><span class="na">setPath</span><span class="o">(</span><span class="n">potentialFile</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
<span class="n">ConfigurationNode</span> <span class="n">rootNode</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="na">createEmptyNode</span><span class="o">(</span><span class="n">ConfigurationOptions</span><span class="o">.</span><span class="na">defaults</span><span class="o">());</span>
</pre></div>
</div>
<p>This method expects the <cite>ninja.leaping.configurate.ConfigurationOptions</cite> to use as a parameter. Unless you want to use
features like custom type serialization, you can just use <a class="reference external" href="http://zml2008.github.io/configurate/apidocs/ninja/leaping/configurate/ConfigurationOptions.html#defaults--">ConfigurationOptions#defaults()</a> to create an
options object with default values.</p>
<p>Using the <code class="docutils literal"><span class="pre">load()</span></code> method you can attempt to load the configuration contents from the source specified upon creation
of the <code class="docutils literal"><span class="pre">ConfigurationLoader</span></code>. It also expects a <code class="docutils literal"><span class="pre">ConfigurationOptions</span></code> instance, but also provides a no-args form
that is shorthand for <code class="docutils literal"><span class="pre">load(ConfigurationOptions.defaults())</span></code>.</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">java.io.IOException</span><span class="o">;</span>
<span class="n">Path</span> <span class="n">potentialFile</span> <span class="o">=</span> <span class="n">getConfigPath</span><span class="o">();</span>
<span class="n">ConfigurationLoader</span><span class="o"><</span><span class="n">CommentedConfigurationNode</span><span class="o">></span> <span class="n">loader</span> <span class="o">=</span> <span class="n">HoconConfigurationLoader</span><span class="o">.</span><span class="na">builder</span><span class="o">().</span><span class="na">setPath</span><span class="o">(</span><span class="n">potentialFile</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
<span class="n">ConfigurationNode</span> <span class="n">rootNode</span><span class="o">;</span>
<span class="k">try</span> <span class="o">{</span>
<span class="n">rootNode</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="na">load</span><span class="o">();</span>
<span class="o">}</span> <span class="k">catch</span><span class="o">(</span><span class="n">IOException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
<span class="c1">// error</span>
<span class="o">}</span>
</pre></div>
</div>
<p>If the <code class="docutils literal"><span class="pre">Path</span></code> given does not exist, the <code class="docutils literal"><span class="pre">load()</span></code> method will create an empty <code class="docutils literal"><span class="pre">ConfigurationNode</span></code>. Any other error
will lead to an <code class="docutils literal"><span class="pre">IOException</span></code> being thrown which you will need to handle properly.</p>
<p>If you have injected the default loader, it’s a good idea to get its <code class="docutils literal"><span class="pre">ConfigurationOptions</span></code>, since they contain the
ability to serialize and deserialize a large number of Sponge objects.</p>
<p>Once you modified your <code class="docutils literal"><span class="pre">ConfigurationNode</span></code> to hold the data you like to be saved, you can use the
<code class="docutils literal"><span class="pre">ConfigurationLoader</span></code> to save the node to the file specified while creating the loader. If that file does not exist,
it will be created. If it does exist, all contents will be overwritten.</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="k">try</span> <span class="o">{</span>
<span class="n">loader</span><span class="o">.</span><span class="na">save</span><span class="o">(</span><span class="n">rootNode</span><span class="o">);</span>
<span class="o">}</span> <span class="k">catch</span><span class="o">(</span><span class="n">IOException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
<span class="c1">// error</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Again, errors will be propagated as an <code class="docutils literal"><span class="pre">IOException</span></code> and must be handled.</p>
</div>
<div class="section" id="example-loading-a-default-config-from-the-plugin-jar-file">
<h2>Example: Loading a default config from the plugin jar file<a class="headerlink" href="#example-loading-a-default-config-from-the-plugin-jar-file" title="Permalink to this headline">¶</a></h2>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">java.net.URL</span><span class="o">;</span>
<span class="n">URL</span> <span class="n">jarConfigFile</span> <span class="o">=</span> <span class="n">Sponge</span><span class="o">.</span><span class="na">getAssetManager</span><span class="o">().</span><span class="na">getAsset</span><span class="o">(</span><span class="s">"defaultConfig.conf"</span><span class="o">).</span><span class="na">get</span><span class="o">().</span><span class="na">getUrl</span><span class="o">();</span>
<span class="n">ConfigurationLoader</span><span class="o"><</span><span class="n">CommentedConfigurationNode</span><span class="o">></span> <span class="n">loader</span> <span class="o">=</span>
<span class="n">HoconConfigurationLoader</span><span class="o">.</span><span class="na">builder</span><span class="o">().</span><span class="na">setURL</span><span class="o">(</span><span class="n">jarConfigFile</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
</pre></div>
</div>
<p>For this example it is important to note that the <a class="reference external" href="https://jd.spongepowered.org/6.0.0/org/spongepowered/api/asset/AssetManager.html#getAsset-java.lang.String-">AssetManager#getAsset(String)</a> method works relative to the
plugin’s asset folder. So if in the above example the plugin ID is <code class="docutils literal"><span class="pre">myplugin</span></code>, the <code class="docutils literal"><span class="pre">defaultConfig.conf</span></code> file
must not lie in the jar file root, but instead in the directory <code class="docutils literal"><span class="pre">assets/myplugin</span></code>. For more information, see
<a class="reference internal" href="../assets.html"><span class="doc">the Asset API page</span></a>.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="nodes.html" class="btn btn-neutral float-right" title="Configuration Nodes" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="index.html" class="btn btn-neutral" title="Configuring Plugins" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2014-2017, Sponge Contributors.
</p>
</div>Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<i class="fa fa-book"> <span>SpongeDocs</span></i>
v: 6.0.0
<span class="fa fa-caret-down"></span>
</span>
<div id="versions" class="rst-other-versions">
<dl>
<dt>Contribute</dt>
<dd><a href="https://github.com/SpongePowered/SpongeDocs/blob/BestPractises/source/plugin/configuration/loaders.rst">Source</a></dd>
<dd><a href="https://github.com/SpongePowered/SpongeDocs/edit/BestPractises/source/plugin/configuration/loaders.rst">Edit</a></dd>
</dl>
</div>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../',
VERSION:'6.0.0',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</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/spongedocs.js"></script>
<script type="text/javascript" src="../../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>