DataNucleus is an extensible persistence tool and allows the user to plug-in user extensions contributing to several persistence aspects. One of these aspects is the Java Types supported for persistence. Infinite types can be persisted with DataNucleus, and many of them are effortless. However, DataNucleus does not know all types beforehand and in situations like user defined types, mapping classes must be defined. While this guide was written for JPOX, you should be able to replace org.jpox by org.datanucleus

In this tutorial we will create a mapping class for the java.lang.StringBuffer (Note that this type is presented only as matter of example, since it is already supported by DataNucleus). Lets we follow the steps of defining a mapping class for a custom type.

1. Step 1 : Download DataNucleus and install it as Eclipse Plug-in
2. Step 2 : Create a Plug-in Project in Eclipse IDE
3. Step 3 : Add DataNucleus Core Plug-in as dependency to the Eclipse Plug-in
4. Step 4 : Implement the org.jpox.store_mapping extension
5. Step 5 : Export the plug-in as a jar file
6. Step 6 : Run your application

Download Eclipse IDE if necessary, and download DataNucleus Core jar and copy it to the Eclipse Plug-in folder <ECLIPSE_HOME>/plugins . Restart Eclipse when done.

Create a Plug-in Project in Eclipse IDE. In Eclipse menu select File >> New >> Project , and follow the wizard.

Select Plug-in Project and click Next .

Give a name to plug-in and click Next .

Unckeck the plug-in options and click on Finish .

Using the Package Explorer of Eclipse open the /META_INF/MANIFEST.MF file.

Go to the Dependencies folder.

Click on Add .

Select org.jpox as dependency.

Using the Package Explorer of Eclipse open the /META_INF/MANIFEST.MF file and add the DataNucleus Core Plug-in (org.jpox) as dependency to your plug-in.

Click on Add .

Select org.jpox.store_mapping and click on Finish .

Right click on org.jpox.store_mapping item.

Select New >> mapping .

On the right panel, set the java-type field to java.lang.StringBuffer and click on mapping-class to create a new JavaTypeMapping class.

Give a class and package name and click on Finish .

The below code is a skeleton created automatically after this wizard, and you must implement it properly. See RDBMS User Types for additional information.

...
public class StringBufferMapping extends JavaTypeMapping
{
    public StringBufferMapping()
    {
    }

    public StringBufferMapping(DatastoreAdapter dba, String type, AbstractPropertyMetaData fmd, DatastoreContainerObject container)
    {
        super(dba, type, fmd, container);
    }

    public Class getJavaType()
    {
        return null;
    }

    public Object getSampleValue(ClassLoaderResolver clr)
    {
        return null;
    }
}

The results should be like the above picture. We will not create a sco-wrapper class because the java.lang.StringBuffer is a final class and cannot be subclassed. SCO wrapper classes are used for dirty checking SCO types.

Eclipse IDE comes with an export utility that creates the jar file with the DataNucleus plug-in.

Go to the Overview folder.

Click on Export Wizard .

Select your plug-in, destination directory and click on Finish .

Once the export process is finished the jar is created under the <destination directory>/plugins .

The jar contains the files:

• /META-INF/manifest.mf
• /plugin.xml
• /org/datanucleus/samples/stringbuffer/StringBufferMapping.class

The manifest.mf file looks like:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Stringbuffer Plug-in
Bundle-SymbolicName: org.jpox.samples.stringbuffer;singleton:=true
Bundle-Version: 1.0.0
Bundle-Localization: plugin
Require-Bundle: org.datanucleus

The plugin.xml looks like:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
   <extension
         point="org.jpox.store_mapping">
      <mapping
            default-embedded="true"
            default-fetch-group="false"
            default-persistent="false"
            java-type="java.lang.StringBuffer"
            mapping-class="org.datanucleus.samples.stringbuffer.StringBufferMapping"/>
   </extension>
</plugin>

As any other java application you must to add the jar to the classpath before running, and the plug-in will be automatically registered with DataNucleus.

If for some reason you don't get the results expected, you can troubleshoot by enabling DataNucleus.Plugin logging and looking at the output.

This is the end of the tutorial.