Jump to: navigation, search

Difference between revisions of "Dali/Juno/JPAMetadataConversion"

< Dali‎ | Juno
(Phase 1)
(Functional Specification: [JPA Metadata Conversion])
Line 47: Line 47:
 
* Move XML to annotations
 
* Move XML to annotations
 
* Move global elements to XML
 
* Move global elements to XML
 +
 +
== Design ==
 +
* 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.
 +
** Metadata conversion will be delegated to a module separated from the current models for extensibility, but maintainability will be compromised and anyone who makes changes to current models in the future should be aware of the existence of the metadata conversion module to avoid breaking the functionality.
  
 
== Requirements ==
 
== Requirements ==
Line 149: Line 154:
 
*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.  
 
*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?
 
*If the chosen classes are not listed in the persistence.xml should they be removed to avoid the Dali warning?
 
== Design ==
 
  
 
== References  ==
 
== References  ==

Revision as of 15:56, 11 July 2011

Functional Specification: [JPA Metadata Conversion]

bug 138622- Convert annotated JPA metadata to orm.xml

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

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 queriesm, to XML

Phase 1

  • 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

Phase 2

  • 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

Phase 3

  • Convert binary metadata

Phase 4

  • Move XML to annotations
  • Move global elements to XML

Design

  • 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.
    • Metadata conversion will be delegated to a module separated from the current models for extensibility, but maintainability will be compromised and anyone who makes changes to current models in the future should be aware of the existence of the metadata conversion module to avoid breaking the functionality.

Requirements

High-level Use Cases

Use Case 1: Generate new orm.xml file

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

Use Case 2: Generate and overwrite orm.xml file

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

Use Case 3: Generate and merge into orm.xml file

The user has a list of Java sources (from same/different source folder(s)/project(s)) with annotated JPA metadata and requests to convert 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.

Use Case 4: Cancel metatada conversion

The user has a list of Java sources (from same/different source folder(s)/project(s)) with annotated JPA metadata and requests to convert metadata to mapping XML metadata. The user creates a new mapping file and selects the annotated sources. The user chooses to cancel the conversion. The metadata conversion wizard exists with the user’s confirmation and no annotated metadata would be written to the created mapping file.

Use Case 5: 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.

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

Use Cases 6: Generate new user named orm.xml file

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

Prototype 1

Prototype Option 1

Use Cases

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
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
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
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

Prototype 2

Prototype Option 2

Use Cases

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

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.

Questions

Note: Discussion of the questions goes to page Discussion

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?
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?
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?

References

User Interface Guidelines

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.