1 /*
2 * Copyright 2013 Chris Pheby
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.jadira.reflection.cloning.api;
17
18 import java.lang.invoke.MethodHandle;
19 import java.util.Set;
20
21 import org.jadira.reflection.cloning.annotation.Transient;
22
23 /**
24 * A clone driver defines the features of a class that is used to bootstrap and provide context to a
25 * cloning operation, typically (but not always), a {@link Cloner} *
26 */
27 public interface CloneDriver extends CloneImplementor {
28
29 /**
30 * Gets the built in implementor for the given class
31 * @param clazz The class
32 * @return A CloneImplementor
33 */
34 public CloneImplementor getBuiltInImplementor(Class<?> clazz);
35
36 /**
37 * Retrieves the registered implementor for the given class
38 * @param clazz The class
39 * @return A CloneImplementor
40 */
41 CloneImplementor getImplementor(Class<?> clazz);
42
43 /**
44 * Retrieves the registered implementor for the given class
45 * @param clazz The class
46 * @return A CloneImplementor
47 */
48 CloneImplementor getAnnotationImplementor(Class<?> clazz);
49
50 /**
51 * Put the registered implementor for the given class
52 * @param clazz The class
53 * @param implementor Implementor to register
54 */
55 void putAnnotationImplementor(Class<?> clazz, CloneImplementor implementor);
56
57
58 /**
59 * If true, then any class that implements {@link Cloneable} will be cloned using the
60 * {@link Object#clone()} method.
61 * @return Default value is false
62 */
63 boolean isUseCloneable();
64
65 /**
66 * Returns the clone() method for the indicated class
67 * @param clazz The class to obtain the method for
68 * @return The related MethodHandle
69 */
70 MethodHandle getCloneMethod(Class<?> clazz);
71
72 /**
73 * Put the clone() method for the indicated class
74 * @param clazz The class to obtain the method for
75 * @param handle The related MethodHandle
76 */
77 void putCloneMethod(Class<?> clazz, MethodHandle handle);
78
79 /**
80 * If false, indicates that fields modified by the transient keyword should not be cloned,
81 * instead being replaced with null.
82 * @return Default value is true
83 */
84 boolean isCloneTransientFields();
85
86 /**
87 * If false, indicates that fields annotated by the {@link Transient} annotation should not be
88 * cloned, instead being replaced with null.
89 * @return Default value is false
90 */
91 boolean isCloneTransientAnnotatedFields();
92
93 /**
94 * If false, indicates that classes known to be immutable should be not cloned. Immutables are
95 * identified by the @Immutable annotation; are one of a select set of known JDK immutable
96 * classes; or are detected as immutable by the Mutability Detector tool (if it was found on the
97 * classpath).
98 * @return Default value is false
99 */
100 boolean isCloneImmutable();
101
102 /**
103 * A list of classes that should be treated as immutable.
104 * @return immutableClasses The immutable classes
105 */
106 Set<Class<?>> getImmutableClasses();
107
108 /**
109 * A list of classes that should not be cloned.
110 * @return immutableClasses The classes which should be be cloned
111 */
112 Set<Class<?>> getNonCloneableClasses();
113
114 /**
115 * Indicates whether custom clone implementors are enabled
116 * @return Default value is true
117 */
118 boolean isUseCloneImplementors();
119
120 /**
121 * Indicates whether synthetic fields should be cloned
122 * @return cloneSyntheticFields Default is false
123 */
124 boolean isCloneSyntheticFields();
125
126 /**
127 * Indicates whether the given object <em>instance</em> should be treated as immutable
128 * @param instance The instance to check for whether it is registered as immutable
129 * @return True if the object is registered as immutable
130 */
131 boolean isImmutableInstance(Object instance);
132
133 /**
134 * Stores an object instance to be treated as immutable
135 * @param instance Object to be considered immutable
136 */
137 void putImmutableInstance(Object instance);
138
139 /**
140 * Indicates whether to track references
141 * @return trackReferences Default is true
142 */
143 boolean isTrackReferences();
144
145 /**
146 * Indicates whether to also track references for flat classes when tracking references.
147 * @return trackReferences Default is false
148 */
149 boolean isTrackReferencesForFlatClasses();
150 }