Difference between revisions of "Dali/Juno/JPAMetadataConversion"

From Eclipsepedia

< Dali‎ | Juno
Jump to: navigation, search
(Phase 1 Move globals to XML)
m (Functional Specification: [JPA Metadata Conversion])
 
(14 intermediate revisions by one user not shown)
Line 25: Line 25:
 
! 07/20/2011
 
! 07/20/2011
 
! Update with the feedback got from planning meeting
 
! Update with the feedback got from planning meeting
 +
|-
 +
! Nan Li
 +
! 08/22/2011
 +
! Update with phase 1 JUnit test information
 
|}
 
|}
  
Line 33: Line 37:
 
* move annotations in both Java sources and jar files to XML
 
* move annotations in both Java sources and jar files to XML
 
* move XML to annotations
 
* move XML to annotations
* move global elements, such as generators and queriesm, to XML
+
* move global elements, such as generators and queries, to XML
  
=== Phase 1 Move globals to XML ===
+
=== Phase 1 Move globals to XML [https://bugs.eclipse.org/bugs/show_bug.cgi?id=353149 353149] ===
 
* Move can only be performed at project level considering the objects being moved are globals
 
* Move can only be performed at project level considering the objects being moved are globals
* We will do nothing if a global has duplicates in XML or is overridden by a query in XML. Report will be given for the query.
+
* We will do nothing if a global has duplicates in Java sources or is overridden by globals in XML. A front warning will be given.
* Globals will be Wipt off from Java after move
+
* Globals will be removed from Java after being converted to XML globals
 +
* Separate menu items will be provided for query, generator and converter
 +
 
 +
JUnit Test:
 +
* The test cases of query and generator metadata conversion are in the class named Generic2_0JpaMetadataConversionTests
 +
* The test cases of converter metadata conversion are in the class named EclipseLink2_0JpaMetadataConversionTests
  
 
=== Phase 2 Move globals to Java ===
 
=== Phase 2 Move globals to Java ===
Line 73: Line 82:
  
 
==== Use Case 3: Convert global element to orm.xml file ====
 
==== Use Case 3: Convert global element to orm.xml file ====
The user has generators/queries/converters defined in Java sources and requests to move them to a mapping file as global elements. The user selects a JPA project, creates/selects a mapping file, and chooses to move. All the generators/queries/converters are moved to the mapping file at the mapping file level and wipt off from the Java sources.
+
The user has generators/queries/converters defined in Java sources and requests to move them to a mapping file as global elements. The user selects a JPA project, creates/selects a mapping file, and chooses to move. All the generators/queries/converters are moved to the mapping file as the mapping XML global level metadata and wipt off from the Java sources.
  
''Note: Different menu items could be added for moving generators, queries, and converters separately.''
+
''Note: Different menu items will be added for moving generators, queries, and converters separately.''
  
 
=== Prototype 1 ===
 
=== Prototype 1 ===
Line 153: Line 162:
 
[[Image:Class Diagram.png|Class Diagram]]
 
[[Image:Class Diagram.png|Class Diagram]]
  
* EclipseLink ORM XML is required for migration in either direction when using EclipseLink platform
+
* EclipseLink ORM XML is required for migration in either direction when using EclipseLink platform.
* Conversion will not perform if compiling errors or malformed XML exist
+
* Conversion will not perform if compiling errors or malformed XML exist.
* Report will be given at the end of conversion if there's any metadata that we don't yet support or failed to convert
+
* Warning message will be given at the front to inform users these metadata that we don't yet support, if exist, will not be converted.
 +
* Warning message will be given at the front to inform users these duplicate or overridden annotated globals, if exist, will not be converted.
  
 
== Questions ==
 
== Questions ==

Latest revision as of 10:07, 23 August 2011

Contents

[edit] Functional Specification: [JPA Metadata Conversion]

bug 138622- Convert annotated JPA metadata to orm.xml

[edit] Document History

Date Author Version Description & Notes
Nan Li 06/16/2011 Add initial prototypes, use cases, and questions we have to collect requirements
Nan Li 07/08/2011 Update with the feedback got from PM and the team
Nan Li 07/19/2011 Update with design related content
Nan Li 07/20/2011 Update with the feedback got from planning meeting
Nan Li 08/22/2011 Update with phase 1 JUnit test information

[edit] Feature overview

The main purpose of this feature is to provide the ability to convert annotated and XML JPA metadata back and forth to let us get different behaviors. With this feature, users could

  • move annotations in both Java sources and jar files to XML
  • move XML to annotations
  • move global elements, such as generators and queries, to XML

[edit] Phase 1 Move globals to XML 353149

  • Move can only be performed at project level considering the objects being moved are globals
  • We will do nothing if a global has duplicates in Java sources or is overridden by globals in XML. A front warning will be given.
  • Globals will be removed from Java after being converted to XML globals
  • Separate menu items will be provided for query, generator and converter

JUnit Test:

  • The test cases of query and generator metadata conversion are in the class named Generic2_0JpaMetadataConversionTests
  • The test cases of converter metadata conversion are in the class named EclipseLink2_0JpaMetadataConversionTests

[edit] Phase 2 Move globals to Java

[edit] Phase 3 Type Mapping Annotation to XML

  • Move annotations of type mapping(s) of the same package or different packages to XML
    • Overwrite the existing type mapping(s) in XML - remove the old type mapping(s) and add the new ones
    • Merge the existing type mapping(s) to XML - update the existing type mapping(s) with new metadata

[edit] Phase 4 Attribute Mapping Annotation to XML

  • Move annotations of attribute mapping(s) to XML
    • Move annotations of all the available attribute mapping(s)
    • Move annotations of selected attribute mapping(s)
    • Available attribute mapping(s) depends on the access type of the corresponding type mapping
      • Field: ignore the annotated properties
      • Property: ignore the annotated fields
      • Default: field access type

[edit] Phase 5 Binary Annotation to XML

  • Convert binary metadata

[edit] Phase 6 Rest of Work *

  • Move XML mappings to annotations

[edit] Requirements

[edit] High-level Use Cases

[edit] Use Case 1: Convert into new orm.xml file

The user has a JPA project with a list of annotated Java sources (from same/different source folder(s)) and requests to convert annotated metadata to mapping XML metadata. The user creates a new mapping file, selects the annotated sources from the list of Java sources, and chooses add the mapping file to the persistence.xml. A mapping file is added to the persistence.xml and opened with the metadata from the selected Java sources.

[edit] Use Case 2: Convert and merge into existing orm.xml file

The user has a JPA projecct with a list of annotated Java sources (from same/different source folder(s)) and requests to convert annotated metadata to mapping XML metadata. The user specifies a mapping file and selects the annotated sources. The user confirms merging metadata to the existing mapping file. The specified mapping file is updated and opened with the metadata from the selected Java sources.

[edit] Use Case 3: Convert global element to orm.xml file

The user has generators/queries/converters defined in Java sources and requests to move them to a mapping file as global elements. The user selects a JPA project, creates/selects a mapping file, and chooses to move. All the generators/queries/converters are moved to the mapping file as the mapping XML global level metadata and wipt off from the Java sources.

Note: Different menu items will be added for moving generators, queries, and converters separately.

[edit] Prototype 1

Prototype Option 1

[edit] Use Cases

[edit] Use case 1-1
  1. User selects several classes from same or different packages and chooses Metadata Conversion
  2. The selected classes are listed and user can select/deselect the classes he wants to convert
[edit] Use case 1-2
  1. User selects several classes from same or different packages and chooses Metadata Conversion
  2. All the valid mapped classes in the selected project are listed with the pre-chosen ones be selected, and user can select/deselect the classes he wants to convert
[edit] Use case 2
  1. User selects one or more package(s) and chooses Metadata Conversion
  2. All the valid mapped classes in the selected package(s) are listed and user can select/deselect the classes he wants to convert
[edit] Use case 3
  1. User selects a project and chooses Metadata Conversion
  2. All the valid mapped classes in the selected package(s) are listed and user can select/deselect the classes he wants to convert

[edit] Prototype 2

Prototype Option 2

[edit] Use Cases

[edit] Use case 1
  1. User selects a class(es)/package(s)/project and chooses Metadata Conversion
  2. The project hierarchy tree shows up with all the available projects and the pre-chosen ones be selected
  3. User can navigate the tree to select the mapped classes he wants to convert
[edit] Use case 2
  1. User selects a class(es)/package(s)/project and chooses Metadata Conversion
  2. User selects “Save as the default mapping file” checkbox, the combo box and Browse button will be disabled.
  3. User hits Finish button, the generated mapping file will be saved to META-INF folder named orm.xml.
[edit] Use case 3
  1. User selects a class(es)/package(s)/project and chooses Metadata Conversion
  2. User clicks Browse button for specifying mapping file
  3. User select “Excluded from persistence.xml” and hit Finish
  4. The generated mapping file won’t be written to the persistence.xml as a mapping file refer entry.

[edit] Prototype 3

"slush bucket wizard" could be used to manipulate the possible selections and selected items. The possible selections could be shown with project hierarchy tree.

[edit] Design

[edit] Design Options

  • Delegate conversion behavior to a big conversion manager class or a group of converter classes. [Class Diagram]
  • Build up converison behavior through creating new constructors to context model objects. E.g. we could create a factory method called like convertEntity making it return an OrmEntity through new constructor.
OrmEntity convertEntity(OrmPersistentType parent, JavaEntity javaEntity) {
   return new GenericOrmEntity(parent, javaEntity);
}
  • Delegate conversion behavior to context model objects
    • Add convertTo method to Java context model objects, like javaPersistentType.convertTo(ormPersisentType)
    • Add convertFrom method to Xml context model objects, like ormPersistentType.convertFrom(javaPersistentType)

[edit] Design Decisions

  • Metadata conversion will be conducted on single JPA project basis due to no way to specify the project related information in a mapping file.
  • Considering the pros and cons of the design options above, the last one would be the best. It integrates the conversion behavior to the XML context model while keeping the independence of the Java context model and avoiding the unexpected behavior that could be introduced by adding new constructors. The detailed design could be

Class Diagram

  • EclipseLink ORM XML is required for migration in either direction when using EclipseLink platform.
  • Conversion will not perform if compiling errors or malformed XML exist.
  • Warning message will be given at the front to inform users these metadata that we don't yet support, if exist, will not be converted.
  • Warning message will be given at the front to inform users these duplicate or overridden annotated globals, if exist, will not be converted.

[edit] Questions

Note: Discussion of the questions goes to page Discussion

[edit] About Prototypes

  • Prototype option 2/3 would work better when lots of Java sources exist in the workspace since it may tiresome for users to select one by one with option 1.
  • With prototype option 2, all the resources in the selected node would be shown in the right side window considering our uses are developers. Validation message should be given when invalid conversion resources are selected. Should we prevent invalid resources from being shown up?
  • 'Save as the default mapping file' option. For an EclipseLink project would we want it to be the default eclipselink-orm.xml file? Would orm.xml with the EclipseLink namespace and schema location be sufficient?
  • By default the generated mapping file would be automatically included in the persistence.xml since mapping files except the default ones (META-INF/orm.xml and META-INF/eclipselink-orm.xml) won’t take effect unless they are listed in the persistence.xml. Uses can exclude the generated mapping file from persistence.xml by selecting the "Exclude from persistence.xml" checkbox. Is this a proper consideration?

[edit] About Annotated Sources

  • We assume users would want to convert all the metadata in a Java source so we only give the option to choose classes. Do we want to provide the ability to let users go a level deeper to choose the attribute mappings they want to convert?
  • Should we remove the annotations from java and replace them with orm.xml?
  • What about package-info.java files? Generic case doesn't need to support this, maybe adopters have feedback on this one?
  • What about JPA annotated binary files?

[edit] About Generated Mapping Files

  • What do we want to do when specified mapping file already exist? Do we want to just delete the old one and generate a new one? Do we want to support merge operation?
  • What if a class is already listed in another orm.xml file?
  • What if users want to convert a Java source with EclipseLink metadata to a generic mapping file? Should we give a warning and convert all the metadata to the mapping file? Should we give a warning and filter out the EclipseLink metadata?
  • Do we want to use the xml-mapping-metadata-complete flag? and exclude-default-mappings flag in eclipselink? or just convert the specified annotations in java? If we use xml-mapping-metadata-complete we will need to use the access flag in the orm.xml where it is only denoted by annotation location in java.
  • If the chosen classes are not listed in the persistence.xml should they be removed to avoid the Dali warning?

[edit] References

User Interface Guidelines

[edit] Notes

  • Discussion goes to page Discussion. It would be better to leave your name along with your feedback to facilitate our discussion.
  • Feedback about anything on this wiki page is very welcome.