DataNucleus Migration Guide (v6.0)

This version of DataNucleus AccessPlatform builds on the v5.x release, adding future flexibility. All releases are checked regularly against the JDO TCK and JPA1 TCK, meaning that DataNucleus is always stable in terms of functionality. Occasionally, due to unknown bugs, or due to new functionality being introduced we need to change some aspects of DataNucleus. As a result sometimes users will have to make some changes to move between versions of DataNucleus. We aim to keep this to a minimum.

Migration to v6.0

Migration to 6.0 involves the following steps

Migration from 6.0.0.M3 to 6.0.0.M4

Migrating will require the following changes.

  • Persistence property datanucleus.rdbms.fetchUnloadedAutomatically is now removed and replaced by datanucleus.rdbms.autoFetchUnloadedBasicFields and datanucleus.rdbms.autoFetchUnloadedFKs.

  • Persistence property datanucleus.jmxType has had its value "default" changed to "platform".

Migration from 6.0.0.M2 to 6.0.0.M3

Migrating will require the following changes.

  • org.datanucleus.state.ObjectProvider is now renamed to org.datanucleus.state.DNStateManager

  • Cassandra plugin now supports Cassandra v4. Use DN 5.2 if using Cassandra v3

  • DateStringConverter had to be changed for Java 11. If using it, create your own converter that understands the old format.

  • CalendarStringConverter had to be changed for Java 11. If using it, create your own converter that understands the old format.

  • Multitenancy is now changed to be explicit class-specified, rather than global.

Migration from 6.0.0.M1 to 6.0.0.M2

Migrating will require the following changes.

  • MongoDB connection URLs have been changed to use MongoDB’s own connection URL string format.

  • The RDBMS persistence property datanucleus.rdbms.statementLogging has had its default and values changed (see the docs)

Migration from 5.2.x to 6.0.0.M1

Migrating will require the following changes.

  • Rename datanucleus.generateSchema.database.mode to datanucleus.schema.generateDatabase.mode

  • Rename datanucleus.generateSchema.scripts.create.source to datanucleus.schema.generateDatabase.createScript

  • Rename datanucleus.generateSchema.scripts.drop.source to datanucleus.schema.generateDatabase.dropScript

  • Rename datanucleus.generateSchema.create.order to datanucleus.schema.generateDatabase.create.order

  • Rename datanucleus.generateSchema.drop.order to datanucleus.schema.generateDatabase.drop.order

  • Rename datanucleus.generateSchema.scripts.mode to datanucleus.schema.generateScripts.mode

  • Rename datanucleus.generateSchema.scripts.create.target to datanucleus.schema.generateScripts.create

  • Rename datanucleus.generateSchema.scripts.drop.target to datanucleus.schema.generateScripts.drop

  • Rename datanucleus.generateSchema.scripts.load to datanucleus.schema.loadScript

Migration to v5.2

Migration to 5.2 involves the following steps

Migration from 5.2.4 to 5.2.5

Migrating will require the following changes.

  • The query extension datanucleus.jdoql.strict is renamed to datanucleus.query.jdoql.strict and is also now valid as a persistence property.

  • The query extension datanucleus.jpql.strict is renamed to datanucleus.query.jpql.strict and is also now valid as a persistence property.

  • The query extension datanucleus.sql.syntaxChecks is renamed to datanucleus.query.sql.syntaxChecks and is also now valid as a persistence property.

  • The Proxool connection pool library is no longer supported.

Migration from 5.2.2 to 5.2.3

Migrating will require the following changes.

  • PostgreSQL handling of JDBC "CLOB" type has changed to reflect the fact that PostgreSQL simply uses a "large string" (text) column. The default column mapping is now changed to use a LongVarcharColumnMapping from ClobColumnMapping. Use the column extension "column-mapping-class" set to "org.datanucleus.store.rdbms.mapping.column.ClobColumnMapping" if you want old handling.

  • PostgreSQL handling of JDBC "BLOB" type has changed to reflect the fact that PostgreSQL simply uses a "large binary" (bytea) column. The default column mapping is now changed to use a LongVarBinaryColumnMapping from BlobColumnMapping. Use the column extension "column-mapping-class" set to "org.datanucleus.store.rdbms.mapping.column.BlobColumnMapping" if you want old handling.

Migration from 5.1.10 to 5.2.0.M1

Migrating will require the following changes.

  • The plugin extension point "org.datanucleus.store.rdbms.datastore_mapping" has been changed to "org.datanucleus.store.rdbms.column_mapping".

  • The (RDBMS) metadata extension "datastore-mapping-class" has been changed to "column-mapping-class".

  • Classes previously under org.datanucleus.store.rdbms.mapping.datastore are moved to org.datanucleus.store.rdbms.mapping.column.

Migration to v5.1

Migration to 5.1 involves the following steps

Migration from 5.1.8 to 5.1.9

Migrating will require the following changes.

  • When refreshing schema table information (from the database), we previously just refreshed the schema information for all known tables in one call. We now default to just refreshing the schema table information for the requested table. Use persistence property datanucleus.rdbms.refreshAllTablesOnRefreshColumns set to true to get previous behaviour.

Migration from 5.1.7 to 5.1.8

Migrating will require the following changes.

  • The default for which JDO XML file locations will be supported has changed. It is now just the locations in the JDO 3.2 spec. To support XML locations from the JDO 1.0.0 spec (which were later removed from JDO) you need to specify persistence property datanucleus.metadata.xml.allowJDO1_0 as true.

Migration from 5.1.0-RELEASE to 5.1.1

Migrating will require the following changes.

  • The "org.datanucleus.store.rdbms.datastore_mapping" extension point values no longer supports the priority attribute. This is to facilitate providing "built-in" values directly in the RDBMS plugin rather than always loading from the plugin mechanism. Either contribute pull requests to the datanucleus-rdbms plugin if wanting to support types better, or make use of the DatastoreAdapter.registerDatastoreMapping method to manually register your datastore mappings.

Migration from 5.1.0-M4 to 5.1.0-RELEASE

Migrating will require the following changes.

  • The extension point "org.datanucleus.management_server" has been removed.

  • The extension point "org.datanucleus.store_query_query" has been removed and embodied in the XXXStoreManager.

  • The RDBMS connection pool "DBCP" (v1) is now removed.

Migration from 5.1.0-M3 to 5.1.0-M4

Migrating will require the following changes.

  • The persistence property datanucleus.datastoreTransactionFlushLimit is renamed to datanucleus.flush.auto.objectLimit.

  • SwarmCache L2 cache is now removed.

  • The persistence property datanucleus.cache.level2.timeout is renamed to datanucleus.cache.level2.expireMillis.

Migration from 5.1.0-M2 to 5.1.0-M3

Migrating will require the following changes.

  • An error was found in the default naming of a table for a class, so that it should use the entity name, meaning that anyone who relied on these previous namings (when overriding the entity name) should set the table/column names in mapping information to be safe.

Migration from 5.1.0-M1 to 5.1.0-M2

Migrating will require the following changes.

  • If you are using a user-defined PK class that has a field targetClassName then be aware that this is now interpreted as holding the fully-qualified class name of the object that the PK represents. If you want to store something else in this field then rename it to something else.

Migration from 5.0.6 to 5.1.0-M1

Migrating will require the following changes.

  • Bytecode enhancement contract changes slightly so re-enhance all classes prior to using this version

  • The persistence property datanucleus.nontransactionalRead is renamed to datanucleus.transaction.nontx.read

  • The persistence property datanucleus.nontransactionalWrite is renamed to datanucleus.transaction.nontx.write

  • The persistence property datanucleus.nontx.atomic is renamed to datanucleus.transaction.nontx.atomic

  • The persistence property datanucleus.transactionType is renamed to datanucleus.transaction.type

  • The persistence property datanucleus.transactionIsolation is renamed to datanucleus.transaction.isolation

  • The persistence property datanucleus.jtaLocator is renamed to datanucleus.transaction.jta.transactionManagerLocator

  • The persistence property datanucleus.jtaJndiLocation is renamed to datanucleus.transaction.jta.transactionManagerJNDI

  • The extension point "org.datanucleus.store.rdbms.connectionprovider" allowing a simple form of failover is now removed (previously enabled by specifying datanucleus.ConnectionFactoryName as a comma-separated list of JNDI names).

  • The extension point "org.datanucleus.store_objectvaluegenerator" was never used and is now removed.

  • The persistence property datanucleus.storeManagerType is no longer used, and uses the ConnectionURL to determine the datastore type, otherwise falls back to RDBMS

  • A couple of errors in the default naming of join tables and its column names were fixed, meaning that anyone who relied on these previous namings should set the table/column names in mapping information to be safe.

Migration to v5.0

Migration to 5.0 involves the following steps

Migration from 5.0.5 to 5.0.6

Migrating will require the following changes.

  • Default JDBC type for java Serialized fields for SQLServer is changed to VARBINARY from LONGVARBINARY.

Migration from 5.0.4 to 5.0.5

Migrating will require the following changes.

  • Support for the McKoi RDBMS database has been removed. The McKoiAdapter is still present in GitHub if requiring this.

  • The MSSQLServerAdapter for support of SQLServer RDBMS databases has been renamed to SQLServerAdapter.

Migration from 5.0.3 to 5.0.4

Migrating will require no changes.

Migration from 5.0.2 to 5.0.3

Migrating will require the following changes.

  • The JPA spec implies that when you specify SINGLE-TABLE inheritance for a tree then a discriminator will be used. DataNucleus previously left it to a user to define the discriminator, but now adds it for them. See persistence property datanucleus.metadata.useDiscriminatorForSingleTable (set to false) to get old behaviour

  • The JPA spec implies that if no discriminator value(s) are provided then the provider should use entity-name. DataNucleus has not done this thus far, instead using class-name. We now swap to entity-name, but allow a persistence property datanucleus.metadata.useDiscriminatorClassNameByDefault that you can set to true to get old behaviour.

  • DatastoreAdapter method getRangeByLimitEndOfStatementClause now has an extra argument added, for people who are overriding an adapter

  • The builtin DBCP connection pool has been removed and replaced by a builtin DBCP2 connection pool. DBCP2 is recommended over DBCP for all JRE’s Java7+ so this switch was long overdue.

  • SchemaTool was changed to have options "createDatabase"/"deleteDatabase" instead of "createSchema"/"deleteSchema", and to accept the catalog as input. To be consistent the persistence property datanucleus.schema.autoCreateSchema is now renamed to datanucleus.schema.autoCreateDatabase.

Migration from 5.0.1 to 5.0.2

Migrating will require the following changes.

  • When mapping a field of type Map<PC,?> with the key being embedded into a join table, this would previously have added an extra column to be part of the PK of the join table (certainly for JPA). It no longer does this, and instead uses all fields of the key in the PK. You can get previous handling by specifying extension surrogate-pk-column to true on the metadata for the field.

Migration from 5.0.0.RELEASE to 5.0.1

Migrating will require the following changes.

  • Persistence property datanucleus.query.compileOptimiser renamed to datanucleus.query.compileOptimiseVarThis

Migration from 5.0.0.M5 to 5.0.0.RELEASE

Migrating will require the following changes.

  • "JCache" (javax.cache v0.1) is no longer supported. Use "javax.cache" instead.

  • Persistence property datanucleus.rdbms.adapter.informixUseSerialForIdentity renamed to datanucleus.rdbms.informix.useSerialForIdentity

  • Persistence property datanucleus.rdbms.oracleNlsSortOrder renamed to datanucleus.rdbms.oracle.nlsSortOrder

Migration from 5.0.0.M4 to 5.0.0.M5

Migrating will require the following changes.

  • Cassandra : requires Datastax v3.0+ now.

  • Refactor org.datanucleus.query.cache to org.datanucleus.query.compiler

  • Refactor org.datanucleus.query.symbol to org.datanucleus.query.compiler

  • Refactor org.datanucleus.store.encryption to org.datanucleus.store

  • Refactor org.datanucleus.store.scostore to org.datanucleus.store.types.scostore

  • Refactor org.datanucleus.store.exceptions to org.datanucleus.exceptions

Migration from 5.0.0.M2 to 5.0.0.M3

Migrating will require the following changes.

  • HBase : changed default storage of relations to use "persistableId" to be consistent with Cassandra, Neo4j, MongoDB, Excel, ODF, JSON etc. Use persistence property datanucleus.hbase.relationUsesPersistableId as false to get old storage method.

Migration from 5.0.0.M1 to 5.0.0.M2

Migrating will require the following changes.

  • The internal conversion mechanism for some java.time types has changed to improve timezone handling. If this causes issues with existing data, then extract the internal TypeConverter for DN 5.0.0.M1 and use that in your application.

  • JPQL "MONTH" function was changed to return (1, 12) rather than (0, 11). To obtain previous handling use the JPQL function "MONTH_JAVA".

  • REST : "/jdoql" URL now takes parameter "query={the_query}" rather than assuming the query string starts with it.

  • REST : "/jpql" URL now takes parameter "query={the_query}" rather than assuming the query string starts with it.

  • REST : "/query" URL is no longer supported, use /jdoql or /jpql.

Migration from 4.2.0.RELEASE to 5.0.0.M1

Migrating will require the following changes.

  • Java : The JRE must be Java8+ now.

  • Use javax.persistence v2.1.2+ if having problems with signatures of JPA EntityGraph "addAttributeNodes" method, since this fixes a bug in JPA2.1 (that should be fixed in JPA 2.2 one day).

Migration to v4.2

Migration to 4.2 involves the following steps

Migration from 4.2.0.M2 to 4.2.0.RELEASE

Migrating will require no changes.

Migration from 4.2.0.M1 to 4.2.0.M2

Migrating will require no changes.

Migration from 4.1.1 to 4.2.0.M1

Migrating will require the following changes.

Migration to v4.1

Migration to 4.1 involves the following steps

Migration from 4.1.1 to 4.1.2

Migrating will require the following changes.

  • JPA : The JPA extension annotation @DatastoreIdentity is renamed @DatastoreId

Migration from 4.1.0.M4 to 4.1.0.RELEASE

Migrating will require no changes.

Migration from 4.1.0.M3 to 4.1.0.M4

Migrating will require the following changes.

  • RDBMS : if persisting java.sql.Timestamp field as VARCHAR, the conversion method has changed slightly to pass a String to JDBC and not rely on JDBC drivers

  • RDBMS : new persistence property added "datanucleus.rdbms.useDefaultSqlType" with default value of true. This could impact on schema generation if your JDBC driver has multiple possible "sql-type" for a specific "jdbc-type". Set it to false if you want the previous (4.0, 4.1) behaviour.

Migration from 4.1.0.M2 to 4.1.0.M3

Migrating will require the following changes.

  • HikariCP : requires HikariCP v2.3.5+ if using that connection pool

Migration from 4.1.0.M1 to 4.1.0.M2

Migrating will require the following changes.

  • The query hint "datanucleus.multivaluedFetch" is renamed to datanucleus.rdbms.query.multivaluedFetch and also can be specified as a persistence property. It also now defaults to 'EXISTS' (meaning perform an EXISTS query for single SQL retrieval of a container field).

  • The metadata extension "adapter-column-name" for overriding the order column name in join tables has been removed - just use the column name within "order"

  • MongoDB : any fields of type java.sql.Time/java.sql.Date were previously defaulted to storing as String, yet now default to the internal MongoDB date type. Set "jdbcType" to "varchar" on all fields that need to be stored as String for backwards compatibility.

  • MongoDB : now require Mongo driver v2.13 or above (including v3)

  • Jodatime : now requires Jodatime v2.0+ (if using LocalDateTime support)

Migration from 4.0.4 to 4.1.0.M1

Migrating will require the following changes.

  • The bytecode enhancement contract has been revised slightly, so all classes will need re-enhancement for use with this release.

  • A query hint has been added "datanucleus.useIsNullWhenEqualsNullParameter" for particular use by JPA for compatibility. It defaults to false.

Migration to v4.0

Migration to 4.0 involves the following steps

Migration from 4.0.3 to 4.0.4

Migrating will require the following changes.

  • The default naming for JPA "element collection" tables has changed to make it consistent with the spec. If you had a table generated using the earlier default naming and want to keep that name then you should explicitly specify the table name in annoations/XML to avoid problems.

Migration from 4.0.2 to 4.0.3

Migrating should require no changes.

Migration from 4.0.1 to 4.0.2

Migrating will require the following changes.

  • JPA plugin handling of nulls allowed was not very predictable before and the code has been changed to work simpler. If you get a field that is now different to 4.0.1 or earlier then you should explicitly specify "allows-null".

Migration from 4.0.0.RELEASE to 4.0.1

Migrating will require the following changes.

  • For the Cassandra plugin, the default data type for UUID fields has changed from "text" to "uuid". If you have used UUID fields on v4.0.0-release you should specify jdbc-type as "varchar" in column metadata when migrating to 4.0.1.

Migration from 4.0.0.M4 to 4.0.0.RELEASE

Migrating will require the following changes.

  • For MongoDB, JSON, Neo4J, HBase the process for table/column naming has changed, particularly for embedded fields. This may result in slightly different default table/column names (for example, the case of the name). To avoid problems use the metadata to explicitly set the column names (or check that the new behaviour matches your expectations).

Migration from 4.0.0.M3 to 4.0.0.M4

Migrating will require the following changes

  • Fields of type Calendar were previously persisted using 2 columns (millisecs, timezone) by default. The default is now changed to use a single column (Timestamp). If you want 2 columns then either specify 2 column metadata for the field, or set the extension metadata calendar-one-column as false

  • The persistence properties datanucleus.localisation.language and datanucleus.localisation.messageCodes are removed. You can now specify either of these as Java system properties since they apply for the JVM as a whole.

  • All 'boolean' fields with JPA (when using annotations) were previously defaulted to use jdbc-type of SMALLINT for some reason. This is now changed to just use the DataNucleus default, and you can get the old behaviour by either specifying @JdbcType or by setting the persistence property datanucleus.jpa.legacy.mapBooleanToSmallint to true

Migration from 4.0.0.M2 to 4.0.0.M3

Migrating will require the following changes

  • The EclipsePluginRegistry is now removed, and anyone using OSGi should use OSGiPluginRegistry. Should this not provide for your requirements the EclipsePluginRegistry class is in DataNucleus GitHub for earlier releases so you could simply include it.

  • The bytecode enhancement contract has changed, so you should re-enhance any classes for use with this version of DataNucleus

  • The previously supported JDO metadata vendor-name="jpox" is now no longer supported. Set the vendor-name to datanucleus

Migration from 4.0.0.M1 to 4.0.0.M2

Migrating will require the following changes

  • Persistence property datanucleus.identifier.case value PreserveCase is now MixedCase

  • User mapping extensions are now not needed if there is a TypeConverter that does the conversion. Also the helper mapping classes ObjectAsStringMapping etc are now removed.

  • DataNucleus now uses ASM v5 so should, in principle, be Java8-ready (as well as backwards compatible). Report any problems in the normal way

  • ODF/Excel : The previously permitted extension of specifying the column "name" to be the position of that column is now no longer supported; specify the column 'position' attribute if wanting to specify the position.

Migration from 3.3.7 to 4.0.0.M1

Migrating will require the following changes

  • Persistence property datanucleus.allowAttachOfTransient now defaults to true for JPA usage; set it explicitly to get old behaviour

  • Persistence property datanucleus.metadata.validate was removed (replaced by datanucleus.metadata.xml.validate some time back)

  • Persistence property datanucleus.defaultInheritanceStrategy is renamed to datanucleus.metadata.defaultInheritanceStrategy

  • Persistence property datanucleus.autoCreateSchema is renamed to datanucleus.schema.autoCreateAll

  • Persistence property datanucleus.autoCreateTables is renamed to datanucleus.schema.autoCreateTables

  • Persistence property datanucleus.autoCreateColumns is renamed to datanucleus.schema.autoCreateColumns

  • Persistence property datanucleus.autoCreateConstraints is renamed to datanucleus.schema.autoCreateConstraints

  • Persistence property datanucleus.validateSchema is renamed to datanucleus.schema.validateAll

  • Persistence property datanucleus.validateTables is renamed to datanucleus.schema.validateTables

  • Persistence property datanucleus.validateColumns is renamed to datanucleus.schema.validateColumns

  • Persistence property datanucleus.validateConstraints is renamed to datanucleus.schema.validateConstraints

  • Persistence property datanucleus.fixedDatastore is now removed, since it only equated to setting the "autoCreate" properties to false.

Migration to v3.3

Migration to 3.3 involves the following steps

Migration from 3.3.6 to 3.3.7

Migrating will require the following changes

  • Persistence property datanucleus.jpa.findTypeConversion is now removed and replaced with datanucleus.findObject.typeConversion, defaulting to true

Migration from 3.3.5 to 3.3.6

Migrating will require the following changes

  • The spatial and awtgeom plugins have been merged, to be datanucleus-geospatial

Migration from 3.3.4 to 3.3.5

Migrating will require the following changes

  • RDBMS : where you have a query that has a collection member in the FetchPlan it previously would have been ignored. Now it is used to attempt a bulk-fetch of the collection. Since this is new functionality there may be cases where the syntax is not optimal; remove the collection field from the query FetchPlan to get the previous behaviour.

Migration from 3.3.3 to 3.3.4

Migrating will require the following changes

  • RDBMS : default mapping for Boolean/boolean java types is now JDBC type BOOLEAN for H2 database; previously this was unspecified so most likely fell back to CHAR for that database. Specify the jdbc-type explicitly if you want to have CHAR

Migration from 3.3.2 to 3.3.3

Migrating from AccessPlatform 3.3.2 to 3.3.3 will require the following changes

  • datanucleus-googlecollections plugin is now renamed to datanucleus-guava

Migration from 3.3.1 to 3.3.2

Migrating will require no changes except to internal API(s).

Migration from 3.3.0.RELEASE to 3.3.1

Migrating will require no changes except to internal API(s).

Migration from 3.3.0.M1 to 3.3.0.RELEASE

Migrating will require the following changes

  • DataNucleus @FetchGroup extension annotation for JPA is now dropped and people should use the official JPA 2.1 @NamedEntityGraph annotation instead (or XML equivalent of course)

Migration from 3.2.3 to 3.3.0.M1

Migrating will require the following changes

  • Now requires a compliant JPA 2.1 API jar. An official JPA 2.1 API jar is not yet available, but as a stop-gap there is a Eclipse javax.persistence v2.1.0 jar. If using the Maven plugin with JPA, note that you also require v3.3.0.m1 of that plugin

  • DataNucleus @Index extension annotation for JPA is now dropped and people should use the official JPA 2.1 @Index annotation instead (or XML equivalent of course)

Migration to v3.2

Migration to 3.2 involves the following steps

Migration from 3.2.8 to 3.2.9

Migrating will require the following changes

  • RDBMS : where you have a query that has a collection member in the FetchPlan it previously would have been ignored. Now it is used to attempt a bulk-fetch of the collection. Since this is new functionality there may be cases where the syntax is not optimal; remove the collection field from the query FetchPlan to get the previous behaviour.

Migration from 3.2.7 to 3.2.8

Migrating will require the following changes

  • RDBMS : default mapping for Boolean/boolean java types is now JDBC type BOOLEAN for H2 database; previously this was unspecified so most likely fell back to CHAR for that database. Specify the jdbc-type explicitly if you want to have CHAR

Migration from 3.2.6 to 3.2.7

Migrating from AccessPlatform 3.2.6 to 3.2.7 will require the following changes

  • datanucleus-googlecollections plugin is now renamed to datanucleus-guava

Migration from 3.2.2 to 3.2.3

Migrating will require the following changes

  • The persistence property datanucleus.metadata.validate is renamed to datanucleus.metadata.xml.validate to better describe its usage. The original name is still supported but you are advised to move to this new naming as the old one can be removed in a future release.

Migration from 3.2.1 to 3.2.2

Migrating will require no changes.

Migration from 3.2.0.RELEASE to 3.2.1

Migrating will require the following changes

  • The persistence property datanucleus.attachSameDatastore defaults to true with datanucleus-core version 3.2.1 and later. Set it to false if you require replicating objects into other datastores

  • The JDOQL method Date.getDay is now deprecated and Date.getDate should be used instead (day of the month). Date.getDay is likely to be converted to return the day of the week in a later release, so fixing any use of this now makes sense

  • PreparedStatement pooling is turned now turned OFF by default due to the fact that DBCP has a bug where it isn’t closing ResultSets correctly when this is enabled.

Migration from 3.2.0.M4 to 3.2.0.RELEASE

Migrating will require no changes.

Migration from 3.2.0.M3 to 3.2.0.M4

Migrating will require the following changes.

  • The RDBMS persistence property datanucleus.rdbms.sqlParamValuesInBrackets is now removed, and replaced by datanucleus.rdbms.statementLogging (see the docs)

  • The persistence property datanucleus.rdbms.useUpdateLock is now removed (was deprecated many releases back). Use standard JDO/JPA locking mechanisms instead.

  • Any user-defined RDBMS mapping plugins will need updating to match some minor type changes to the "datanucleus-rdbms" plugin API.

Migration from 3.2.0.M2 to 3.2.0.M3

Migrating will require no changes.

Migration from 3.2.0.M1 to 3.2.0.M2

Migrating will require the following changes.

  • The Maven plugin has been renamed to datanucleus-maven-plugin from maven-datanucleus-plugin to match Maven3 naming policies.

  • You no longer require to include asm.jar since version 4.1 of ASM is now repackaged into datanucleus-core.jar

  • Added persistence property "datanucleus.useImplementationCreator" to allow turning off the persistent interface implementation creator.

  • All java type mappings used by the RDBMS plugin are now moved from org.datanucleus.store.mapped.mapping in the core plugin, to org.datanucleus.store.rdbms.mapping.java in the RDBMS plugin. Related classes only for "mapped" datastores are also now in the RDBMS plugin

Migration from 3.1.x to 3.2.0.M1

Migrating will require the following changes.

  • The Enhancer plugin is now merged into "datanucleus-core". Note also that the "pre-compilation" enhancement process is now discontinued.

  • The Enhancer Ant task is now moved to org.datanucleus.enhancer.EnhancerTask

  • Various DataNucleus internal classes have been refactored. Please refer to this guide for details of upgrading DataNucleus internal API calls

  • Many "simple" Java field types now default to persistent (all supported types are now set to default persistent). Additionally many "simple" types default to being in the DFG whereas they used not to (i.e you had to enable the persistence of them, e.g java.sql.Date)

Migration to v3.1

Migration to 3.1 involves the following steps

Migration from 3.1.1 to 3.1.2

Migrating will require no changes.

Migration from 3.1.0.RELEASE to 3.1.1

Migrating will require no changes.

Migration from 3.1.0.M5 to 3.1.0.RELEASE

Migrating will require the following changes.

  • You no longer are required to specify the persistence property datanucleus.rdbms.stringDefaultLength as 255 for JDO; this is its new default

Migration from 3.1.0.M4 to 3.1.0.M5

Migrating will require no changes.

Migration from 3.1.0.M3 to 3.1.0.M4

Migrating will require the following changes.

  • The enhancer (v3.1) is now upgraded and requires ASM v4.0+. You can continue to use the v3.0 enhancer with ASM v3.x but that will not work completely with Java7

  • The RDBMS plugin now requires JDK1.6+ to run. Use v3.0 if you are still using Java5

Migration from 3.1.0.M2 to 3.1.0.M3

Migrating will require the following changes.

  • Persistence property datanucleus.managedRuntime replaced by datanucleus.jmxType defining the JMX server to use.

  • Persistence property datanucleus.datastoreTransactionDelayOperations is removed and replaced by datanucleus.flush.mode with values of MANUAL and AUTO. MANUAL means that operations will only go to the datastore on flush/commit, whereas AUTO will send them immediately.

  • The persistence property datanucleus.nontx.atomic previously only included persists and deletes. It now also encompasses field updates. Bear this in mind when considering behaviour

  • The value strategy chosen when "native"(JDO)/"auto"(JPA) is specified has changed. It will now take "identity"/"sequence"/"increment" when numeric-based (first that is supported for that datastore) and "uuid-hex" when string-based. For RDBMS, use persistence property datanucleus.rdbms.useLegacyNativeValueStrategy as true if wanting the old process.

Migration from 3.1.0.M1 to 3.1.0.M2

Migrating will require the following changes.

  • "javax.cache" is now split into "jcache" (old API) and "javax.cache" (standard API) and the standard API is now supported in datanucleus-core

  • datanucleus-management plugin is now merged into datanucleus-core

Migration from 3.0.x to 3.1.0.M1

Migrating will require the following changes.

  • Excel, ODF, MongoDB and HBase plugins now respect JDO/JPA table/column naming strategies. Make sure that you set the table/column names explicitly if requiring some other naming that was default with v3.0 and earlier plugins

  • If you have any "type" plugins using the ObjectStringConverter or ObjectLongConverter interface please rewrite them to use the new TypeConverter interface (minimal changes).

Migration to v3.0

Migration to 3.0 involves the following steps

Migration from 3.0.3 to 3.0.4

Migrating will require the following changes.

  • Move java.awt geometric type support into datanucleus-awtgeom plugin

Migration from 3.0.2 to 3.0.3

Migrating will require no changes.

Migration from 3.0.1 to 3.0.2

Migrating will require the following changes.

  • HBase : Default behaviour was to use Java serialisation to get the bytes of the PK of objects. This is changed to now use HBase Bytes.toBytes resulting in cleaner PK ROW ID. To get the old behaviour set the persistence property datanucleus.hbase.serialisePK

  • HBase : default behaviour used to be to persist primitive wrapper fields as serialized. They are now persisted as serialised if specified in metadata, otherwise using HBase Bytes handler

Migration from 3.0.0 M6 to 3.0.0 RELEASE

Migrating will require no changes.

Migration from 3.0.0 M5 to 3.0.0 M6

Migrating will require the following changes.

  • The plugin attribute "override" utilised by "java_type", "store_mapping" and "rdbms_mapping" is now removed, and users should make use of the attribute "priority" (specify a number and the higher the number the higher the priority that plugin extension gets.

  • JPA usage now defaults to use "datanucleus.RetainValues". This means that when an object leaves a transaction it will not move to HOLLOW state, but instead to PERSISTENT NONTRANSACTIONAL and has its field values intact.

  • If using an identity string translator, note that this is now a IdentityStringTranslator and the persistence property is now "datanucleus.identityStringTranslatorType"

Migration from 3.0.0 M4 to 3.0.0 M5

Migrating should require no changes.

Migration from 3.0.0 M3 to 3.0.0 M4

Migrating will require the following changes.

  • Maven2 plugin option "outputFile" is renamed to "ddlFile" for consistency with all docs/tools

Migration from 3.0.0 M2 to 3.0.0 M3

Migrating will require the following changes.

  • Anyone using "memcache" cache provider should rename it to "spymemcached". This renaming is to clarify which implementation of "memcached" is actually being used. Similarly the persistence properties are now spelt "memcached" instead of "memcache". Also the former property datanucleus.cache.level2.memcached.keyprefix is dropped and users should use datanucleus.cache.level2.cacheName instead

  • HBase : previously all primitives were stored serialised. Set the metadata 'serialized' flag on the field/property to continue doing that.

  • Queries are no longer run in a separate thread (which was the previous way of supporting query cancellation, now reworked for RDBMS to use SQL error codes).

  • Persistence properties for schema validation datanucleus.validateXXX now default to false

Migration from 3.0.0 M1 to 3.0.0 M2

Migrating will require the following changes.

  • The connection password decryption interface has been repackaged/renamed to org.datanucleus.store.encryption.ConnectionEncryptionProvider so if you were providing your own decryption of passwords then rebuild to this

  • If using your own DataNucleus plugins, make sure you specify the persistence property datanucleus.plugin.allowUserBundles as true since the default is now to just use official DataNucleus plugins.

  • The identifier naming strategy datanucleus has been renamed to datanucleus1 to make it clearer that it was used as the default for DataNucleus v1.x but no longer

Migration from 2.2.x to 3.0.0 M1

Migrating will require the following changes.

  • JDO API has been moved into its own plugin "datanucleus-api-jdo" and you will need this if using the JDO API. JDO classes have been repackaged to org.datanucleus.api.jdo and this is of particular importance for your PMF class (org.datanucleus.api.jdo.JDOPersistenceManagerFactory)

  • "datanucleus-jpa" jar has been repackaged as "datanucleus-api-jpa" and the classes within repackaged to "org.datanucleus.api.jpa". In particular your JPA persistence provider class should reference this new package name (org.datanucleus.api.jpa.PersistenceProviderImpl)

  • "datanucleus-rest" jar has been repackaged as "datanucleus-api-rest".

  • SchemaTool (and its Ant task) has been moved in package to org.datanucleus.store.schema

  • HBase : generation of "family name" has changed when previously specifying a column name without a colon; previously used that as family name and qualifier name, but now uses the table name as the family name in that situation.

  • HBase : previously all relationships were stored serialised. Set the metadata 'serialized' flag on the field/property to continue doing that.

Migration to v2.2

Migration to 2.2 involves the following steps

Migration from 2.2.0 RELEASE to 2.2.1

Migrating will require the following changes.

  • JDO 3.1 changes the return type of JDOQL "AVG" to be double or BigDecimal depending on the type being averaged (previously just returned the same type as the averaged type).

Migration from 2.2.0 Milestone3 to 2.2.0 RELEASE

Migrating will require the following changes.

  • datanucleus-connectionpool is no longer provided/needed, and is included within datanucleus-rdbms. In addition, if using Java6 you can use a builtin DBCP connection pool. You still need to include the relevant connection pool (e.g DBCP) in your CLASSPATH if using Java5

  • If you experience different behaviour with delete of objects with Excel or ODF, this is because they now support cascade-delete

  • Major changes have been made to the use of the L2 cache (so that fields are used from there rather than from the datastore wherever possible) and also to Managed Relations. Please report any problems

Migration from 2.2.0 Milestone2 to 2.2.0 Milestone3

Migrating will require the following changes.

  • Persistence property datanucleus.attachPolicy was removed since no longer needed - the default attach handler copes with all situations.

  • Much improved support for collections/arrays/maps containing nulls is now present to better match the Java spec for types. If any problems come up, make use of the "allow-nulls" extension metadata

  • JPA Criteria query annotation processor is now in its own plugin jar known as datanucleus-jpa-query

  • JDO Typesafe query annotation processor is now in its own plugin jar known as datanucleus-jdo-query

Migration from 2.2.0 Milestone1 to 2.2.0 Milestone2

Migrating will require the following changes.

  • NucleusJDOHelper methods for getting dirty/loaded fields have been improved. Check the docs for the new method names.

  • JDO3.1 sequence changes allow specification of "allocationSize" and "initialValue". These default to 50 and 1 respectively. Set them for your sequences as required. The persistence properties now become only fallback values

Migration from 2.1.x to 2.2.0 Milestone1

Migrating will require the following changes.

  • Legacy JDOQL implementation for RDBMS is now dropped. Use AccessPlatform 2.1 if you require it

Migration to v2.1

Migration to 2.1 involves the following steps

Migration from 2.1.2 to 2.1.3

Migrating will require the following changes.

  • Persistence property datanucleus.attachPolicy is now removed, and the default handling should work fine

Migration from 2.1.1 to 2.1.2

Migrating will require the following changes.

  • The metadata extension index that is used to specify a column position (in table) was previously required under "field" for Excel/ODF plugins. It should be under "column" now

Migration from 2.1.0 RELEASE to 2.1.1

Migrating will require the following changes.

  • Default allocation size for increment and sequence value strategies have been changed for JDO usage to 10 and 10 respectively (from 5 and 1). You can configure the global defaults via persistence properties

Migration from 2.1.0 Milestone3 to 2.1.0 RELEASE

Migrating will require the following changes.

  • Move to using JDO3 jar instead of JDO 2.3 "ec"

  • Dropped support for class-level metadata extension "cacheable"; use standardised cacheable attribute (or annotation) instead.

Migration from 2.1.0 Milestone2 to 2.1.0 Milestone3

Migrating will require no changes.

Migration from 2.1.0 Milestone1 to 2.1.0 Milestone2

Migrating will require the following changes.

  • JPQL "CASE" statements are now supported

  • JPA2 static metamodel is now supported, and so can be used with criteria queries alongside the string-based field specification method

  • Runtime enhancement is now turned off by default even when you use Java6+ and have the enhancer/core jars in the CLASSPATH. Specify the compiler argument processor to enable it (see the docs)

Migration from 2.0.x to 2.1.0 Milestone1

Migrating will require the following changes.

  • The JDOQL implementation used for RDBMS is now the rewritten "generic" implementation. To use the old implementation, set the JDOQL implementation as "JDOQL-Legacy"

  • Use of JPA should be run against the JPA2 "final" jar (or its Apache Geronimo specs equivalent)

  • Heavy refactoring has been done internally so if relying on DataNucleus APIs you should check against SVN for changes. In particular, plugins should be using ObjectProvider instead of StateManager, and ExecutionContext in place of ObjectManager.