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 "EclipseLink/DesignDocs/384399"

(Phase #6 - TBD)
(Development Plan)
Line 289: Line 289:
 
#Update relevant project/build/maven dependencies to reflect this change.
 
#Update relevant project/build/maven dependencies to reflect this change.
  
=== Phase #3 - Introduce XMLProject Class  ===
+
=== Phase #3 - Create the Common Bundle  ===
 
+
The following items will be done during this phase:
+
 
+
#Add ''org.eclipse.persistence.oxm.XMLProject'' as a subclass of ''org.eclipse.persistence.sessions.Project''. 
+
#Modify OXM test cases to use the new ''XMLProject'' class.
+
 
+
=== Phase #4 - Create the Common Bundle  ===
+
  
 
The following items will be done during this phase:  
 
The following items will be done during this phase:  
Line 304: Line 297:
 
#Update relevant dependencies
 
#Update relevant dependencies
  
=== Phase #5 - Have Core Classes Extend Corresponding Common Classes ===
+
=== Phase #4 - Have Core Classes Extend Corresponding Common Classes ===
  
 
#Modify classes in the core bundle with counterparts in the common bundle to subclass from them.
 
#Modify classes in the core bundle with counterparts in the common bundle to subclass from them.
 
#Move common functionality up to super class.
 
#Move common functionality up to super class.
 
#ORM subclasses will need methods that simply call the super method to maintain binary compatibility.
 
#ORM subclasses will need methods that simply call the super method to maintain binary compatibility.
 +
 +
=== Phase #5 - Introduce XMLProject Class  ===
 +
 +
The following items will be done during this phase:
 +
 +
#Add ''org.eclipse.persistence.oxm.XMLProject'' as a subclass of ''org.eclipse.persistence.sessions.Project''. 
 +
#Modify OXM test cases to use the new ''XMLProject'' class.
  
 
=== Phase #6 - Change OXM Classes to Extend Common Classes ===
 
=== Phase #6 - Change OXM Classes to Extend Common Classes ===
Line 314: Line 314:
 
#Change the OXM Classes to Extend Common Classes
 
#Change the OXM Classes to Extend Common Classes
  
=== Phase #7 - TBD ===
+
=== Phase #7 - Move ORM Specific Classes Out of Core Bundle  ===
 
+
=== Phase #8 - TBD ===
+
 
+
=== Phase #9 - Move ORM Specific Classes Out of Core Bundle  ===
+
  
 
The following items will be done during this phase:  
 
The following items will be done during this phase:  
Line 325: Line 321:
 
#Update relevant project/build/maven dependencies to reflect this change.
 
#Update relevant project/build/maven dependencies to reflect this change.
  
=== Phase #10 - Move Common Classes to Core Bundle  ===
+
=== Phase #8 - Move Common Classes to Core Bundle  ===
  
 
The following items will be done during this phase:  
 
The following items will be done during this phase:  

Revision as of 11:44, 17 August 2012

Design Specification: MOXy Footprint Reduction

ER 384399

Document History

Date Author Version Description & Notes
2012/07/05 Blaise Doughan Work In Progress

Project overview

Problem

The install footprint is currently preventing MOXy from being bundled with other software and used on mobile platforms.

XML Binding Install Footprint (EclipseLink 2.4)

Bundle Size
org.eclipse.persistence.moxy_2.4.0.v20120608-r11652.jar 455 KB
org.eclipse.persistence.asm_3.3.1.v201206041142.jar 271 KB
org.eclipse.persistence.core_2.4.0.v20120608-r11652.jar 4711 KB
5437 KB

JSON Binding Install Footprint (EclipseLink 2.4)

Bundle Size
org.eclipse.persistence.moxy_2.4.0.v20120608-r11652.jar 455 KB
org.eclipse.persistence.asm_3.3.1.v201206041142.jar 271 KB
org.eclipse.persistence.core_2.4.0.v20120608-r11652.jar 4711 KB
org.eclipse.persistence.antlr_3.2.0.v201206041011.jar 190 KB
5627 KB

Goals

Bundle Size
org.eclipse.persistence.moxy_2.4.0.v20120608-r11652.jar 455 KB
org.eclipse.persistence.asm_3.3.1.v201206041142.jar 271 KB
org.eclipse.persistence.core_2.4.0.v20120608-r11652.jar 1000 KB (estimated)
org.eclipse.persistence.antlr_3.2.0.v201206041011.jar 190 KB
1726 KB (XML) / 1916 (JSON)

Concepts

Package Splitting

This is when classes from the same package are distributed among different bundles. This is not compatible with OSGi, and therefore is something that we can not do.

Generics & Parameterized Types

This design makes use of generics, below is an example if you are not familiar with the mechanism in Java.

package demo;
 
import java.lang.reflect.Method;
 
public class Demo {
	private static String METHOD_NAME = "sample";
	private static Class<?>[] PARAMETER_TYPES = new Class[] {String.class};
 
	public static void main(String[] args) throws Exception {
		// Use Method - Test Method Can Be Called
		Integer a = new Foo().sample("A"); // YES
		Integer b = new Bar().sample("B"); // YES
		Integer c = new Baz().sample("C"); // YES
 
		// Reflection - Test Method Accessed Via Reflection
		hasMethod(Foo.class, METHOD_NAME, PARAMETER_TYPES); // YES
		hasMethod(Bar.class, METHOD_NAME, PARAMETER_TYPES); // NO
		hasMethod(Baz.class, METHOD_NAME, PARAMETER_TYPES); // YES
	}
 
	private static void hasMethod(Class<?> clazz, String methodName, Class<?>[] parameterTypes) {
		try {
			Method method = clazz.getMethod(methodName, parameterTypes);
			System.out.println(method);
		} catch(NoSuchMethodException e) {
			e.printStackTrace();
		}
	}
 
	// Regular Java Class
	static class Foo {
		public Integer sample(String string) {
			return null;
		}
	}
 
	// Parameterized Type
	static abstract class AbstractBar<RETURN, PARAMETER> {
		private RETURN value;
 
		public RETURN sample(PARAMETER parameter) {
			return value;
		}
	}	
 
	// Subclass of Parameterized type
	static class Bar extends AbstractBar<Integer, String>{
	}
 
	// Subclass of Parameterized type that overrides method from super class
	static class Baz extends AbstractBar<Integer, String> {
		@Override
		public Integer sample(String parameter) {
			return super.sample(parameter);
		}
	}
}


Requirements

  1. All bundles must remain binary compatible except the OXM aspects of org.eclipse.persistence.core.

Design Constraints

  1. All bundles must remain binary compatible except the OXM aspects of org.eclipse.persistence.core.

Design / Functionality

High Level

Bundle Changes

  1. Introduce a new bunding org.eclipse.persistence.common to contain classes common to both MOXy and Core
  2. Move MOXy specific things from Core to MOXy
  3. Change MOXy bundle to depend on Common bundle

Common Abstractions

The common bundle will include abstractions that are common to both MOXy and ORM. Below is an example of the current and proposed architectures.

  • AbstractProject, AbstractDescriptor, and AbstractMapping would be part of the new common bundle.
  • Project, ClassDescriptor, and DatabaseMapping would be changed to extend their counterparts from the core bundle. This would be done in such a way as to maintain binary compatibility.
  • New MOXy classes would be added (i.e. XMLProject and XMLMapping) and others modified (i.e. XMLDescriptor). This would introduce a binary incompatibility in the native MOXy APIs.
Current (edit) Proposed (edit)
DesignDoc384399-Before.jpg            DesignDoc384399-Proposed.jpg

Medium Level

Required Abstractions

Initial prototyping indicates that abstractions would be required for the following classes:

  • org.eclipse.persistence.config
    • DescriptorCustomizer
  • org.eclipse.persistence.descriptors
    • ClassDescriptor
    • ClassExtractor
    • DescriptorEvent
    • DescriptorEventAdapter
    • DescriptorEventAdapter
    • DescriptorEventManager
    • InheritancePolicy
    • InstatiationPolicy
  • org.eclipse.persistence.exceptions
    • ExceptionHandler
    • IntegrityChecker
  • org.eclipse.persistence.internal.databaseaccess
    • DatasourcePlatform
  • org.eclipse.persistence.internal.descriptors
    • ObjectBuilder
  • org.eclipse.persistence.internal.helper
    • ConversionManager
    • DatabaseField
    • DatabaseTable
  • org.eclipse.persistence.internal.identitymaps
    • CacheKey
  • org.eclipse.persistence.internal.queries
    • ContainerPolicy
  • org.eclipse.persistence.internal.sessions
    • AbstractRecord
    • AbstractSession
    • IdentityMapAccessor
  • org.eclipse.persistence.mappings
    • AttributeAccessor
    • DatabaseMapping
  • org.eclipse.persistence.mappings.converters
    • Converter
  • org.eclipse.persistence.mappings.sessions
    • DatasourceLogin
  • org.eclipse.persistence.queries
    • ObjectBuildingQuery
  • org.eclipse.persistence.sessions
    • Project
    • SessionEvent
    • SessionEventAdapter
    • SessionEventListener
    • SessionEventManager
    • SesssionLog

Low Level

Inheritance Hierarchies

Development Plan

Phase #1 - Introduce XMLSession and Supporting Classes

The following items will be done during this phase:

  1. Add org.eclipse.persistence.oxm.sessions.XMLSession and supporting classes
  2. Have XMLSession extend DatabaseSession
  3. Modify OXM layer to use instance of XMLSession (no public API changes yet)
  4. Override all inherited methods to throw UnsupportedOperationException
  5. Add back minimum functionality to get OXM/JAXB/SDO tests passing.

Phase #2 - Move MOXy Specific Classes Out of Core Bundle

The following items will be done during this phase:

  1. Move the MOXy specific classes from the org.eclipse.persistence.core bundle into the org.eclipse.persistence.moxy bundle or intro a new org.eclipse.persistence.oxm bundle (see Open Issue #2).
  2. Update relevant project/build/maven dependencies to reflect this change.

Phase #3 - Create the Common Bundle

The following items will be done during this phase:

  1. Create the org.eclipse.persistence.common bundle as a new foundation bundle.  This bundle will later become the org.eclipse.persistence.common bundle.
  2. Add skeleton abstractions into common bundle
  3. Update relevant dependencies

Phase #4 - Have Core Classes Extend Corresponding Common Classes

  1. Modify classes in the core bundle with counterparts in the common bundle to subclass from them.
  2. Move common functionality up to super class.
  3. ORM subclasses will need methods that simply call the super method to maintain binary compatibility.

Phase #5 - Introduce XMLProject Class

The following items will be done during this phase:

  1. Add org.eclipse.persistence.oxm.XMLProject as a subclass of org.eclipse.persistence.sessions.Project
  2. Modify OXM test cases to use the new XMLProject class.

Phase #6 - Change OXM Classes to Extend Common Classes

  1. Change the OXM Classes to Extend Common Classes

Phase #7 - Move ORM Specific Classes Out of Core Bundle

The following items will be done during this phase:

  1. Move the ORM specific classes from the org.eclipse.persistence.core bundle into the org.eclipse.persistence.jpa bundle or intro a new org.eclipse.persistence.orm bundle (see Open Issue #3).
  2. Update relevant project/build/maven dependencies to reflect this change.

Phase #8 - Move Common Classes to Core Bundle

The following items will be done during this phase:

  1. Move the Core classes from the org.eclipse.persistence.common bundle into the org.eclipse.persistence.core bundle.
  2. Delete the common bundle.
  3. Update relevant project/build/maven dependencies to reflect this change.

Testing

API

Config files

Deployment XML - OXM

If we continue to support the deployment XML file for OXM projects, we will need to map the old format to the new objects. See Open Issue #4.

Documentation

The following items will need to be documented:

  • What the binary incompatibilities are (if any).
  • How to migrate to the new release (i.e. Using the Package Renamer Tool).

Open Issues

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

Issue # Owner Description / Notes
1 Peter/Doug Does the implementation of this feature require us to bump the version number to 3.0?
2 Peter/Doug/Blaise Should the OXM specific items in the core bundle be moved into the moxy bundle or a new oxm bundle.
3 Peter/Doug Should the ORM specific items in the core bundle be moved into the jpa bundle or a new orm bundle.
4 Peter/Doug/Blaise Should the old deployment XML file still be supported. If so work will need to be done to map the new MOXy metadata objects to the old format.

Decisions

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

Issue # Description / Notes Decision

Future Considerations

During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.

Project Jigsaw

Is a standard module system being designed for the Java SE platform. It is being applied to the JDK itself. While this feature is not dependent on Jigsaw, care will be taken as to what modules we will need to depend on.

Back to the top