Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Dali/Juno/JPAMetadataConversion"

< Dali‎ | Juno
(Use Case 4)
m (Use Case 1)
Line 29: Line 29:
 
=== High-level Use Cases ===
 
=== High-level Use Cases ===
  
==== Use Case 1 ====
+
==== Use Case 1: Generate New ORM 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.
 
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.
  

Revision as of 10:39, 8 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 Draft 1 - Add initial prototypes, use cases, and questions we have to collect requirements

Feature overview

The purpose of this feature is to provide the ability to generate mapping files from the annotated sources so that users can get different behaviors by configuring generated mapping files without touching their well configured sources.

Phase 1

Phase 2

Phase 3

Requirements

High-level Use Cases

Use Case 1: Generate New ORM 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

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

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

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

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 within which invalid metadata exists. The user is asked to either correct the metadata or confirm to ignore the metadata. A mapping file is generated and opened with the metadata from the selected Java sources.

Use Cases 6

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?

Design

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.

Back to the top