com.jme3.util.clone.JmeCloneable Maven / Gradle / Ivy
Show all versions of jme3-core Show documentation
/*
* Copyright (c) 2016-2021 jMonkeyEngine
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* * Neither the name of 'jMonkeyEngine' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package com.jme3.util.clone;
/**
* Indicates an object that wishes to more actively participate in the
* two-part deep copying process provided by the Cloner. Objects implementing
* this interface can access the already cloned object graph to resolve
* their local dependencies in a way that will be equivalent to the
* original object graph. In other words, if two objects in the graph
* share the same target reference then the cloned version will share
* the cloned reference.
*
* For example, if an object wishes to deep clone one of its fields
* then it will call cloner.clone(object) instead of object.clone().
* The cloner will keep track of any clones already created for 'object'
* and return that instead of a new clone.
*
* Cloning of a JmeCloneable object is done in two parts. First,
* the standard Java clone() method is called to create a shallow clone
* of the object. Second, the cloner will call the cloneFields() method
* to let the object deep clone any of its fields that should be cloned.
*
* This two part process is necessary to facilitate circular references.
* When an object calls cloner.clone() during its cloneFields() method, it
* may get only a shallow copy that will be filled in later.
*
* @author Paul Speed
*/
public interface JmeCloneable extends Cloneable {
/**
* Performs a regular shallow clone of the object. Some fields
* may also be cloned but generally only if they will never be
* shared with other objects. (For example, local Vector3fs and so on.)
*
* This method is separate from the regular clone() method
* so that objects might still maintain their own regular java clone()
* semantics (perhaps even using Cloner for those methods). However,
* because Java's clone() has specific features in the sense of Object's
* clone() implementation, it's usually best to have some path for
* subclasses to bypass the public clone() method that might be cloning
* fields and instead get at the superclass protected clone() methods.
* For example, through super.jmeClone() or another protected clone
* method that some base class eventually calls super.clone() in.
*
* @return a new instance
*/
public Object jmeClone();
/**
* Implemented to perform deep cloning for this object, resolving
* local cloned references using the specified cloner. The object
* can call cloner.clone(fieldValue) to deep clone any of its fields.
*
* Note: during normal clone operations the original object
* will not be needed as the clone has already had all of the fields
* shallow copied.
*
* @param cloner The cloner that is performing the cloning operation. The
* cloneFields method can call back into the cloner to make
* clones of its subordinate fields.
* @param original The original object from which this object was cloned.
* This is provided for the very rare case that this object needs
* to refer to its original for some reason. In general, all of
* the relevant values should have been transferred during the
* shallow clone, and this object need only clone what it wants.
*/
public void cloneFields(Cloner cloner, Object original);
}