[[BackLinksMenu]] = Analysis = == Overview == Property Utilities are additions to the Properties Library that provide extra functionality. == Task requirements == Add utilites that: * Assign values to a property (except Auto Properties) * Clone objects with properties * Other - discuss with the team if something else is needed at this iteration == Task result == The task result should be source code (with unit tests included). == Implementation idea == Cloning should keep only those properties that are needed. == Related == [wiki:PRO_LIB_CORE_TUTORIAL] == How to demo == Present the utilities to the team and run unit tests to demonstrate them. = Design = !ProUtil should provide functionality for "smart" copying of properties. "Smart" means that depending on specific objects a person can expect only the reference to the object to be copied or to change a little the copy to identify it as a copy or can expect a "deep" copy (means copy not only the object, but also objects used inside). So "smart" copy should follow some expected behaviour. What the common behavior is depends not only on object type but also on its connection to other objects and their mutability i.e. whether it is in a parent-child relation or whether points to an object that is mutable or immutable or automatic. * New annotation - @Shared A new annotation should be created in org.sophie2.core.prolib.annot. This annotation is for the smart copying of objects. If a property is marked as @Shared, this means that the value it holds should be the same for all objects using this property. In other words, when copying such property the new property should hold a reference to the value, not a clone of the value. * Assign - public static void assign(T dest, T source) in the !ProUtil class in org.sophie2.core.prolib.util package The assign() method should copy the values of all properties of the source !ProObject to the destionation !ProObject. It should be a "smart" copy, so for each property should be decided how to be copied. Implementation can just call a private assign() method that works for a particular property and can decide how to copy it. * Clone - public static T clone(T src) in the !ProUtil class in org.sophie2.core.prolib.util package The clone() method should make a new !ProObject instance which is a copy of the original object. The properties in the new instance have their values assigned from the original object. Implementation can just make a new !ProObject instance and then call the assign() method to copy all property values from the original to the new instance. * Single property assign - private static void assign(!ProObject dest, !ProObject source, String propId) in the !ProUtil class in org.sophie2.core.prolib.util package The assign() method should take care about property types and annotations to decide what to do when trying to copy data. Here are all the cases: ||property types||relation/annotation||value class||value action||comment|| ||!ValueProperty ||@Own ||immutable ||error |||| || || ||pro-obj ||pro.clone |||| || || ||else ||error |||| || ||@Shared||all ||copy ref |||| || ||none ||immutable ||copy ref |||| || || ||else ||error |||| |||||||||||| ||!ParentProperty || ||all ||set null ||Better decide whether to keep the same parent in each case.|| |||||||||||| ||!FinalProperty || --> || --> || --> ||Same as !ValueProperty. The assign operation should be possible only once, as the set operation is.|| |||||||||||| ||!ResourceProperty || --> || --> ||none ||do nothing|| ||!AutoProperty || --> || --> ||none ||do nothing|| |||||||||||| ||!ValueListProperty|| --> || --> || --> ||Create a new list and apply the rules for !ValueProperty to the elements of the list as if they are single values|| ||!AutoListProperty || --> || --> ||none ||do nothing|| * Tests [source:trunk/sophie2-platform/modules/org.sophie2.core/src/test/java/org/sophie2/core/prolib/util/ProUtilTest.java?rev=728] = Implementation = * A @Shared annotation created [source:trunk/sophie2-platform/modules/org.sophie2.core/src/main/java/org/sophie2/core/prolib/annot/Shared.java?rev=744] * The public clone() method is refactored to use directly the public assign() method * The public assign() method calls the private assign() method for each property * The private assign() method has an if statement for each case described in the design [source:trunk/sophie2-platform/modules/org.sophie2.core/src/main/java/org/sophie2/core/prolib/util/ProUtil.java?rev=932] = Testing = = Comments = = Log = [[Include(wiki:PRO_LIB_UTILS_R0_LOG)]]