This document describes how to upgrade to a new version of Kodo from the prior version. When skipping versions, please follow the steps outlined as though you are converting to each intermediate version.
The sections below detail specific steps to switch from one Kodo release
to another. Kodo also offers backwards compatibility settings for
certain runtime behaviors, encompassed in the
kodo.Compatibility
property. This property uses Kodo's
plugin syntax to control
the following options:
ValidateFalseReturnsHollow
: Whether to return
hollow objects (objects for which no state has been loaded) from
calls to PersistenceManager.getObjectById(oid,
false)
. This is the default behavior of Kodo 4.0
and above. Previous Kodo versions, however, always loaded
the object from the datastore. Set this property to
false
to get the old behavior.
ValidateTrueChecksStore
: Prior to Kodo 4.0,
calling PersistenceManager.getObjectById(oid,
true)
always checked the datastore to be sure the
given oid existed, even when the corresponding object was
already cached. Kodo 4.0 and above does not check the
datastore when the instance is already cached and loaded. Set
this property to true
to mimic
previous behavior.
CopyObjectIds
: Kodo versions prior to 3.0
always copied oid objects before returning them to you. This
prevents possible errors resulting from you mutating the oid
object by reference, but wasn't very efficient for the majority
of users who don't modify oid instances. Thus Kodo 3.0 and
higher does not copy oids by default. Set this property to
true
to force Kodo to copy.
CloseOnManagedCommit
: If
true
, then the JDO PersistenceManager
will close after a managed transaction
commits, assuming you have invoked the
close
method. If this is set to
false
, then the
PersistenceManager
will not close. This means
that objects passed to a processing tier in the same JVM
will still be usable, as their owning
PersistenceManager
will still be open. This
behavior is not in strict compliance with the JDO
specification, but is convenient for applications that
were coded against Kodo 2.x, which did not close the
PersistenceManager
in these situations. The default for this property
is true
, meaning that the
PersistenceManager
will close properly.
QuotedNumbersInQueries
: Whether to interpret
quoted numbers in query strings as numbers, as opposed to
strings. Defaults to treating quoted numbers as strings. Set
to true
to treat quoted numbers as numbers
instead to mimic the behavior of Kodo 3.1 and prior.
StrictIdentityValues
: Whether to require
identity values used for finding application identity instances
to be of the exact right type. By default, Kodo allows
stringified identity values, and performs conversions between
numeric types.
NonOptimisticVersionCheck
: Whether
or not to perform a version check on instances to be
updated when a non-optimistic transaction is commited.
Defaults to false
, meaning that
an dirty instance enlisted in a datastore transaction
will not have its version columns (if any) validated
upon commit, although those version columns will still
be updated with the new values. This behavior is new
as of Kodo 4.1. Setting it to true
will mimic pre-4.1 behavior, which is to always
update version columns when dirty instances are
flushed to the datastore.
For example, the setting below cause Kodo to copy oids and not to return hollow objects:
JPA XML format:
<property name="kodo.Compatibility" value="ValidateFalseReturnsHollow=false, CopyObjectIds=true">
JDO properties format:
kodo.Compatibility: ValidateFalseReturnsHollow=false, CopyObjectIds=true