JPOX 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 JPOX, and many of them are effortless. However, JPOX does not know all types beforehand and in situations like user defined types, mapping classes must be defined.

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 JPOX). Lets we follow the steps of defining a mapping class for a custom type.

1. Step 1 : Download JPOX and install it as Eclipse Plug-in
2. Step 2 : Create a Plug-in Project in Eclipse IDE
3. Step 3 : Add JPOX 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 JPOX 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 JPOX 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 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;
    }

    public ScalarExpression newLiteral(QueryExpression qs, Object value)
    {
        return null;
    }

    public ScalarExpression newScalarExpression(QueryExpression qs, LogicSetExpression te)
    {
        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 JPOX 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/jpox/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.jpox

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.jpox.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 JPOX.

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

This is the end of the tutorial.