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

Reduce the size of X so that is no more that 600 KB.

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.oxm_2.4.0.v20120608-r11652.jar

X KB

org.eclipse.persistence.antlr_3.2.0.v201206041011.jar

190 KB

(726 + X) KB (XML) / (916 + X) KB (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.

Concepts

Package Splitting

This is when classes from the same package are distributed among different bundles. Modularity frameworks discourage splitting packages and therefore is something that we can not do.

Backwards Compatibility

Support applications written/compiled against previous versions of EclipseLink. Failing to be backwards compatible will have a negative impact on our user base. Anything less than binary compatibility will affect applications that include EclipseLink.

Binary Compatible

Applications compiled against EclipseLink before the footprint reduction will continue to work against EclipseLink after the footprint reduction.

Source Code Compatible

Applications compiled against EclipseLink before the footprint reduction will not continue to work against EclipseLink after the footprint reduction. The user won't need to modify their source code, but they will need to recompile it against the new version of EclipseLink.

Incompatible

The user would need to make changes to their code to work with the new version of EclipseLink. We could leverage the "package renamer" tool to make it easier for users to migrate their code to the new APIs.

Generics & Parameterized Types

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

MOXy's DOM & SAX Platforms

MOXy contains two object-to-XML implementations: DOMPlatform and SAXPlatform. DOMPlatform was the first implementation and closely mirrors the mechanisms used by EclipseLink's object-to-relational mapping. SAXPlatform was introduced second as a performance improvement and now has almost completely replaced all usages of DOMPlatform.

Requirements

Existing classes must remain binary compatible. This means that applications compiled against a previous version of EclipseLink must continue to run against the version of EclipseLink that implements the footprint reduction. Breaking backwards (binary) compatibility would require us to due a whole number version increment (i.e. 2.4.-> 3.0 and not 2.4 -> 2.5).

Plan

New Core Abstractions

The following are core classes that are required by MOXy. These classes currently have dependencies on other ORM specific classes. As part of this feature new super classes will be created for each of these classes to contain the shared behaviour and state. The abstractions will maintain the same package structure under:

org.eclipse.persistence.core

org.eclipse.persistence.internal.core

Public Classes

This refactoring will affect the following public classes. Binary compatibility will be maintained as a result of this refactoring.

org.eclipse.persistence.descriptors.ClassDescriptor

org.eclipse.persistence.descriptors.DescriptorEvent

org.eclipse.persistence.descriptors.DescriptorEventManager

org.eclipse.persistence.descriptors.InheritancePolicy

org.eclipse.persistence.mappings.DatabaseMapping

org.eclipse.persistence.mappings.converters.Converter

org.eclipse.persistence.sessions.Session

Internal Classes

This refactoring will affect the following internal classes. Even though these classes are technically internal they are probably leveraged by some of our users so binary compatibility will be maintained for these classes as well.

org.eclipse.persistence.internal.databaseaccess.Platform

org.eclipse.persistence.internal.descriptors.ObjectBuilder

org.eclipse.persistence.internal.helper.ClassConstants

org.eclipse.persistence.internal.helper.ConversionManager

org.eclipse.persistence.internal.helper.DatabaseField

org.eclipse.persistence.internal.helper.Helper

org.eclipse.persistence.internal.sessions.AbstractRecord

org.eclipse.persistence.internal.sessions.AbstractSession

Areas Where We Need to Duplicate Code

Possible Approaches

Option #1 - Move ORM Specific Packages to JPA Bundle

Using the Class Dependency Analyzer (CDA) tool I was able to determine that the following packages could be removed from the core bundle without affecting MOXy. Since we cannot split packages only whole packages can be moved. The classes in these packages represent approximately 170 KB of the core bundle.

Design / Functionality

High Level

MOXy contains two mechanisms for converting objects to/from XML: DOMPlatform and SAXPlatform. DOMPlatform has strong roots in ORM processing (supports queries, change sets, etc) and is leveraged by EclipseLink EIS. SAXPlatform was introduced to optimize the binding use case as part of the JAXB implementation. The SAXPlatform shares much less logic with the ORM layer than the DOMPlatform does, but shares all the same dependencies. The goal of this feature is to extract only the code necessary to make the SAXPlatform work in order to support the JAXB use case.

Bundle Changes

Introduce a new org.eclipse.persistence.bind bundle to contain common classes and interfaces and the light-weight OXM implementation.

Modify the core bundle to depend on the new bind bundle.

Move MOXy specify items from core into MOXy bundle

Move old OXM code into separate bundle for backwards compatibility

Common Abstractions

A true common core will be created to represent the common behaviour between OXM and ORM. This common core will consist of both interfaces and abstract classes.

Abstract Classes

Where possible common behaviour will be represented as abstract classes. This allows real code to be shared between the ORM and OXM layers. To preserve binary backwards compatibility where the current ORM classes are modified to extend the new abstract classes they will need a method with the correct method signature that simply calls/returns the super method.

It will be possible to introduce abstract classes where there is a shared concept that isn't part of an inheritance hierarchy (i.e. Project, Descriptor, Mapping).

AbstractProject, AbstractDescriptor, and AbstractMapping would be new abstract classes to represent common functionality.

Project, ClassDescriptor, and DatabaseMapping would be changed to extend their counterparts from the common abstract classes. This would be done in such a way as to maintain binary compatibility.

A new lightweight MOXy implementation of these classes would be created.

Much of the processing for the SAXPlatform is done in the internal.oxm packages. Where this logic depends on core classes interfaces will be created an the interanl.oxm logic will be updated to use the new interfaces instead. The core classes will be updated to implement/extend the new interfaces so that all current code continues to run.

Phase #2 - Pull internal.oxm Classes and Common Classes/Interfaces Into a New org.eclipse.persistence.bind Bundle

The internal.oxm classes and the new common classes/interfaces will form the basis of a new org.eclipse.persistence.bind bundle. The core bundle will be dependent on this new bundle. During this move the XML prefix on class names will be dropped, and the internal.oxm package will be renamed internal.bind. This is to reflect that MOXy now supports more than just object-to-XML mapping (MOXy also supports object-to-JSON mapping).

Phase #3 - Implement Light Weight Version of Core Classes/Interfaces

A lightweight version of the core classes/interfaces will be implemented in the org.eclipse.persistence.bind package. Where possible the corresponding implementations in the org.eclipse.persistence.oxm package will be updated to extend their counterparts in the bind bundle so that there is as little code duplication as possible.

Once the core bundle is no longer dependent upon the oxm classes they could be moved into there own bundle. This would reduce the footprint of the core bundle. The oxm classes would still be available for anyone that required them for backwards compatibility reasons.

Testing

Binary Compatible Testing

Testing would be required to ensure that binary compatibility is kept, for the areas we plan on maintaining binary compatibility.

API

Core Packages

The common core classes will be under the following package. The final package structure will be reviewed once all the abstractions are known.

org.eclipse.persistence.internal.core

Proposed Class Structure

New Abstractions (i.e. Descriptor)

A set of classes/interfaces will be created to represent the core functionality that is common to both object-to-XML and object-to-relational mapping. Type variables will be leveraged so that the OXM and ORM implementations can be further specialized.

The new light weight MOXy will provide a new implementation of these core classes/interfaces (the class names below are for demonstration purposes only). The existing core OXM classes will continue to work (see below).

The existing core classes will be modified to extends/implement these classes/interfaces supplying the appropriate type variables. Everything else about the core classes will stay the same ensuring backwards compatibility.

Documentation

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

Doug/Peter

Does the implementation of this feature require us to bump the version number to 3.0?

2

Doug/Peter/Blaise

Do we need to maintain binary compatibility of the native OXM APIs?

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

Remove Need for ASM Bundle

There are a few areas where MOXy makes use of the ASM bundle to generate bytecodes. Some feature work could be done to eliminate the need to generate these bytecodes and the ASM dependency could be dropped removing it from the install footprint.

Remove Need for ANTLR Bundle

Currently the ANTLR bundle is required to parse JSON documents. Once a standard JSON parser is available (see [1]), we can remove dependency on ANTLR from MOXy.

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.