Section : Documentation

Migration Guide for DataNucleus plugins

If developing plugins for DataNucleus, this page gives information on how to upgrade them to the latest version(s)

4.x -> 5.0

  • The datanucleus-java8 plugin is not used in DataNucleus v5.

4.0 -> 4.1

  • Updated the bytecode enhancement contract to have all classes in org.datanucleus.enhancement and use ExecutionContextReference in the enhancement contract rather than ExecutionContext, to minimise class loading requirements.

3.x -> 4.0

  • MetaDataManager changed to interface
  • TypeManager changed to interface
  • NucleusContext changed to interface, and PersistenceNucleusContext used throughout main persistence code
  • PersistenceConfiguration renamed to Configuration
  • StoreManager addClass, addClasses, removeAllClasses methods have been renamed
  • Plugin point org.datanucleus:store_mapping changed to org.datanucleus.store.rdbms:java_mapping
  • Plugin point org.datanucleus:store_datastoreadapter changed to org.datanucleus.store.rdbms:datastoreadapter
  • Plugin point org.datanucleus:store_identifierfactory changed to org.datanucleus.store.rdbms:identifierfactory
  • Plugin point org.datanucleus.store.rdbms:rdbms_mapping changed to org.datanucleus.store.rdbms:datastore_mapping
  • Many persistence properties changed, see migration notes for 4.0
  • Majority of schema handling code is now moved from StoreManager to StoreSchemaHandler
  • Refactor org.datanucleus.query.evaluator.memory to org.datanucleus.query.inmemory
  • Change enhancement contract to use org.datanucleus.enhancer.Persistable
  • Move identity generation to org.datanucleus.identity.IdentityManager

3.1 -> 3.2

  • The enhancer is now part of core, but with org.datanucleus.enhancer package still. ASM is repackaged into core too (as org.datanucleus.asm).
  • JDOClassLoaderResolver is renamed to ClassLoaderResolverImpl
  • org.datanucleus.store.types.sco is renamed to org.datanucleus.store.types
  • org.datanucleus.jta is renamed to org.datanucleus.transaction.jta
  • org.datanucleus.store.ObjectProvider moved to org.datanucleus.state.ObjectProvider and removed org.datanucleus.StateManager since redundant
  • org.datanucleus.store.ExecutionContext moved to org.datanucleus.ExecutionContext
  • ObjectManagerImpl renamed to ExecutionContextImpl
  • MultithreadedObjectManager renamed to ExecutionContextThreadedImpl
  • org.datanucleus.state.lock moved to org.datanucleus.state
  • Removed attribute persistent from java-type extension (now in APIAdapter).
  • org.datanucleus.store.mapped is now moved into the RDBMS plugin as org.datanucleus.store.rdbms.mapping (and other packages).
  • Dropped ApiAdapter.isLoaded(ObjectProvider, fieldNum); just call ObjectProvider.isLoaded(fieldNum) instead.
  • Dropped ApiAdapter.getVersion(ObjectProvider); just call ObjectProvider.getVersion() instead.
  • StoreManager argument added to constructor of AbstractPersistenceHandler.
  • package org.datanucleus.query.typesafe is refactored from core to api.jdo.
  • JavaTypeMapping/FieldManager arguments changed from Object to PreparedStatement/ResultSet in RDBMS plugin
  • StoreManager should now set the flushProcess to be used (defaults to FlushNonReferential, but override if you want control of the flush ordering)

2.x -> 3.0

  • In 2.x you have OMFContext. This is replaced by NucleusContext which also takes on the role of ObjectManagerFactoryImpl. You now create a NucleusContext by passing in the API name, its type and any startup properties.
  • In 2.x the constructor to ConnectionFactoryImpl took an OMFContext. It now takes StoreManager. This is since the ConnectionFactory is specific to that datastore, and we need to allow a NucleusContext to manage multiple StoreManagers.
  • StoreManager now takes in an additional argument with the persistence properties that it will manage. Just hand them to AbstractStoreManager constructor.
  • The method DataNucleusDataSourceFactory.makePooledDataSource(OMFContext) is changed to DataNucleusDataSourceFactory.makePooledDataSource(StoreManager).
  • When you want to access a persistence property, go via the StoreManager in general. This will then look whether the property is defined on the store, and if not will go to the NucleusContext (and if not specified by the user there, will use any available default).
  • Some methods added/changed on DatastoreAdapter interface relating to name/version of product and driver
  • StoreManager valueGenerationMgr is now lazy initialised, so always access it via getValueGenerationManager()
  • StoreManager now owns the QueryManager, instead of NucleusContext
  • If wanting to support SchemaTool, then your StoreManager must implement SchemaAwareStoreManager.
  • If wanting to support Backed SCO wrappers, then your StoreManager must implement BackedSCOStoreManager.
  • If wanting to support the datastore handing out object references (like in ODBMS), then your StoreManager must implement ObjectReferencingStoreManager
  • You now have the ability to handle the insert of multiple objects at once, or the delete of multiple objects at once if your datastore doesnt have referential integrity (most except RDBMS). Look at StorePersistenceHandler and you can implement insertObjects(), deleteObjects().
  • org.datanucleus.StateManager -> org.datanucleus.state.StateManager
  • org.datanucleus.metadata.VersionMetaData getNewVersion() moved to org.datanucleus.store.VersionHelper
  • org.datanucleus.store.AbstractStoreManager performVersionCheck() moved to org.datanucleus.store.VersionHelper
  • org.datanucleus.metadata.VersionMetaData and IdentityMetaData now only have 1 ColumnMetaData to reflect what we actually support
  • org.datanucleus.store.mapped.scostore is now moved into the RDBMS plugin. If you were extending them youre advised to add your own variants in your plugin since those were RDBMS-based.
  • XXXQuery constructors need to take in the StoreManager now too