001/*
002 *  Copyright 2013 Chris Pheby
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.jadira.reflection.cloning.api;
017
018import java.util.IdentityHashMap;
019
020/**
021 * A CloneImplementor represents an atomic cloning capability. The interface is implemented by
022 * classes that can clone a specific type, as well as by {@link CloneStrategy} and
023 * {@link CloneDriver} implementations. In general users do not work with the methods on this class,
024 * using {@link Cloner} instead
025 */
026public interface CloneImplementor {
027
028        /**
029         * Create a new, uninitialised instance of the given class (if supported). Depending on
030         * strategy, this may or may not initialise instance fields, and may or may not invoke
031         * constructors.
032         * @param c Type to create instance of
033         * @param <T> The type of the instance to be constructed
034         * @return The new instance
035         */
036        <T> T newInstance(final Class<T> c);
037
038        /**
039         * True if this implementor can clone the given class
040         * @param clazz The class
041         * @return True if cloneable, false otherwise
042         */
043        boolean canClone(Class<?> clazz);
044
045        /**
046         * Performs a clone.
047         * @param obj Object to clone
048         * @param context The CloneDriver that initiated the request
049         * @param referencesToReuse Any references for objects already cloned to ensure reference
050         *            identity is preserved
051         * @param stackDepth The number of objects already cloned in the current data structure
052         * @param <T> The type of the object to be cloned
053         * @return The cloned object
054         */
055        <T> T clone(T obj, CloneDriver context, IdentityHashMap<Object, Object> referencesToReuse, long stackDepth);
056}