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
(Document History)
(Document History)
Line 29: Line 29:
 
! 08/22/2011
 
! 08/22/2011
 
! Update with phase 1 JUnit test information
 
! Update with phase 1 JUnit test information
|}
+
|-}
  
 
== Feature overview ==
 
== Feature overview ==

Revision as of 15:20, 22 August 2011

Functional Specification: [JPA Metadata Conversion]

bug 138622- Convert annotated JPA metadata to orm.xml

Document History

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

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

Phase 2 Move globals to Java

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

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

Phase 5 Binary Annotation to XML

  • Convert binary metadata

Phase 6 Rest of Work *

  • Move XML mappings to annotations

Requirements

High-level Use Cases

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.

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.

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.

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

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.

Design

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)

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.

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

Back to the top