Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/io/Evolvable.hpp

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