blob: 1b146229d5410c9b154af87c9795755a0713916c [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="en">
<head>
<!-- Generated by javadoc (24) on Mon Sep 29 10:48:08 CEST 2025 -->
<title>Configuration (Apache SIS 1.5 API)</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="dc.created" content="2025-09-29">
<meta name="description" content="declaration: module: org.apache.sis.util, package: org.apache.sis.setup, class: Configuration">
<meta name="generator" content="javadoc/ClassWriter">
<meta name="keywords" content="org.apache.sis.setup.Configuration class">
<meta name="keywords" content="current()">
<meta name="keywords" content="getDatabase()">
<meta name="keywords" content="setDatabase()">
<meta name="keywords" content="shutdown()">
<link rel="stylesheet" type="text/css" href="../../../../../resource-files/jquery-ui.min.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../../../../resource-files/stylesheet.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../../../../resource-files/sis.css" title="Style">
<script type="text/javascript" src="../../../../../script-files/script.js"></script>
<script type="text/javascript" src="../../../../../script-files/jquery-3.7.1.min.js"></script>
<script type="text/javascript" src="../../../../../script-files/jquery-ui.min.js"></script>
</head>
<body class="class-declaration-page">
<script type="text/javascript">const pathtoroot = "../../../../../";
loadScripts(document, 'script');</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<header role="banner">
<nav role="navigation">
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="top-nav" id="navbar-top">
<div class="nav-content">
<div class="nav-menu-button"><button id="navbar-toggle-button" aria-controls="navbar-top" aria-expanded="false" aria-label="Toggle navigation links"><span class="nav-bar-toggle-icon">&nbsp;</span><span class="nav-bar-toggle-icon">&nbsp;</span><span class="nav-bar-toggle-icon">&nbsp;</span></button></div>
<div class="skip-nav"><a href="#skip-navbar-top" title="Skip navigation links">Skip navigation links</a></div>
<ul id="navbar-top-firstrow" class="nav-list" title="Navigation">
<li><a href="../../../../../index.html">Overview</a></li>
<li class="nav-bar-cell1-rev">Class</li>
<li><a href="class-use/Configuration.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../new-list.html">New</a></li>
<li><a href="../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../search.html">Search</a></li>
<li><a href="../../../../../help-doc.html#class">Help</a></li>
</ul>
</div>
</div>
<div class="sub-nav">
<div class="nav-content">
<ol class="sub-nav-list">
<li><a href="../../../../module-summary.html">org.apache.sis.util</a></li>
<li><a href="package-summary.html">org.apache.sis.setup</a></li>
<li><a href="Configuration.html" class="current-selection">Configuration</a></li>
</ol>
<div class="nav-list-search">
<input type="text" id="search-input" disabled placeholder="Search" aria-label="Search in documentation" autocomplete="off">
<input type="reset" id="reset-search" disabled value="Reset">
</div>
</div>
</div>
<!-- ========= END OF TOP NAVBAR ========= -->
<span class="skip-nav" id="skip-navbar-top"></span></nav>
</header>
<div class="main-grid">
<nav role="navigation" class="toc" aria-label="Table of contents">
<div class="toc-header">Contents&nbsp;
<input type="text" class="filter-input" disabled placeholder="Filter" aria-label="Filter table of contents" autocomplete="off">
<input type="reset" class="reset-filter" disabled value="Reset">
</div>
<button class="hide-sidebar"><span>Hide sidebar&nbsp;</span>&#10094;</button><button class="show-sidebar">&#10095;<span>&nbsp;Show sidebar</span></button>
<ol class="toc-list">
<li><a href="#" tabindex="0">Description</a>
<ol class="toc-list">
<li><a href="#other-system-wide-configuration-heading" tabindex="0">Other system-wide configuration</a></li>
</ol>
</li>
<li><a href="#method-summary" tabindex="0">Method Summary</a></li>
<li><a href="#method-detail" tabindex="0">Method Details</a>
<ol class="toc-list">
<li><a href="#current()" tabindex="0">current()</a></li>
<li><a href="#getDatabase()" tabindex="0">getDatabase()</a></li>
<li><a href="#setDatabase(java.util.function.Supplier)" tabindex="0">setDatabase(Supplier)</a></li>
<li><a href="#shutdown()" tabindex="0">shutdown()</a></li>
</ol>
</li>
</ol>
</nav>
<main role="main">
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<h1 title="Class Configuration" class="title">Class Configuration</h1>
</div>
<div class="inheritance" title="Inheritance Tree"><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>
<div class="inheritance">Configuration</div>
</div>
<section class="class-description" id="class-description">
<hr>
<div class="horizontal-scroll">
<div class="type-signature"><span class="modifiers">public final class </span><span class="element-name type-name-label">Configuration</span>
<span class="extends-implements">extends <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a></span></div>
<div class="block">Provides system-wide configuration for Apache SIS library.
Methods in this class can be used for overriding SIS default values.
Those methods can be used in final applications, but should not be used by libraries
in order to avoid interfering with user's settings.
<h2 id="other-system-wide-configuration-heading">Other system-wide configuration</h2>
The following methods have system-wide effects on Apache SIS configuration,
but are not yet controlled through this <code>Configuration</code> class:
<ul>
<li><a href="../util/logging/MonolineFormatter.html#install()"><code>Monoline­Formatter​.install()</code></a></li>
<li><a href="../util/logging/PerformanceLevel.html#setMinDuration(long,java.util.concurrent.TimeUnit)"><code>Performance­Level​.set­Min­Duration(long, Time­Unit)</code></a></li>
</ul>
The following properties are defined by the standard Java environment.
Apache SIS read those properties but does not modify them:
<ul>
<li><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Locale.html#getDefault()" title="class or interface in java.util" class="external-link"><code>Locale​.get­Default()</code></a> (sometimes using <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Locale.Category.html" title="class or interface in java.util" class="external-link"><code>Locale​.Category</code></a>)</li>
<li><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/charset/Charset.html#defaultCharset()" title="class or interface in java.nio.charset" class="external-link"><code>Charset​.default­Charset()</code></a></li>
<li><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/TimeZone.html#getDefault()" title="class or interface in java.util" class="external-link"><code>Time­Zone​.get­Default()</code></a></li>
<li><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/System.html#lineSeparator()" title="class or interface in java.lang" class="external-link"><code>System​.line­Separator()</code></a></li>
<li><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/io/File.html#pathSeparator" title="class or interface in java.io" class="external-link"><code>File​.path­Separator</code></a></li>
<li><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/io/File.html#separator" title="class or interface in java.io" class="external-link"><code>File​.separator</code></a></li>
</ul></div>
<dl class="notes">
<dt>Since:</dt>
<dd>1.0</dd>
</dl>
</div>
</section>
<section class="summary">
<ul class="summary-list">
<!-- ========== METHOD SUMMARY =========== -->
<li>
<section class="method-summary" id="method-summary">
<h2>Method Summary</h2>
<div id="method-summary-table">
<div class="table-tabs" role="tablist" aria-orientation="horizontal"><button id="method-summary-table-tab0" role="tab" aria-selected="true" aria-controls="method-summary-table.tabpanel" tabindex="0" onkeydown="switchTab(event)" onclick="show('method-summary-table', 'method-summary-table', 3)" class="active-table-tab">All Methods</button><button id="method-summary-table-tab1" role="tab" aria-selected="false" aria-controls="method-summary-table.tabpanel" tabindex="-1" onkeydown="switchTab(event)" onclick="show('method-summary-table', 'method-summary-table-tab1', 3)" class="table-tab">Static Methods</button><button id="method-summary-table-tab2" role="tab" aria-selected="false" aria-controls="method-summary-table.tabpanel" tabindex="-1" onkeydown="switchTab(event)" onclick="show('method-summary-table', 'method-summary-table-tab2', 3)" class="table-tab">Instance Methods</button><button id="method-summary-table-tab4" role="tab" aria-selected="false" aria-controls="method-summary-table.tabpanel" tabindex="-1" onkeydown="switchTab(event)" onclick="show('method-summary-table', 'method-summary-table-tab4', 3)" class="table-tab">Concrete Methods</button></div>
<div id="method-summary-table.tabpanel" role="tabpanel" aria-labelledby="method-summary-table-tab0">
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Method</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab1 method-summary-table-tab4"><code>static <a href="Configuration.html" title="class in org.apache.sis.setup">Configuration</a></code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab1 method-summary-table-tab4"><code><a href="#current()" class="member-name-link">current</a>()</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab1 method-summary-table-tab4">
<div class="block">Returns the current configuration.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4"><code><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Optional.html" title="class or interface in java.util" class="external-link">Optional</a><wbr>&lt;<a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/javax/sql/DataSource.html" title="class or interface in javax.sql" class="external-link">Data­Source</a>&gt;</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4"><code><a href="#getDatabase()" class="member-name-link">get­Database</a>()</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4">
<div class="block">Returns the data source for the SIS-wide "SpatialMetadata" database.</div>
</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4"><code>void</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4"><code><a href="#setDatabase(java.util.function.Supplier)" class="member-name-link">set­Database</a><wbr>(<a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/function/Supplier.html" title="class or interface in java.util.function" class="external-link">Supplier</a>&lt;<a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/javax/sql/DataSource.html" title="class or interface in javax.sql" class="external-link">Data­Source</a>&gt;&nbsp;source)</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4">
<div class="block">Specifies the data source to use if no <code>"jdbc/Spatial­Metadata"</code> source is binded to a JNDI environment.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4"><code>void</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4"><code><a href="#shutdown()" class="member-name-link">shutdown</a>()</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4">
<div class="block">Shutdowns the Apache <abbr>SIS</abbr> library.</div>
</div>
</div>
</div>
</div>
<div class="inherited-list">
<h3 id="methods-inherited-from-class-Object">Methods inherited from class&nbsp;<a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a></h3>
<code><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#clone()" title="class or interface in java.lang" class="external-link">clone</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#equals(java.lang.Object)" title="class or interface in java.lang" class="external-link">equals</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#finalize()" title="class or interface in java.lang" class="external-link">finalize</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#getClass()" title="class or interface in java.lang" class="external-link">get­Class</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#hashCode()" title="class or interface in java.lang" class="external-link">hash­Code</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#notify()" title="class or interface in java.lang" class="external-link">notify</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#notifyAll()" title="class or interface in java.lang" class="external-link">notify­All</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#toString()" title="class or interface in java.lang" class="external-link">to­String</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#wait()" title="class or interface in java.lang" class="external-link">wait</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#wait(long)" title="class or interface in java.lang" class="external-link">wait</a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Object.html#wait(long,int)" title="class or interface in java.lang" class="external-link">wait</a></code></div>
</section>
</li>
</ul>
</section>
<section class="details">
<ul class="details-list">
<!-- ============ METHOD DETAIL ========== -->
<li>
<section class="method-details" id="method-detail">
<h2>Method Details</h2>
<ul class="member-list">
<li>
<section class="detail" id="current()">
<h3>current</h3>
<div class="horizontal-scroll">
<div class="member-signature"><span class="modifiers">public static</span>&nbsp;<span class="return-type"><a href="Configuration.html" title="class in org.apache.sis.setup">Configuration</a></span>&nbsp;<span class="element-name">current</span>()</div>
<div class="block">Returns the current configuration.</div>
<dl class="notes">
<dt>Returns:</dt>
<dd>the current configuration.</dd>
</dl>
</div>
</section>
</li>
<li>
<section class="detail" id="getDatabase()">
<h3>getDatabase</h3>
<div class="horizontal-scroll">
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Optional.html" title="class or interface in java.util" class="external-link">Optional</a>&lt;<a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/javax/sql/DataSource.html" title="class or interface in javax.sql" class="external-link">DataSource</a>&gt;</span>&nbsp;<span class="element-name">getDatabase</span>()
throws <span class="exceptions"><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/java/sql/SQLException.html" title="class or interface in java.sql" class="external-link">SQLException</a></span></div>
<div class="block">Returns the data source for the SIS-wide "SpatialMetadata" database.
This method returns the first of the following steps that succeed:
<ol>
<li>If a JNDI context exists, use the data source registered under the <code>"jdbc/Spatial­Metadata"</code> name.</li>
<li>Otherwise if a default data source <a href="#setDatabase(java.util.function.Supplier)">has been supplied</a>, use that data source.</li>
<li>Otherwise if the <code>SIS_DATA</code> environment variable is defined,
use the data source for <code>"jdbc:derby:$SIS_DATA/Databases/Spatial­Metadata"</code>.
That database will be created if it does not exist. Note that this is the only case where
Apache SIS may create the database since it is located in the directory managed by Apache SIS.</li>
<li>Otherwise if the <code>org​.apache​.sis​.referencing​.database</code> module is present on the module path,
use the embedded database.</li>
<li>Otherwise if the "<code><span id="derby.system.home" class="search-tag-result">derby​.system​.home</span></code>" property is defined,
use the data source for <code>"jdbc:derby:Spatial­Metadata"</code> database.
This database will <strong>not</strong> be created if it does not exist.</li>
</ol></div>
<dl class="notes">
<dt>Returns:</dt>
<dd>the data source for the <code>"Spatial­Metadata"</code> database.</dd>
<dt>Throws:</dt>
<dd><code><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/java/sql/SQLException.html" title="class or interface in java.sql" class="external-link">SQLException</a></code> - if an error occurred while fetching the database source.</dd>
</dl>
</div>
</section>
</li>
<li>
<section class="detail" id="setDatabase(java.util.function.Supplier)">
<h3>setDatabase</h3>
<div class="horizontal-scroll">
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type">void</span>&nbsp;<span class="element-name">setDatabase</span><wbr><span class="parameters">(<a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/function/Supplier.html" title="class or interface in java.util.function" class="external-link">Supplier</a>&lt;<a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/javax/sql/DataSource.html" title="class or interface in javax.sql" class="external-link">DataSource</a>&gt;&nbsp;source)</span></div>
<div class="block">Specifies the data source to use if no <code>"jdbc/Spatial­Metadata"</code> source is binded to a JNDI environment.
Data source specified by JNDI has precedence over data source specified by this method in order to let users
control their data source. The following example shows how to setup a connection to a PostgreSQL database:
<div class="snippet-container"><button class="copy snippet-copy" aria-label="Copy snippet" onclick="copySnippet(this)"><span data-copied="Copied!">Copy</span><img src="../../../../../resource-files/copy.svg" alt="Copy snippet"></button>
<pre class="snippet" id="snippet-setDatabase(java.util.function.Supplier)1"><code class="language-java">import org.postgresql.ds.PGSimpleDataSource;
class MyClass {
private static DataSource createDataSource() {
PGSimpleDataSource ds = new PGSimpleDataSource();
ds.setDatabaseName("SpatialMetadata");
// Server default to "localhost".
return ds;
}
static initialize() {
if (WANT_TO_CONFIGURE_JNDI) {
// Registration assuming that a JNDI implementation is available
Context env = (Context) InitialContext.doLookup("java:comp/env");
env.bind("jdbc/SpatialMetadata", createDataSource());
}
// Fallback if there is no JNDI or no "SpatialMetadata" entry.
Configuration.current().setDatabase(MyClass::createDataSource);
}
}
</code></pre>
</div>
This method can be invoked only before the first attempt to <a href="#getDatabase()">get the database</a>.
If the <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/javax/sql/DataSource.html" title="class or interface in javax.sql" class="external-link"><code>Data­Source</code></a> has already be obtained, then this method throws <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/IllegalStateException.html" title="class or interface in java.lang" class="external-link"><code>Illegal­State­Exception</code></a>.</div>
<dl class="notes">
<dt>Parameters:</dt>
<dd><code>source</code> - supplier of data source to set.
The supplier may return <code>null</code>, in which case it will be ignored.</dd>
<dt>Throws:</dt>
<dd><code><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/IllegalStateException.html" title="class or interface in java.lang" class="external-link">Illegal­State­Exception</a></code> - if <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/javax/sql/DataSource.html" title="class or interface in javax.sql" class="external-link"><code>Data­Source</code></a> has already be obtained before this method call.</dd>
<dt>See Also:</dt>
<dd>
<ul class="tag-list-long">
<li><a href="https://sis.apache.org/epsg.html#jndi">How to use EPSG geodetic dataset</a></li>
</ul>
</dd>
</dl>
</div>
</section>
</li>
<li>
<section class="detail" id="shutdown()">
<h3>shutdown</h3>
<div class="horizontal-scroll">
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type">void</span>&nbsp;<span class="element-name">shutdown</span>()</div>
<div class="block">Shutdowns the Apache <abbr>SIS</abbr> library.
This method closes database connections and stops the daemon threads that were started by <abbr>SIS</abbr>.
<strong>The Apache <abbr>SIS</abbr> library shall not be used anymore after this method call.</strong>
Any use of Apache <abbr>SIS</abbr> after this method call may have unexpected effects.
In particular, it may cause memory leaks.
<h4 id="when-to-use-heading">When to use</h4>
This method should generally <strong>not</strong> be invoked, because Apache <abbr>SIS</abbr> registers
itself a <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Runtime.html#addShutdownHook(java.lang.Thread)" title="class or interface in java.lang" class="external-link">shutdown hook</a> to the Java Virtual Machine.
This method may be useful in embedded environments that do not allow the use of shutdown hooks,
or when waiting for the <abbr>JVM</abbr> shutdown is overly conservative.
<h4 id="complete-shutdown-heading">Complete shutdown</h4>
This method shutdowns only the databases used by Apache <abbr>SIS</abbr>.
If Apache Derby is used for the <abbr>EPSG</abbr> database, some Derby daemon threads may still be running.
Those daemons can be ignored in standalone applications, but may need to be stopped in embedded environments.
A complete Derby shutdown can be requested with the following code:
<div class="snippet-container"><button class="copy snippet-copy" aria-label="Copy snippet" onclick="copySnippet(this)"><span data-copied="Copied!">Copy</span><img src="../../../../../resource-files/copy.svg" alt="Copy snippet"></button>
<pre class="snippet" id="snippet-shutdown()1"><code class="language-java">Configuration.current().shutdown();
try {
DriverManager.getConnection("jdbc:derby:;shutdown=true");
} catch (SQLException e) {
// Expected exception as per Derby documentation.
}
</code></pre>
</div>
</div>
<dl class="notes">
<dt>Since:</dt>
<dd>1.5</dd>
<dt>See Also:</dt>
<dd>
<ul class="tag-list">
<li><a href="https://db.apache.org/derby/docs/10.15/devguide/tdevdvlp40464.html">Shutting down Derby</a></li>
</ul>
</dd>
</dl>
</div>
</section>
</li>
</ul>
</section>
</li>
</ul>
</section>
<!-- ========= END OF CLASS DATA ========= -->
</main>
</div>
</body>
</html>