|
|
| (7 intermediate revisions by 2 users not shown) |
| Line 5: |
Line 5: |
| | | | |
| | ==Issue Summary== | | ==Issue Summary== |
| − | With the new Criteria API from the JPA 2.0 spec, EclipseLink will provide a way to produce static metamodel classes corresponding to the entities, mapped superclasses, and embeddable classes in the persistence unit. A static metamodel class models the persistent state and relationships of the corresponding managed class. | + | With the new Criteria API from the JPA 2.0 spec, EclipseLink can now produce static metamodel classes that correspond to the entities, mapped superclasses, and embeddable classes in the persistence unit. A static metamodel class models the persistent state and relationships of the corresponding managed class. |
| | | | |
| − | For portability, EclipseLink will generate the canonical metamodel as defined in section 6.2.1.1. | + | For portability, EclipseLink generates this canonical metamodel as defined in section 6.2.1.1 of the specification. |
| | | | |
| | ==General solution== | | ==General solution== |
| − | EclipseLink will employ the annotation processor tool (APT) in conjunction with its existing metadata processing of annotations and XML to generate the static metamodel classes. | + | EclipseLink generates the static metamodel classes by using the the annotation processor tool (APT) in conjunction with its existing metadata processing of annotations. |
| | | | |
| | For more information on APT, see: http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html | | For more information on APT, see: http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html |
| | | | |
| − | == Metadata processing ==
| |
| | | | |
| − | The annotation processor tool directly ties into the regular deployment metadata processing. Which means before generating the metamodel classes, persistence units are processed as they normally would be according to the spec giving you the following behavior:<br>
| + | ==End-user information== |
| | + | For additional information, see [[UserGuide/JPA/Using_the_Canonical_Model_Generator_(ELUG)|Using the Canonical Model Generator]] in the EclipseLink User Guide. |
| | | | |
| − | *Persistence unit property processing
| |
| − |
| |
| − | *XML mapping file merging and override
| |
| − |
| |
| − | *Full annotation and xml processing of Entities, Embeddables and MappedSuperclasses.
| |
| − |
| |
| − | *Full support of EclipseLink extensions, including annotations and eclipelink-orm.xml
| |
| − |
| |
| − | == Configuring and using within Eclipse Galileo ==
| |
| − |
| |
| − | The following steps outline how to configure the metamodel generation within the Eclipse IDE.
| |
| − |
| |
| − | #Select your project in the '''Package Explorer''' and select '''Project''' > '''Properties'''. The Properties dialog appears.
| |
| − | #Select '''Java Compiler''' and ensure you are using JDK 1.6 (or higher).
| |
| − | #Expand the '''Java Compiler''' element and select '''Annotation Processing'''.
| |
| − | #In the Annotation Processing area, enable the '''Enable annotation processing''' option.
| |
| − | #In the '''Generated source directory''' field, enter the directory in which to generate the metamodel classes.
| |
| − | #By default, '''Processor options''' are not needed. However, EclipseLink provides you with custom generation options if you would like to configure you metamodel classes differently then defined in the spec. See the EclipseLink custom processor options section below for supported processor options.
| |
| − | #Expand the '''Annotation Processing''' element and select '''Factory Path'''.
| |
| − | #Click '''Add External JARs''' and add the following libraries (JARs). Refer to the the [[#library_names|1.2.0 RC4 Library names]] for details.
| |
| − | **The EclipseLink JAR (eclipselik.jar)
| |
| − | **The Java persistence 2.0 preview JAR
| |
| − | **A JAR that contains the enabling services file that specifies the name of the annotation processor tool.
| |
| − | {| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| |
| − | | align="left" |
| |
| − | '''Note:''' The annotation processor ''does not'' log to the '''Console''' window. Instead, messages are logged to the '''Error Log''' window. To display this window, select '''Window > Show View > Error Log''' from the Eclipse menu.
| |
| − | |}<br />
| |
| − |
| |
| − | == Configuring and using within ANT/javac ==
| |
| − | Use the following procedure to configure the metamodel generation within ANT/javac:
| |
| − |
| |
| − | #Add '''modelgen jar''' to the javac classpath.
| |
| − | #Use the <tt>-processor</tt> option on javac command line.
| |
| − | #In the following examples, options are specified with using '''-A''' (for example, <tt>javac -Aeclipselink.persistencexml=META-INF/sub/persistence.xml</tt>)
| |
| − |
| |
| − | === ANT example ===
| |
| − | <source lang="xml">
| |
| − | <target name="model-compile" description="compile models that need canonical processing">
| |
| − | <javac
| |
| − | srcdir="${SRC_PATH}"
| |
| − | destdir="${DEST_PATH}"
| |
| − | debug="${javac.debug}"
| |
| − | debuglevel="${javac.debuglevel}"
| |
| − | optimize="${javac.optimize}"
| |
| − | source="${javac.version}"
| |
| − | target="${javac.version}"
| |
| − | deprecation="${javac.deprecation}" failonerror="true">
| |
| − | <include name="${MODEL_PATH}/**/*.java"/>
| |
| − | <compilerarg value="-Aeclipselink.persistencexml=${PERSISTENCE_XML_PATH}" compiler="javac1.6"/>
| |
| − | <classpath refid="${COMPILE_PATH_REF}"/>
| |
| − | </javac>
| |
| − | </target>
| |
| − | </source>
| |
| − |
| |
| − | == EclipseLink custom processor options ==
| |
| − | The following table describes the EclipseLink custom options:
| |
| − |
| |
| − | <table width="100%" border="1" frame="hsides" rules="rows" cellpadding="3">
| |
| − | <tr>
| |
| − | <th>Option</th>
| |
| − | <th>Description</th>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''eclipselink.persistencexml'''</td>
| |
| − | <td>
| |
| − | The full resource name in which to look for the persistence XML files. If not specified the default <tt>META-INF/persistence.xml</tt> will be used. </td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''eclipselink.persistenceunits'''</td>
| |
| − | <td>A comma deliminated list of persistence unit names that will be used when generating the canonical model. By default all persistence units available in all persistence XML files will be used.<br /><strong>Note</strong>: When specifying multiple persistence units you cannot include a persistence unit with a comma ( , ) in its name.</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''eclipselink.canonicalmodel.prefix'''</td>
| |
| − | <td>The prefix that will be added to the start of the class name of any generated canonical model class. By default the prefix is not used. </td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''eclipselink.canonicalmodel.suffix'''</td>
| |
| − | <td>The suffix that will be added to the end of the class name of any generated canonical model class. The default suffix value is <strong>_</strong> (an underscore). If specified, this property value must be a non-empty string that contains valid characters for use in a Java class name. </td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''eclipselink.canonicalmodel.subpackage'''</td>
| |
| − | <td>A sub-package name that can be used to have the canonical model generator generate its classes in a sub-package of the package where the corresponding entity class is located. By default the canonical model classes are generated into the same package as the entity classes.</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − |
| |
| − | == EclipseLink 1.2.0 RC4 Library names ==<span id="library_names"></span>
| |
| − |
| |
| − | Currently the target release of EclipseLink 1.2.0 is RC4 which uses the following jar files names in the ZIP installer. Please note that the ZIP installer is the only distribution of EclipseLink including the modelgen JAR file.
| |
| − | *Services file (enables the processor): <br /> '''''\eclipselink\jlib\jpa\eclipselink-jpa-modelgen_1.2.0.v20091016-r5565.jar'''''
| |
| − |
| |
| − | *javax.persistence library: <br />'''''\eclipselink\jlib\jpa\javax.persistence_2.0_preview.jar'''''
| |
| − |
| |
| − | *EclipseLink jar: <br /> '''''\eclipselink\jlib\eclipselink.jar'''''
| |
| − |
| |
| − | == Troubleshooting ==
| |
| − |
| |
| − | After following the configuration steps above if no classes are generated, check the following.
| |
| − |
| |
| − | #Ensure you have a persistence.xml. The default is META-INF/persistence.xml. If your persistence XML file is named differently or located elsewhere, you'll need to add the eclipselink.persistencexml processor option.
| |
| − | #If you are using an extended eclipselink orm mapping file and it is not listed in your persistence.xml file, it will not be discovered automatically (similar to the orm.xml file). You currently must specify <mapping-file>eclipselink-orm.xml</mapping-file> explicitly. The automatic discovery of the eclipselink-orm.xml if a known defect and will be corrected in a later version.
| |
| − |
| |
| − | After an XML change (within Eclipse), the generated model classes are not updated to reflect the change
| |
| − |
| |
| − | #Unlike changes to the model class itself, XML changes are not picked up automatically as the annotation processor is not aware of these changes. To have your XML changes reflected in your generated metamodel classes do a clean of your project. Select '''Project''' - '''Clean...'''
| |
| − | #If you have made many XML changes namely removed some mapping files or deleted some entities from others you will more than a project clean but rather a restart to the annotation processor tool to pick up all the changes. Do following to restart:
| |
| − | ##Select '''Project''' - '''Properties'''
| |
| − | ##Expand '''Java Compiler'''
| |
| − | ##Select '''Annotation Processing''' and deselect the '''Enable annotation processing''' checkbox
| |
| − | ##Click '''OK'''
| |
| − | ##A window will present itself stating the annotation processing settings have changed and that a rebuild of the project is required for the changes to take effect. Click '''Yes'''
| |
| − | ##Go back into the project propertes and select the '''Enable annotation processing''' checkbox.
| |
| − | ##Same message from step #5 will present itself, click '''Yes'''
| |
| | | | |
| | == Work schedule == | | == Work schedule == |
With the new Criteria API from the JPA 2.0 spec, EclipseLink can now produce static metamodel classes that correspond to the entities, mapped superclasses, and embeddable classes in the persistence unit. A static metamodel class models the persistent state and relationships of the corresponding managed class.
For portability, EclipseLink generates this canonical metamodel as defined in section 6.2.1.1 of the specification.
EclipseLink generates the static metamodel classes by using the the annotation processor tool (APT) in conjunction with its existing metadata processing of annotations.
