org.glassfish.pfl.dynamic.copyobject.impl.Notes.txt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of pfl-dynamic Show documentation
Functionality that may include class generation
There is a newer version: 5.0.0
#
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
#
# Copyright (c) 1997-2018 Oracle and/or its affiliates. All rights reserved.
#
# The contents of this file are subject to the terms of either the GNU
# General Public License Version 2 only ("GPL") or the Common Development
# and Distribution License("CDDL") (collectively, the "License").  You
# may not use this file except in compliance with the License.  You can
# obtain a copy of the License at
# https://oss.oracle.com/licenses/CDDL+GPL-1.1
# or LICENSE.txt.  See the License for the specific
# language governing permissions and limitations under the License.
#
# When distributing the software, include this License Header Notice in each
# file and include the License file at LICENSE.txt.
#
# GPL Classpath Exception:
# Oracle designates this particular file as subject to the "Classpath"
# exception as provided by Oracle in the GPL Version 2 section of the License
# file that accompanied this code.
#
# Modifications:
# If applicable, add the following below the License Header, with the fields
# enclosed by brackets [] replaced by your own identifying information:
# "Portions Copyright [year] [name of copyright owner]"
#
# Contributor(s):
# If you wish your version of this file to be governed by only the CDDL or
# only the GPL Version 2, indicate your decision by adding "[Contributor]
# elects to include this software in this distribution under the [CDDL or GPL
# Version 2] license."  If you don't indicate a single choice of license, a
# recipient has the option to distribute your version of this file under
# either the CDDL, the GPL Version 2 or to extend the choice of license to
# its licensees as provided above.  However, if you add GPL Version 2 code
# and therefore, elected the GPL Version 2 license, then the option applies
# only if the new code is made subject to such option by the copyright
# holder.
#

Note on improving the reflective copy object architecture.

Basic abstractions:

/** Creates an instance of an ObjectCopier to be used for a single session.
 */
ObjectCopierFactory {
    ObjectCopier make() ;
}

/** Used to copy objects in a single session: multiple calls to the
 * same ObjectCopier instance will share all aliases.
ObjectCopier {
    Object copy( Object obj ) throws ReflectiveCopyException ;
}

------------------------
Reflective case:

/** Used to copy an Object of a particular type.  Preserves aliasing through
 * oldToNew.
 */
interface ClassCopier {
    Object copy( IdentityHashMap oldToNew, Object source ) throws ReflectiveCopyException ;
}

/** Create a ClassCopier for a particular type.
 */
ClassCopierFactory {
    ClassCopier get( Class cls ) throws ReflectiveCopyException ;
}

Use filter pattern: use a chain of ClassCopierFactory instances, take first non-null result.

Special ClassCopier instances:
    DefaultClassCopiers
	ClassCopier makeMapCopier( ClassCopierFactory ccf ) 
	ClassCopier getIdentityCopier() 
	ClassCopier getErrorCopier()

ClassCopierFactory instances:

    - A client may create a special ClassCopierFactory with arbitrary behavior.
    - An ArrayClassCopierFactory that returns a ClassCopier for an array, and 
      null for non-array
    - A OrdinaryClassCopierFactory that returns a ClassCopier for any Class,
      and throws ReflectiveCopyException if it cannot create a ClassCopier.
    - An ImmutableClassCopierFactory that returns an IdentityClassCopier if
      the class is immutable (also has registration API).
    - A CachingClassCopierFactory that maintains a cache of know ClassCopier
      instances for particular classes (also has a registration API).
    - PipelineCopierFactory:
	- Does Caching -> Special (may be no-op) -> Array -> Ordinary
	- Updates cache if needed
	- Provides API for:
	    - registration of know ClassCopier instances
	    - registration of immutable classes (go straight to cache)
	    - registration of optional special ClassCopierFactory
	- passes itself to Array and Ordinary ClassCopierFactory instances

    DefaultClassCopierFactories:
	ClassCopierFactory makeCachingClassCopierFactory()
	ClassCopierFactory makeArrayClassCopierFactory( ClassCopierFactory ) 
	ClassCopierFactory makeOrdinaryClassCopierFactory( ClassCopierFactory )