DataNucleus products are built using a plugin mechanism, allowing plugins to operate together. This plugin mechanism is useful also from a user viewpoint in that you, the user, could provide plugins that use these plugin points and extend the capabilities of DataNucleus. Plugins are loaded by a plugin manager when DataNucleus is initialised at runtime, and this plugin manager uses a registry mechanism, inspecting jars in the CLASSPATH. The three steps necessary for creating a DataNucleus plugin are
A minimum META-INF/MANIFEST.MF for a plugin jar should look like this
Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: myplugin Bundle-SymbolicName: mydomain.myplugin Bundle-Version: 1.0.0 Bundle-Vendor: My Company</source>
Each plugin extension has attributes. If you want to override an extension that is included in DataNucleus itself then you need to specify the priority attribute, setting it to an integer (the default plugin has priority=0, so set to higher than this to override it). If you write a DataNucleus plugin and you either want it to be included in the DataNucleus distribution, or want it to be listed here then please contact us via the Forum
Plugin Points are defined for each DataNucleus release, so some may be available in one version and not in another. Consult the documentation of the DataNucleus version that you are using.
Non-managed environment is a runtime environment where DataNucleus runs and plug-ins are not managed by a container. In this environment the plug-in discovery and lifecycle is managed by DataNucleus.
There is a 1 to N instance relationship from DataNucleus to a plug-in per PMF. More exactly, if only one PMF exists, there is only one Plug-in instance for a Connection Pool Plug-in, and if N PMF exist, there are N Plug-in instances for a Connection Pool Plug-in.
JavaSE and JavaEE runtimes are considered non-managed environments. In non managed environments there is no lifecycle itself of plug-ins. Extensions implemented by plug-ins are instantiated on demand and terminated on PMF/EMF closing, PM/EM closing or in another form depending in what the extension is used for.
Managed environment is a runtime environment where DataNucleus plug-ins are managed by a container. The discovery, registry and lifecycle of plug-ins are controlled by the container. There is no plug-in instance relationship from DataNucleus to a plug-in regarding PMF instances. In managed environments, there is only one plug-in instance for one or N PMFs. Again, this is managed by the container.
DataNucleus supports OSGi containers as managed environment. In OSGi managed environments plug-in lifecycle is determined by the OSGi specification. Once activated, a plug-in is only stopped when the OSGi container finishes its execution, or the plug-in is stopped by an OSGi command.
A plugin owns an Extension. The behaviour is defined below :-
Each DataNucleus bundle uses a version schema that has the following grammar (OSGi 3.0 §3.2.4): major.minor.micro.qualifier Major, Minor and Macro are numeric values, and qualifier is a alphanumeric.
Each bundle has the version value set in the /META-INF/MANIFEST.MF file, Bundle-Version entry.
Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: DataNucleus Enhancer Bundle-SymbolicName: org.datanucleus.enhancer;singleton:=true Bundle-Vendor: DataNucleus Bundle-Version: 1.2.0.b2
The most common version compatibility policies are (OSGI 3.0 §3.6.2): * major - An incompatible update * minor - A backward compatible update * micro - A change that does not affect the interface: for example, a bug fix
When your bundle depends on another bundle, you must declare it in the /META-INF/MANIFEST.MF file, via the Require-Bundle entry.
For example, the RDBMS plugin (org.datanucleus.store.rdbms) plug-in depends on the core (org.datanucleus) plug-in.
Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: DataNucleus RDBMS Bundle-SymbolicName: org.datanucleus.store.rdbms;singleton:=true Bundle-Vendor: DataNucleus Bundle-Version: 1.2.0.b2 Bundle-Localization: plugin Require-Bundle: org.datanucleus
See more on the OSGi 3.0 specification §3.13.1.
If a bundle depends on a specific version of a bundle, you must declare it in the Require-Bundle entry, bundle-version parameter. For example
Require-Bundle: org.datanucleus;bundle-version=(1.2.0.b2, 2.0)
See more on the OSGi 3.0 specification §3.2.5 and §3.13.1 chapters.
All recent DataNucleus releases (v3.2 onwards) use the Maven bundle plugin to auto-generate the MANIFEST.MF file. This means that the version in the pom.xml is taken for the bundle version, and the dependencies are auto-generated from imports etc. We recommend that you use this same method for your own plugins.