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"

m (Primary Goals)
(Bundle Changes)
Line 192: Line 192:
 
==== Bundle Changes ====
 
==== Bundle Changes ====
  
#Introduce a new bunding '''''org.eclipse.persistence.common''''' to contain classes common to both MOXy and Core
+
#Have the org.eclipse.persistence.common bundle contain things that are only common to both OXM and ORM.
#Move MOXy specific things from Core to MOXy
+
#Move MOXy specific items into MOXy bundle.
#Change MOXy bundle to depend on Common bundle
+
#MOXy ORM specific items into JPA bundle (or a new ORM bundle).
  
 
==== Common Abstractions ====
 
==== Common Abstractions ====

Revision as of 16:44, 20 August 2012

Design Specification: MOXy Footprint Reduction

ER 384399

Document History

Date Author Version Description & Notes
2012/07/05 Blaise Doughan Initial draft
2012/08/20 Blaise Doughan Pre-review Draft

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

Primary Goals

Below are the projected jar sizes based on some initial prototyping.

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)

Secondary Goals

Memory Improvement

Many of the current "core" classes contains information that is only required for object-relational mapping. This type of metadata needlessly increases the amount of memory MOXy requires to run. This refactor will reduce the amount of memory MOXy requires to run.

Ability to Release/Upgrade Separately

The new core bundle should not need to change frequently. Breaking the dependency between ORM and OXM should give us some flexibility if we ever wanted to release MOXy independent of JPA. More importantly it would allows users to upgrade to a newer version of MOXy without having to upgrade JPA.

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. Have the org.eclipse.persistence.common bundle contain things that are only common to both OXM and ORM.
  2. Move MOXy specific items into MOXy bundle.
  3. MOXy ORM specific items into JPA bundle (or a new ORM 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

Core Packages

The following would be the proposed package structure for the core bundle.

  • org.eclipse.persistence.core
  • org.eclipse.persistence.core.config
  • org.eclipse.persistence.core.descriptors
  • org.eclipse.persistence.core.exceptions
  • org.eclipse.persistence.core.mappings
  • org.eclipse.persistence.core.mappings.converters
  • org.eclipse.persistence.core.queries
  • org.eclipse.persistence.core.sessions
  • org.eclipse.persistence.internal.core
  • org.eclipse.persistence.internal.core.databaseaccess
  • org.eclipse.persistence.internal.core.descriptors
  • org.eclipse.persistence.internal.core.helper
  • org.eclipse.persistence.internal.core.identitymaps
  • org.eclipse.persistence.internal.core.queries
  • org.eclipse.persistence.internal.core.sessions

Core Class Structure

The core classes will contain type variables. The corresponding OXM and ORM classes will be specify the appropriate types in their concrete subclasses.

package org.eclipse.persistence.core;
 
...
 
public abstract class CoreProject<
    LOGIN extends CoreLogin,
    DESCRIPTOR extends CoreDescriptor>
    implements Serializable {
 
    protected Map<String, DESCRIPTOR> aliasDescriptors;
    protected LOGIN datasourceLogin;
    protected Map<Class, DESCRIPTOR> descriptors;
    protected String name;
    protected List<DESCRIPTOR> orderedDescriptors;
 
    /**
     * PUBLIC:
     * Add an alias for the descriptor.
     */
    public void addAlias(String alias, DESCRIPTOR descriptor) {
        if (aliasDescriptors == null) {
            aliasDescriptors = new HashMap(10);
        }
        aliasDescriptors.put(alias, descriptor);
    } 
 
    ...
 
}

OXM Project

A new OXM XMLProject class will be introduced that extends the CoreProject class.

public class XMLProject extends CoreProject<XMLLogin, XMLDescriptor> {
 
    ...
 
}

ORM Project

The existing ORM Project class will be modified to extend the new CoreProject class.

public class Project extends CoreProject<DatasourceLogin, ClassDescriptor> {
 
    ...
 
}

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