# Release Notes for Apache Derby 10.8.1.2

These notes describe the difference between Apache Derby release 10.8.1.2 and the preceding release 10.7.1.1.

- Overview
- New Features
- Bug Fixes
- Issues
- Build Environment
- Verifying Releases

## Overview

The most up to date information about Derby releases can be found on the Derby download page.

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 Apache web site. Derby functionality includes:

- Embedded engine with JDBC drivers
- Network Server
- Network client JDBC drivers
- Command line tools: ij (SQL scripting), dblook (schema dump) and sysinfo (system info)

Java and JDBC versions supported:

- Java SE 1.4 and higher with JDBC 2.1, 3.0, 4.0 and 4.1
- Java ME CDC/Foundation Profile 1.1 with JSR-169 JDBC Optional Package for CDC/Foundation Profile.

## New Features

This is a feature release. The following new features were added:

- JDBC 4.1 - Derby's JDBC drivers support the new Java 7 methods on the java.sql and javax.sql interfaces. This support works with the pre-GA OpenJDK 7 build 131 available at http://download.java.net/jdk7/ on March 3, 2011. Derby's implementation of these interfaces may change in a future release in the highly unlikely event that the actual GA version of these interfaces changes.
- Automatic calculation of index statistics - Derby automatically refreshes statistics to help it pick better query plans.
- Improved interrupt handling - Interrupting connection threads no longer crashes the Derby engine.
- MAX optimization - On indexed tables, MAX queries run faster in more cases.
- XML operator portability - The xmlparse and xmlserialize operators work out-of-the-box on more platforms.

## Bug Fixes

The following issues are addressed by Derby release 10.8.1.2. These issues are not addressed in the preceding 10.7.1.1 release.

Issue Id | Description
DERBY-5192 | Setting up network server for management tests hangs intermittently
DERBY-5187 | More accessibility fixes needed for demo pages
DERBY-5186 | dblook_test_territory.java fails on AIX with ibm 1.4.2 diffing on 1 line not removed from .out
DERBY-5185 | store/rollForwardRecovery.sql stuck in RAFContainer4.recoverContainerAfterInterrupt() during shutdown
DERBY-5181 | Accessibility fixes needed for release notes
DERBY-5180 | Accessibility fixes needed for top-level and demo pages
DERBY-5174 | Failure in UpdateStatisticsTest after DERBY-5153
DERBY-5173 | RAFContainer.privGetRandomAccessFile() unwraps wrong exception type
DERBY-5171 | Fix uses of <alt> and <desc> elements and figure captions
DERBY-5170 | Client doesn't handle double quotes in savepoint names
DERBY-5168 | Wrong syntax in identifier chain returned by SynonymAliasInfo.toString()
DERBY-5162 | CLOB INOUT arg set to NULL by procedure does not preserve NULL value when re-invoked
DERBY-5161 | Cannot rollback after syntax error in internal statement
DERBY-5160 | NullPointerException when adding column without specifying type
DERBY-5157 | Incomplete quoting of SQL identifiers in AlterTableConstantAction
DERBY-5154 | Tables in documentation should not have empty cells
DERBY-5153 | Intermittent ASSERT FAILED Internal Error-- statistics not found in selectivityForConglomerate when running InterruptResilienceTest
DERBY-5152 | Shutting down db, information that the thread received an interrupt will not be restored to thread's interrupt flag
DERBY-5148 | Fixes for problems with figures in documentation
DERBY-5143 | Remove unnecessary copying of the map in getTypeMap()
DERBY-5136 | Simple accessibility fixes to frames HTML doc output
DERBY-5124 | NPE or assert failure printed when dropping table while statistics are written out
DERBY-5121 | Data corruption when executing an UPDATE trigger
DERBY-5119 | testQualifiers(org.apache.derbyTesting.functionTests.tests.store.AccessTest)java.sql.SQLException: Table/View 'FOO' already exists in Schema 'APP'.
DERBY-5117 | ParameterMetaDataJdbc30Test fails with "'DUMMYINT' is not recognized as a function or procedure"
DERBY-5116 | SequenceTest fails with "Sequence 'MYSEQ1' already exists"
DERBY-5115 | NetworkServerControlApiTest depends on implicit ordering of test cases
DERBY-5114 | Assert failure in SavepointJdbc30Test.testReleaseSqlSavepointAndRollback
DERBY-5113 | Intermittent failure in BlobSetMethodsTest on Java 7: Unable to set stream: 'Reached EOF prematurely; expected 1,024, got 0.'
DERBY-5112 | ImportExportTest depends on implicit ordering of test cases
DERBY-5107 | BasicInMemoryDbTest depends on implicit ordering of test cases
DERBY-5106 | Lacking cleanup in CheckConstraintTest.testJira4282()
DERBY-5104 | InterruptResilienceTest fails to remove tables in tearDown()
DERBY-5103 | ProcedureInTriggerTest depends on implicit ordering of test cases
DERBY-5102 | GrantRevokeDDLTest depends on implicit ordering of test cases
DERBY-5101 | TruncateTableTest depends on implicit ordering of test cases
DERBY-5100 | GetCurrentPropertiesTest depends on implicit ordering of test cases
DERBY-5099 | PrepareStatementTest depends on ordering of test cases
DERBY-5095 | Update XML operator documentation to reflect new requirements
DERBY-5093 | [patch] avoid Integer allocations fetching client meta data info
DERBY-5092 | [patch] avoid Boolean allocations for rowset data in client cursor
DERBY-5089 | Improve tracing/logging of runtime exceptions raised in the istat thread
DERBY-5088 | ShutdownException raised in istat thread during factory call
DERBY-5087 | NPE in istat daemon when encountering critical exception during shutdown
DERBY-5086 | Disable istat logging by default
DERBY-5085 | After specifying deregister=false on the engine shutdown URL, Derby forgets that the default behavior is deregister=true
DERBY-5082 | ShutdownException in ContextManager.checkInterrupt() during shutdown
DERBY-5079 | DERBY-4984 caused a regression which will not allow users to drop a table if the table was involved in a trigger action rebind during ALTER TABLE DROP COLUMN
DERBY-5078 | Incorrect list of compatible JRE versions in client trace
DERBY-5076 | [patch] move instanceof check up above where casts occur
DERBY-5074 | test failure(s) with IBM 1.4.2 in store.InterruptResilienceTest.testRAFWriteInterrupted: java.sql.SQLException: The exception 'junit.framework.AssertionFailedError: interrupt flag lost' was thrown while evaluating an expression.
DERBY-5071 | [patch] use string buffers when building strings in loops
DERBY-5070 | [patch] remove unused fetching of data dictionary
DERBY-5069 | Since Feb 7,2011 weme 6.2 Junit tests have failed to run completely with Failed to invoke suite():java.lang.reflect.InvocationTargetException
DERBY-5067 | Performance regression tests should populate tables before creating indexes
DERBY-5063 | Embedded driver allows updateBytes() on BOOLEAN column
DERBY-5062 | [patch] push code assignments down to where they are used - part 2
DERBY-5060 | [patch] use collection apis
DERBY-5056 | Incorrect statement in reference manual about memory requirement when streaming columns
DERBY-5055 | [patch] add visibility to static method calls
DERBY-5054 | [patch] better npe handling in exceptional case
DERBY-5053 | [patch] reduce superfluous boxing histrionics
DERBY-5052 | [patch] Bad name collision causes non functional method
DERBY-5051 | Update the docs to include the additional information available in derby.log. This information will be useful from product supportability stand point
DERBY-5050 | BrokeredConnection could call setHoldability() without using reflection
DERBY-5047 | Documentation links to java.sun.com should be updated
DERBY-5046 | Intermittent assert failure in AutomaticIndexStatisticsTest.testStatisticsCorrectness
DERBY-5045 | Assert failures in UpdateStatisticsTest
DERBY-5043 | Document the new url attribute deregister to keep the AutoloadedDriver registers in DriverManager
DERBY-5042 | ResultSet.updateBoolean() on new BOOLEAN type throws exception
DERBY-5040 | On Windows, cascade of errors after failed test AutomaticIndexStatisticsTest
DERBY-5039 | store/updatelocksJDBC30.sql test failing in tinderbox when background update statistics are enabled.
DERBY-5038 | updatelocks test failing in tinderbox when background update statistics are enabled.
DERBY-5037 | Assertion failure from index-stat-thread when running AutomaticIndexStatisticsTest
DERBY-5036 | [patch] fix impossible comparison due to sign extension
DERBY-5034 | [patch] bad field masking makes non functional rowsInput evaluation
DERBY-5033 | [patch] System.arraycopy, being native, is more performant
DERBY-5032 | [patch] derived InternalXact attempts (and fails) to override a method from base
DERBY-5029 | getParentLogger() won't work after the engine has been shut down once
DERBY-5028 | InterruptResilienceTest passes with IBM 1.6 SR9 but creates javacore dumps
DERBY-5024 | Document the behavior of interrupt handling.
DERBY-5023 | Cannot find Ant libraries when building from NetBeans
DERBY-5022 | [patch] override equals correctly
DERBY-5021 | [patch] avoid map look ups in a loop by using entrySet
DERBY-5020 | [patch] remove redundant finalizer methods
DERBY-5019 | [patch] quiet the ant build with 1.8.1+
DERBY-5018 | [patch] remove erroneous throws clauses on non derivable methods that don't throw
DERBY-5017 | [patch] push code assignments down to where they are used
DERBY-5015 | Use Arrays.fill() in client/am/ResultSet.java
DERBY-5013 | [patch] remove dead allocation
DERBY-5012 | [patch] bad allocation guard in ResultSet#resetUpdatedColumnsForInsert
DERBY-5011 | [patch] Client driver lexer to determine statement type: fix bad attempt at incrementing a variable
DERBY-5009 | [patch] RelaseNotesTransformer: make proper string replacements for forrest
DERBY-5008 | [patch] fix npe in error condition
DERBY-5005 | Error when fully qualifying a field from a view in an ORDER BY clause
DERBY-5004 | Typo in column name "HASH_KEY_COLUMN_NUMBER" in SYSXPLAIN_SCAN_PROPS system table documentation
DERBY-5002 | In case of checksum error, insure correct error reported to user.
DERBY-5001 | Intermittent bug in InterruptResilienceTest
DERBY-5000 | The Derby properties section in the reference manual should provide hint about where to find server specific properties.
DERBY-4999 | Docs build fails under C locale
DERBY-4997 | SysinfoTest version output filtering is fragile with new java versions
DERBY-4995 | Docs build creates extraneous devguide directory
DERBY-4992 | Release notes should specify which Java version is needed to run Derby
DERBY-4991 | The derby security policy in the Admin Guide is stale.
DERBY-4990 | Documentation should state a custom security policy being required to use LDAP in conjunction with network driver
DERBY-4988 | ALTER TABLE DROP COLUMN should make use of information in SYSTRIGGERS to detect column used through REFERENCING clause to find trigger dependencies
DERBY-4987 | BootLockTest can hang reading spawned process output
DERBY-4986 | Document the new property derby.stream.error.extendedDiagSeverityLevel for thread dump and extend diagnostic information
DERBY-4985 | BootLockTest can fail with ERROR XCY03: Required property 'derby.serviceProtocol' has not been set with slow configurations
DERBY-4983 | failure in jdbcapi.StatementJdbc20Test:testCompletionClosure_jdbc4_1 with j9 (j2ME/CDC)
DERBY-4982 | Retrying after interrupts in store pops a bug in derbyall/storeall/storeunit/T_RawStoreFactory in some cases
DERBY-4980 | Replication tests lose derby.log for slave
DERBY-4979 | build.properties in plugins/eclipse/org.apache.derby.ui refers to non-existent file install_plugin.html
DERBY-4978 | Document the new SQLPermission required by the JDBC 4.1 Connection.abort(Executor) method
DERBY-4974 | InterruptResilienceTest fails on Solaris with Sun VMs prior to 1.6
DERBY-4973 | NullPointerException in updatelocks.sql encryption tests on IBM 1.6
DERBY-4970 | ClassCastException from getBlob() on string parameter
DERBY-4968 | Let query stop execution if an interrupt is seen, at same time as we check the query timeout
DERBY-4967 | Handle interrupt received while waiting for database lock
DERBY-4965 | Boolean to char conversion results in integer
DERBY-4964 | Client driver fails to convert string to boolean with setObject(col, str, Types.BIT)
DERBY-4963 | Revert to FileDescriptor#sync from FileChannel#force to improve interrupt resilience
DERBY-4960 | Race condition in FileContainer#allocCache when reopening RAFContainer after interrupt
DERBY-4959 | NPE in network server trying to return a null LOB as a procedure output arg
DERBY-4958 | Wrapper types not recognized when resolving procedures with OUT arguments.
DERBY-4951 | test failure in jdbc4.ResultSetTest:testJDBC4_1 with ibm 1.6 jvm
DERBY-4950 | AccessControlException when running AssertFailureTest from Ant
DERBY-4949 | Backward, confusing error message when you use the wrong ResultSet.getXXX() method in the client driver
DERBY-4948 | Inconsistent casing of IPv4/IPv6 in admin guide
DERBY-4947 | Missing/broken synchronization in BasicDependencyManager.getDependents()
DERBY-4946 | Derby 10.7 DatabaseMetaData.getTypeInfo() should not return BOOLEAN for a soft upgraded database
DERBY-4944 | Embedded Derby does not start when derby.jar is dynamically uploaded / added to the classpath
DERBY-4943 | TRUNCATE TABLE docs should state that it doesn't work for temporary tables
DERBY-4942 | Describe how to run compatibility tests from JUnit in README
DERBY-4941 | Invalid example URL in German help text for dblook
DERBY-4939 | Enable istat daemon and tests
DERBY-4938 | Implement istat scheduling/triggering
DERBY-4937 | Enable explicit mode istat daemon code for UPDATE_STATISTICS
DERBY-4936 | Add core istat daemon
DERBY-4935 | Add initial istat tests
DERBY-4933 | Use framework helper methods to check result sets in DatabaseMetaDataTest
DERBY-4932 | Move the StringColumnVTI to the public api
DERBY-4929 | Engine code should not use java/shared/org/apache/derby/shared/common/error/ErrorUtil.java
DERBY-4928 | Deadlock-prone synchronization in BasicDependencyManager
DERBY-4920 | suites.All stuck in RAFContainer4.awaitRestoreChannel()
DERBY-4918 | Minor refactoring of SPSDescriptor
DERBY-4915 | test failure in OSReadOnlyTest in assertDirectoryDeleted
DERBY-4913 | 10.3 to 10.5 upgrade fails with ava.io.StreamCorruptedException: java.lang.ClassCastException: org.apache.derby.catalog.types.OldRoutineType incompatible with org.apache.derby.iapi.types.DataTypeDescriptor
DERBY-4912 | Instability in Derby2017LayerBTest
DERBY-4910 | Four replication tests fail on z/OS with junit.framework.AssertionFailedError: startMaster did not succeed.
DERBY-4907 | EmbeddedXADataSource with ;create=true attribute set in setDatabaseName fails with java.sql.SQLException: Database not available
DERBY-4897 | Get rid of warning for customized tags in javadoc build
DERBY-4856 | Add thread dump information when derby crash
DERBY-4853 | log derby.properties location and derby.log location to derby.log
DERBY-4837 | Prepare lang.UpdateStatisticsTest for automatic index statistics generation
DERBY-4771 | Continue investigation of automatic creation/update of index statistics
DERBY-4741 | Make embedded Derby work reliably in the presence of thread interrupts
DERBY-4727 | Document derby.stream.error.logBootTrace=true diagnostic property
DERBY-4713 | Subclasses of ScriptTestCase can not run correctly with the non-English default locale
DERBY-4691 | The Reference Guide should say that SYSCOLPERMS.COLUMNS and SYSCOLUMNS.COLUMNDEFAULT are not part of Derby's public api
DERBY-4656 | eclipse ui/doc plugin 1.1.2 was built with 1.6 jvm, results in "The chosen operation is not currently available" on Add Derby Nature with 1.5 jvms
DERBY-4614 | JDBC metadata gives incorrect lengths for timestamps
DERBY-4589 | Corrupted database prevents startup and should be automatically repaired perhaps
DERBY-4573 | Reference manual is unclear about the purpose of REFERENCEDCOLUMNS in SYSTRIGGERS table.
DERBY-4544 | Referencing streaming CLOBs in (some) generated column clauses fails
DERBY-4540 | 'AssertionFailedError' in 'store.AccessTest.testCS4595B_UniqueIndex(AccessTest.java:1729)' on SUSE Linux / IBM JIT - r9
DERBY-3980 | Conflicting select then update with REPEATABLE_READ gives lock timeout instead of deadlock
DERBY-3788 | Provide a zero-admin way of updating the statisitcs of an index
DERBY-3258 | 'Unexpected row count: expected:<0> but was:<3>' in testReleaseCompileLocks
DERBY-3009 | Out of memory error when creating a very large table
DERBY-2949 | AssertionFailedError in testStalePlansOnLargeTable
DERBY-2905 | Shutting down embedded Derby does not remove all code, the AutoloadDriver is left registered in the DriverManager.
DERBY-2739 | Use DOM interfaces to implement XML operators
DERBY-2515 | Network client does not retain the INOUT parameter value change for subsequent execution
DERBY-2354 | Unable to perform select query using DISTINCT on a read-only database
DERBY-642 | SELECT MAX doesn't use indices optimally

## Issues

Compared with the previous release (10.7.1.1), Derby release 10.8.1.2 introduces the following new features and incompatibilities. These merit your special attention.

- Note for DERBY-5121: In Derby 10.7.1.1, update triggers with REFERENCING clauses can corrupt data. Users are urged to upgrade to the next release in the 10.7 family or to 10.8.

- Note for DERBY-4965: The JDBC-level conversion from BOOLEAN to CHAR has changed.

- Note for DERBY-4963: Interrupt resilience may degrade the performance of writes on some platforms.

- Note for DERBY-4939: Index cardinality statistics are updated automatically.

- Note for DERBY-4856: Diagnostics for system crashes and session errors have been expanded.

- Note for DERBY-4614: JDBC metadata reports longer precision and scale for Timestamps.

- Note for DERBY-2905: Engine shutdown now unregisters the embedded JDBC driver.

- Note for DERBY-2739: The requirements for XML operators have changed.

### Note for DERBY-5121

#### Summary of Change

In Derby 10.7.1.1, update triggers with REFERENCING clauses can corrupt data. Users are urged to upgrade to the next release in the 10.7 family or to 10.8.

#### Symptoms Seen by Applications Affected by Change

In Derby 10.7.1.1, UPDATE triggers which use the REFERENCING clause can be confused about which columns to pass to their triggered actions. This can silently corrupt data manipulated by the triggered actions.

#### Incompatibilities with Previous Release

Derby 10.7.1.1 is the only release whose triggers corrupt data this way. Upgrading to a later 10.7 release or to 10.8 will recompile these triggers correctly. Applications should check for data corruption if they used 10.7.1.1 to create UPDATE triggers with the REFERENCING clause.

#### Rationale for Change

This change was made in order to fix a data corruption problem caused by UPDATE triggers with REFERENCING clauses.

### Note for DERBY-4965

#### Summary of Change

The JDBC-level conversion from BOOLEAN to CHAR has changed.

#### Symptoms Seen by Applications Affected by Change

In previous releases of Derby, when using `PreparedStatement.setObject()` or `PreparedStatement.setBoolean()` to initialize a character type parameter (CHAR, VARCHAR, etc.) with a boolean value, the parameter would be set to the value "1" or "0" for `true` or `false`, respectively.

#### Incompatibilities with Previous Release

In this release, `PreparedStatement.setObject()` and `PreparedStatement.setBoolean()` will convert the boolean values `true` and `false` to the strings "true" and "false", respectively, if the type of the parameter is one of the character types.

#### Rationale for Change

The previous behavior caused failures in a JDBC compliance test after Derby's meta-data started reporting that the BOOLEAN data type was supported in version 10.7.1.1.

#### Application Changes Required

If the application expects the parameter to be set to "1" or "0" instead of "true" or "false", it must be recoded to explicitly set the parameter to an integer value.

For example, if an application uses setBoolean() to set a character type parameter, it could be changed from

    ps.setBoolean(col, b);

to

    ps.setInt(col, b ? 1 : 0);

in order to preserve the old behavior.

### Note for DERBY-4963

#### Summary of Change

Interrupt resilience may degrade the performance of writes on some platforms.

#### Symptoms Seen by Applications Affected by Change

In Derby 10.8, INSERTs and UPDATEs may run slower on platforms which do not support write synchronization. Affected platforms include JDK 1.4.0 and JDK 1.4.1 (on all operating systems) and Java 5 (on Mac OSX and BSD variants).

#### Incompatibilities with Previous Release

On some platforms, INSERTs and UPDATEs may run slower than they did in previous Derby releases. Changes needed for interrupt resilience may cause extra io calls on platforms which do not support the "rws"/"rwd" modes in the constructor for RandomAccessFile(File,String)

#### Rationale for Change

Derby's log flushing logic was changed to prevent Thread interrupts from crashing the engine.

#### Application Changes Required

Upgrade the JVM to JDK 6 or higher if your application suffers slower INSERTs/UPDATEs after upgrading to Derby 10.8.

### Note for DERBY-4939

#### Summary of Change

Index cardinality statistics are updated automatically.

#### Symptoms Seen by Applications Affected by Change

During query compilation, Derby now checks if the index cardinality statistics for the tables involved in the query are out of date. If the statistics are outdated, the query compiler will schedule a job that updates them in a separate thread. The thread that updates the statistics in the background may affect the performance of the user threads.

#### Incompatibilities with Previous Release

This release of Derby may cause more threads to be running than previous releases did. These threads may use resources also needed by the user threads (for example, disk bandwidth, CPU or locks on system tables) and thereby interfere with the execution in the user threads.

#### Rationale for Change

Derby's optimizer will often choose query execution plans that yield bad performance if the index cardinality statistics are out of date.

#### Application Changes Required

If the automatic updating of index cardinality statistics causes problems, the application can disable it by setting the database property `derby.storage.indexStats.auto=false`.

To diagnose problems with automatic updating of index statistics, the application may set the database property `derby.storage.indexStats.log=true`. When this property is set, the thread that updates the statistics will write messages to the Derby system log (derby.log) every time it performs a task.

### Note for DERBY-4856

#### Summary of Change

Diagnostics for system crashes and session errors have been expanded.

#### Symptoms Seen by Applications Affected by Change

After a severe error (system crash or session error), the Derby error log will snapshot stack traces for all threads. On IBM JVMs these errors will produce a javacore file too.

To obtain thread dumps and diagnostics for less severe errors, adjust the derby.stream.error.extendedDiagSeverityLevel property as described in the Setting system-wide properties section of the Derby Developer's Guide. Please consult the Derby documentation for explanations of error severities and the other possible settings of extendedDiagSeverityLevel.

For example, to obtain this extra information while diagnosing deadlocks, set `derby.stream.error.extendedDiagSeverityLevel=30000`. Then deadlocks will dump thread stacks into the Derby error log.

#### Incompatibilities with Previous Release

None.

#### Rationale for Change

This change gives DBAs and tech support engineers more information to help them diagnose errors and crashes.

#### Application Changes Required

No application changes are required. To disable this feature, simply set the derby.stream.error.extendedDiagSeverityLevel property to the value 50001.

### Note for DERBY-4614

#### Summary of Change

JDBC metadata reports longer precision and scale for Timestamps.

#### Symptoms Seen by Applications Affected by Change

Previously, JDBC metadata calls reported that Derby Timestamps had precision 26 and scale 6. Now the precision of Timestamps is 29 and the scale is 9. The following metadata were corrected:

- DatabaseMetaData.getTypeInfo() - The PRECISION and MINIMUM_SCALE fields were wrong.
- DatabaseMetaData.getColumns() - The COLUMN_SIZE and DECIMAL_DIGITS fields were wrong.
- DatabaseMetaData.getProcedureColumns() - The PRECISION and SCALE fields were wrong.
- DatabaseMetaData.getFunctionColumns() - The PRECISION and SCALE fields were wrong.
- ResultSetMetaData - Wrong results came back from the getColumnDisplaySize(), getPrecision(), and getScale() methods.
- ParameterMetaData - Wrong results came back from the getPrecision() and getScale() methods.

#### Incompatibilities with Previous Release

Applications which rely on JDBC metadata to determine the length of Timestamps will now display longer Timestamps.

#### Rationale for Change

The metadata was changed to reflect the actual precision and scale of Derby Timestamps, which are simply instances of java.sql.Timestamp.

#### Application Changes Required

Applications, which consulted JDBC metadata in order to determine the length of Timestamps, should be tested (and if necessary recoded) to verify that they correctly handle the longer lengths.

### Note for DERBY-2905

#### Summary of Change

Engine shutdown now unregisters the embedded JDBC driver.

#### Symptoms Seen by Applications Affected by Change

In release 10.1, orderly engine shutdown unregistered the embedded JDBC driver, allowing the JVM to garbage-collect the Derby classes. Later releases (10.2 through 10.7) did not unregister the driver. 10.8 revives the 10.1 behavior. In 10.8, orderly engine shutdown unregisters the embedded JDBC driver.

After the embedded driver has been unregistered, it must be re-registered in order to obtain a new Connection to Derby. Re-registration occurs when the application invokes the following statement:

`Class.forName("org.apache.derby.jdbc.EmbeddedDriver").newInstance();`

It is also possible for an application to request orderly shutdown without unregistering the embedded driver. After such a shutdown it is not necessary to re-register the embedded driver. To request this kind of shutdown, the application needs to add `deregister=false` to the end of the shutdown URL. For more information on this feature, please see the section on the deregister attribute in the Derby Reference Manual.

#### Incompatibilities with Previous Release

None.

#### Rationale for Change

The 10.1 behavior has been revived so that the JVM can garbage-collect the Derby classes after orderly engine shutdown.

#### Application Changes Required

Applications no longer need to call `DriverManager.deregister(driver)` in order to enable garbage-collection of the Derby classes after orderly engine shutdown.

### Note for DERBY-2739

#### Summary of Change

The requirements for XML operators have changed.

#### Symptoms Seen by Applications Affected by Change

After upgrading to Derby 10.8, applications may fail if they use the XMLPARSE, XMLSERIALIZE, XMLQUERY, and XMLEXISTS operators. Using those operators may raise the following error message:

    ERROR XML00: Failed to locate 'XPath 3.0' API or implementation classes.  XML operations are not permitted unless these classes are in your classpath.

This happens if the classpath doesn't include the DOM Level 3 XPath interfaces or an implementation of those interfaces.

#### Incompatibilities with Previous Release

On Java 5 and earlier JVMs, the XMLPARSE, XMLSERIALIZE, XMLQUERY, and XMLEXISTS operators may fail as described above.

#### Rationale for Change

Previous releases of Derby required a recent version of Apache Xalan-Java in order to support the XML operators. Since not all platforms include Apache Xalan-Java, and some platforms contain a modified version with a different interface, these operators didn't work out of the box on many platforms.

In this release, the XML operators access the platform's XML libraries via the javax.xml and org.w3c.dom interfaces instead of accessing the Xalan implementation classes directly. This change makes the XML operators work out of the box on most Java SE 6 or later platforms, but may break the functionality on older platforms that don't contain all the required interfaces.

#### Application Changes Required

In environments affected by this change, the XML operators can be fixed by upgrading the JVM (IBM's versions 1.5.0 and 1.6.0 and Oracle's version 1.6.0 are known to work) or by installing a recent version of Apache Xalan-Java.

Installation of Xalan-Java may require the Endorsed Standards Override Mechanism. This is described in the "XML data types and operators" section of the Derby Developer's Guide.

## Build Environment

Derby release 10.8.1.2 was built using the following environment:

- Branch - Source code came from the 10.8 branch.
- Machine - Mac OS X 10.5.8.
- Ant - Apache Ant version 1.7.1 compiled on June 27 2008.
- JDK 1.4 - Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_22-b02-329).
- Java 6 - Java(TM) SE Runtime Environment (build 1.6.0_17-b04-248-9M3125).
- Compiler - The 1.6.0_17-b04-248-9M3125 javac was used to compile all classes.
- JSR 169 - Java ME support was built using libraries from phoneME Advanced Milestone Release 2.

## Verifying Releases

It is essential that you verify the integrity of the downloaded files using the PGP and MD5 signatures. MD5 verification ensures the file was not corrupted during the download process. PGP verification ensures that the file came from a certain person.

The PGP signatures can be verified using PGP or GPG. First download the Apache Derby KEYS as well as the `asc` 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 ...

    % pgpk -a KEYS
    % pgpv db-derby-X.Y.tar.gz.asc

    or

    % pgp -ka KEYS
    % pgp db-derby-X.Y.tar.gz.asc

    or

    % gpg --import KEYS
    % gpg --verify db-derby-X.Y.tar.gz.asc

To verify the MD5 signature on the files, you need to use a program called `md5` or `md5sum`, which is included in many unix distributions. It is also available as part of GNU Textutils. Windows users can get binary md5 programs from here, here, or here.

We strongly recommend that you verify your downloads with both PGP and MD5.