Plugins : Annotations

DataNucleus is developed as a plugin-driven framework and one of the components that is pluggable is the reading of annotations. DataNucleus provides a support for JDO2 and JPA1 annotations, but is structured so that you can easily add your own annotations and have them usable within your DataNucleus usage.

DataNucleus supports Java5 annotations. More than this, it actually provides a pluggable framework whereby you can plug in your own annotations support. The Java5 plugin provides plugins for JDO2 and JPA1 annotations. You can extend DataNucleus's capabilities using the plugin extension org.datanucleus.java5.annotations .

Plugin extension-point Key Description Location
org.datanucleus.java5.annotations @PersistenceCapable JDO2 annotation reader datanucleus-java5
org.datanucleus.java5.annotations @PersistenceAware JDO2 annotation reader datanucleus-java5
org.datanucleus.java5.annotations @Entity JPA1 annotation reader datanucleus-java5
org.datanucleus.java5.annotations @MappedSuperclass JPA1 annotation reader datanucleus-java5
org.datanucleus.java5.annotations @Embeddable JPA1 annotation reader datanucleus-java5




Interface

Any annotation reader plugin will need to implement org.datanucleus.metadata.annotations.AnnotationReader . So you need to implement the following interface 

package org.datanucleus.metadata.annotations;

import org.datanucleus.metadata.PackageMetaData;
import org.datanucleus.metadata.ClassMetaData;

public interface AnnotationReader
{
    /**
     * Accessor for the annotations packages supported by this reader.
     * @return The annotations packages that will be processed.
     */
    String[] getSupportedAnnotationPackages();

    /**
     * Method to get the ClassMetaData for a class from its annotations.
     * @param cls The class
     * @param pmd MetaData for the owning package (that this will be a child of)
     * @return The ClassMetaData (unpopulated and unitialised)
     */
    public ClassMetaData getMetaDataForClass(Class cls, PackageMetaData pmd);
}


Plugin Specification

So we now have our custom "annotation reader" and we just need to make this into a DataNucleus plugin. To do this you simply add a file plugin.xml to your JAR at the root. The file plugin.xml should look like this 

<?xml version="1.0"?>
<plugin id="mydomain.annotations" name="DataNucleus plug-ins" provider-name="My Company">
    <extension point="org.datanucleus.java5.annotations">
        <annotations annotation-class="mydomain.annotations.MyAnnotationType" 
                reader="mydomain.annotations.MyAnnotationReader"/>
    </extension>
</plugin>

So here we have our "annotations reader" class "MyAnnotationReader" which will process any classes annotated with the annotation "MyAnnotationType".