blob: f51ebef55415dfc9989258f23eeff9b69b13a190 [file] [log] [blame]
<html lang="en">
<title>Release Notes for Apache Derby 10.15.0.0</title>
<body>
<h1>
<a name="Release Notes for Apache Derby 10.15.0.0"></a>Release Notes for Apache Derby 10.15.0.0</h1>
<div>
<p>These notes describe the difference between Apache Derby release 10.15.0.0 and the preceding release 10.14.2.0.</p>
</div>
<ul>
<li>
<a href="#Overview">Overview</a>
</li>
<li>
<a href="#New Features">New Features</a>
</li>
<li>
<a href="#Bug Fixes">Bug Fixes</a>
</li>
<li>
<a href="#Issues">Issues</a>
</li>
<li>
<a href="#Build Environment">Build Environment</a>
</li>
<li>
<a href="#Verifying Releases">Verifying Releases</a>
</li>
</ul>
<h2>
<a name="Overview"></a>Overview</h2>
<div>
<p>
The most up to date information about Derby releases can be found on the
<a href="http://db.apache.org/derby/derby_downloads.html">Derby download page</a>.
</p>
<p>
Apache Derby is a pure Java relational database engine using standard SQL and
JDBC as its APIs. More information about Derby can be found on the
<a href="http://db.apache.org/derby/">Apache web site</a>.
Derby functionality includes:
</p>
<ul>
<li>Embedded engine with JDBC drivers</li>
<li>Network Server</li>
<li>Network client JDBC drivers</li>
<li>Command line tools: ij (SQL scripting), dblook (schema dump) and sysinfo (system info)</li>
</ul>
<p>
The 10.15 release family supports the following Java and JDBC versions:
</p>
<ul>
<li>Java SE 9 and higher with JDBC 4.2.</li>
</ul>
</div>
<h2>
<a name="New Features"></a>New Features</h2>
<div>
<p>
This is a feature release. The following new feature was added:
</p>
<ul>
<li>
<b>JPMS modularization</b> - Derby has been re-packaged as a set of JPMS modules. This introduced a new jar file, <i>derbyshared.jar</i>, required by all configurations. Module diagrams for Derby configurations can be found in the
<a href="http://db.apache.org/derby/docs/10.15/publishedapi/index.html">javadoc</a>
for the 10.15 public API.
</li>
</ul>
<p>
New users should consult the
<a href="http://db.apache.org/derby/manuals/index.html#docs_10.15">10.15 documentation</a>,
especially the
<a href="http://db.apache.org/derby/docs/10.15/getstart/index.html">Getting Started With Derby</a> guide.
</p>
<p>
Existing users who want to continue running Derby with a classpath should read the extended release note for issue DERBY-6945 (see below).
</p>
<p>
Existing users who want to run Derby with a module path should consult the module diagrams in the
<a href="http://db.apache.org/derby/docs/10.15/publishedapi/index.html">javadoc</a>
for the 10.15 public API. Templates for wiring together a module path can be found in the
<i>setEmbeddedCP</i>, <i>setNetworkServerCP</i>, and <i>setNetworkClientCP</i> scripts located
in the bin directory of the release distributions, as described by the
"Manually setting the CLASSPATH/MODULEPATH environment variables" topic in the
<a href="http://db.apache.org/derby/docs/10.15/getstart/index.html">Getting Started With Derby</a> guide.
</p>
</div>
<h2>
<a name="Bug Fixes"></a>Bug Fixes</h2>
<div>
<p>The following issues are addressed by Derby release 10.15.0.0. These issues are not addressed in the preceding 10.14.2.0 release.</p>
<table border="2">
<tr>
<th>
<div style="width:110px;">Issue Id</div>
</th><th>Description</th>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-7020">DERBY-7020</a></td><td>Fix release targets to account for modularization changes</td>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-7018">DERBY-7018</a></td><td>Test the demo programs after the changes made by DERBY-6945</td>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-7016">DERBY-7016</a></td><td>Adjust the set*CP scripts to include derbyshared.jar and to set a MODULEPATH variable as well</td>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-6981">DERBY-6981</a></td><td>"SQLSTATE: XJ001, SQLERRMC: java.lang.NullPointerException&#20;&#20;XJ001.U"</td>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-6980">DERBY-6980</a></td><td>Documentation changes to accompany jigsaw-modularization of derby</td>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-6973">DERBY-6973</a></td><td>Provide SHA-512 checksums on future releases</td>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-6945">DERBY-6945</a></td><td>Re-package Derby as a collection of jigsaw modules</td>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-6856">DERBY-6856</a></td><td>Make it possible to build Derby using JDK 9</td>
</tr>
<tr>
<td><a href="https://issues.apache.org/jira/browse/DERBY-5543">DERBY-5543</a></td><td>include debug info in derby builds uploaded to maven</td>
</tr>
</table>
</div>
<h2>
<a name="Issues"></a>Issues</h2>
<div>
<ul>
<li>
<a href="#Note for DERBY-6945"><span>Note for DERBY-6945:
Modularize Derby, cleanly partitioning its packages across a small set of
JPMS components.
</span></a>
</li>
</ul>
<p>Compared with the previous release (10.14.2.0), Derby release 10.15.0.0 introduces the following new features and incompatibilities. These merit your special attention.</p>
<hr>
<h3>
<a name="Note for DERBY-6945"></a>Note for DERBY-6945</h3>
<div>
<!--
SUMMARIZE THE ISSUE. This is a one line, one sentence summary of the
issue. It serves as the title for the issue in the Issues section of
the full Release Notes.
For instance:
Applications may no longer open two InputStreams on the same ResultSet column.
-->
<h4>Summary of Change</h4>
<p>
Modularize Derby, cleanly partitioning its packages across a small set of
JPMS components.
</p>
<!--
DESCRIBE WHAT IT IS THAT THE USER ACTUALLY SEES WHEN THE PROBLEM OCCURS.
For instance:
In the previous release, applications were able to open two
InputStreams on the same column. Depending on how these streams
interacted, the value siphoned out of the column was erratic. Now
Derby raises a SQLException when the application attempts to create
the second InputStream.
-->
<h4>Symptoms Seen by Applications Affected by Change</h4>
<p>
A new jar file (<i>derbyshared.jar</i>) has been added. All Derby
configurations require it. In addition, the <i>derbytools.jar</i> library is
now required when running the network server and/or when using Derby
DataSources.
</p>
<p>
More privileges must be granted to the Derby jar files when running
under a Security Manager.
</p>
<p>
Derby jar files can now be wired into a modulepath
for use by module-aware applications.
</p>
<!--
OPTIONAL: DESCRIBE INCOMPATIBILITIES WITH PREVIOUS RELEASE, IF ANY.
For instance:
Applications which open two InputStreams on the ResultSet column now
fail.
-->
<h4>Incompatibilities with Previous Release</h4>
<p>
Legacy applications may fail if their classpaths don't contain the
required jar files. Code common to all Derby configurations has been
isolated in the new <i>derbyshared.jar</i> file. DataSources have
moved from <i>derbyclient.jar</i> and <i>derby.jar</i> into <i>derbytools.jar</i>
</p>
<p>
Legacy applications which run under a Java SecurityManager may fail
due to insufficient privilege grants.
</p>
<!--
DESCRIBE WHY THE CHANGE WAS MADE.
For instance:
The previous behavior violated the JDBC standard. The new behavior
is correct.
-->
<h4>Rationale for Change</h4>
<p>
Derby was divided into JPMS components for the following reasons:
</p>
<ul>
<li>
<b>Footprint</b> - Modularization reduces Derby's footprint
when running embedded on resource-constrained devices.</li>
<li>
<b>Security</b> - Modularization lets Derby protect its code
via package-level encapsulation.</li>
</ul>
<!--
OPTIONAL: DESCRIBE HOW TO REVERT TO THE PREVIOUS BEHAVIOR OR
OTHERWISE AVOID THE INCOMPATIBILITIES INTRODUCED BY THIS CHANGE.
For instance:
Users must recode applications which open multiple streams on the same column.
-->
<h4>Application Changes Required</h4>
<p>
Consult the module diagrams for configurations described on the
landing page of the
<a href="http://db.apache.org/derby/docs/10.15/publishedapi/index.html">10.15 public API</a>.
Then adjust your application's classpath as follows:
</p>
<ul>
<li>
<b>Remote client</b> - When running remote client applications, make
sure that the classpath includes <i>derbyshared.jar</i>. Remote applications which
use Derby DataSources should also include <i>derbytools.jar</i>.</li>
<li>
<b>Embedded engine</b> - When running the embedded engine, make
sure that the classpath includes <i>derbyshared.jar</i>. Embedded applications which
use Derby DataSources should also include <i>derbytools.jar</i>.</li>
<li>
<b>Network server</b> - When running the network server, make
sure that the classpath includes <i>derbyshared.jar</i> and <i>derbytools.jar</i>.</li>
<li>
<b>Tools</b> - When running Derby tools like <i>ij</i>,
<i>dblook</i>, and <i>sysinfo</i>, make
sure that the classpath includes <i>derbyshared.jar</i>.</li>
</ul>
<p>
Java security policy files must grant additional privileges to
Derby jar files. For more information, see the "Configuring Java
Security" topic in the
<a href="http://db.apache.org/derby/docs/10.15/security/index.html"><i>Derby Security Guide</i></a>
and consult
the following template policy files
in the <i>demo/templates</i> directory of the bin distribution:
</p>
<ul>
<li>
<b>clientTemplate.policy</b> - Privileges needed by remote
client applications.</li>
<li>
<b>engineTemplate.policy</b> - Privileges needed by applications
which embed the Derby engine.</li>
<li>
<b>serverTemplate.policy</b> - Privileges needed when running the
network server.</li>
<li>
<b>toolsTemplate.policy</b> - Privileges needed when running
Derby tools.</li>
</ul>
</div>
</div>
<h2>
<a name="Build Environment"></a>Build Environment</h2>
<div>
<p>Derby release 10.15.0.0 was built using the following environment:</p>
<ul>
<li>
<b>Branch</b> - Source code came from the 10.15 branch.</li>
<li>
<b>Machine</b> - Mac OSX 10.11.6.</li>
<li>
<b>Ant</b> - Apache Ant(TM) version 1.10.2 compiled on February 3 2018.</li>
<li>
<b>Compiler</b> - All classes were compiled by the javac from OpenJDK 64-Bit Server VM 18.9 (build 11+28, mixed mode).</li>
</ul>
</div>
<h2>
<a name="Verifying Releases"></a>Verifying Releases</h2>
<div>
<p>It is essential that you verify the integrity of the downloaded
files using the PGP and SHA-512 signatures. SHA-512 verification ensures the
file was not corrupted during the download process. PGP verification
ensures that the file came from a certain person.</p>
<p>The PGP signatures can be verified using
<a href="http://www.pgpi.org/">PGP</a> or
<a href="http://www.gnupg.org/">GPG</a>.
First download the Apache Derby
<a href="https://dist.apache.org/repos/dist/release/db/derby/KEYS">KEYS</a>
as well as the <code>asc</code> signature file for the particular
distribution. It is important that you get these files from the ultimate
trusted source - the main ASF distribution site, rather than from a mirror.
Then verify the signatures using ...</p>
<pre>
% pgpk -a KEYS
% pgpv db-derby-X.Y.tar.gz.asc
<em>or</em>
% pgp -ka KEYS
% pgp db-derby-X.Y.tar.gz.asc
<em>or</em>
% gpg --import KEYS
% gpg --verify db-derby-X.Y.tar.gz.asc
</pre>
<p>To verify the SHA-512 checksums on the files, you need to use a
platform-specific program. On Mac OSX, this program is called
<code>shasum</code>, on Linux it is called <code>sha512sum</code>,
and on Windows it is called <code>CertUtil</code>.</p>
<p>We strongly recommend that you verify your downloads with both PGP and SHA-512.</p>
</div>
</body>
</html>