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