00001 /* 00002 * Copyright (c) 2000, 2020, Oracle and/or its affiliates. 00003 * 00004 * Licensed under the Universal Permissive License v 1.0 as shown at 00005 * http://oss.oracle.com/licenses/upl. 00006 */ 00007 #ifndef COH_EVOLVABLE_HPP 00008 #define COH_EVOLVABLE_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 // ----- forward declarations ----------------------------------------------- 00013 00014 COH_OPEN_NAMESPACE2(coherence,util) 00015 00016 class Binary; 00017 00018 COH_CLOSE_NAMESPACE2 00019 00020 COH_OPEN_NAMESPACE2(coherence,io) 00021 00022 00023 /** 00024 * The Evolvable interface is implemented by classes that require forwards- 00025 * and backwards-compatibility of their serialized form. An Evolvable class 00026 * has an integer version identifier <tt>n</tt>, where <tt>n >= 0</tt>. When 00027 * the contents and/or semantics of the serialized form of the Evolvable class 00028 * changes, the version identifier is increased. Two versions identifiers, 00029 * <tt>n1</tt> and <tt>n2</tt>, indicate the same version iff 00030 * <tt>n1 == n2</tt>; the version indicated by <tt>n2</tt> is newer than the 00031 * version indicated by <tt>n1</tt> iff <tt>n2 > n1</tt>. 00032 * 00033 * The Evolvable interface is designed to support the evolution of classes by 00034 * the addition of data. Removal of data cannot be safely accomplished as long 00035 * as a previous version of the class exists that relies on that data. 00036 * Modifications to the structure or semantics of data from previous versions 00037 * likewise cannot be safely accomplished as long as a previous version of the 00038 * class exists that relies on the previous structure or semantics of the 00039 * data. 00040 * 00041 * When an Evolvable is deserialized, it retains any unknown data that has 00042 * been added to newer versions of the class, and the version identifier for 00043 * that data format. When the Evolvable is subsequently serialized, it 00044 * includes both that version identifier and the unknown future data. 00045 * 00046 * When an Evolvable is deserialized from a data stream whose version 00047 * identifier indicates an older version, it must default and/or calculate the 00048 * values for any data fields and properties that have been added since that 00049 * older version. When the Evolvable is subsequently serialized, it includes 00050 * its own version identifier and all of its data. Note that there will be no 00051 * unknown future data in this case; future data can only exist when the 00052 * version of the data stream is newer than the version of the Evolvable 00053 * class. 00054 * 00055 * @author jh 2008.01.08 00056 */ 00057 class COH_EXPORT Evolvable 00058 : public interface_spec<Evolvable> 00059 { 00060 // ----- handle definitions --------------------------------------------- 00061 00062 public: 00063 /** 00064 * Binary View definition. 00065 */ 00066 typedef TypedHandle<const coherence::util::Binary> BinaryView; 00067 00068 00069 // ----- Evolvable interface -------------------------------------------- 00070 00071 public: 00072 /** 00073 * Determine the serialization version supported by the implementing 00074 * class. 00075 * 00076 * @return the serialization version supported by this Evolvable 00077 */ 00078 virtual int32_t getImplVersion() const = 0; 00079 00080 /** 00081 * Obtain the version associated with the data stream from which this 00082 * Evolvable was deserialized. If the Object was constructed (not 00083 * deserialized), the data version is the same as the implementation 00084 * version. 00085 * 00086 * @return the version of the data used to initialize this Evolvable, 00087 * greater than or equal to zero 00088 */ 00089 virtual int32_t getDataVersion() const = 0; 00090 00091 /** 00092 * Set the version associated with the data stream with which this 00093 * Evolvable is being deserialized. 00094 * 00095 * @param nVersion the version of the data in the data stream that 00096 * will be used to deserialize this Object; greater 00097 * than or equal to zero 00098 */ 00099 virtual void setDataVersion(int32_t nVersion) = 0; 00100 00101 /** 00102 * Return all the unknown remainder of the data stream from which 00103 * this Evolvable was deserialized. The remainder is unknown because 00104 * it is data that was originally written by a future version of this 00105 * Evolvable's class. 00106 * 00107 * @return future data in binary form 00108 */ 00109 virtual BinaryView getFutureData() const = 0; 00110 00111 /** 00112 * Store the unknown remainder of the data stream from which this 00113 * Evolvable is being deserialized. The remainder is unknown because 00114 * it is data that was originally written by a future version of this 00115 * Evolvable's class. 00116 * 00117 * @param vBinFuture future data in binary form 00118 */ 00119 virtual void setFutureData(BinaryView vBinFuture) = 0; 00120 }; 00121 00122 COH_CLOSE_NAMESPACE2 00123 00124 #endif // COH_EVOLVABLE_HPP