..
      Copyright 2015 IBM Corp.
      All Rights Reserved.

      Licensed under the Apache License, Version 2.0 (the "License"); you may
      not use this file except in compliance with the License. You may obtain
      a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
      License for the specific language governing permissions and limitations
      under the License.

Versioned Objects
=================

Magnum uses the `oslo.versionedobjects library
<http://docs.openstack.org/developer/oslo.versionedobjects/index.html>`_ to
construct an object model that can be communicated via RPC. These objects have
a version history and functionality to convert from one version to a previous
version. This allows for 2 different levels of the code to still pass objects
to each other, as in the case of rolling upgrades.

Object Version Testing
----------------------

In order to ensure object versioning consistency is maintained,
oslo.versionedobjects has a fixture to aid in testing object versioning.
`oslo.versionedobjects.fixture.ObjectVersionChecker
<http://docs.openstack.org/developer/oslo.versionedobjects/api/fixture.html#oslo_versionedobjects.fixture.ObjectVersionChecker>`_
generates fingerprints of each object, which is a combination of the current
version number of the object, along with a hash of the RPC-critical parts of
the object (fields and remotable methods).

The tests hold a static mapping of the fingerprints of all objects. When an
object is changed, the hash generated in the test will differ from that held in
the static mapping. This will signal to the developer that the version of the
object needs to be increased. Following this version increase, the fingerprint
that is then generated by the test can be copied to the static mapping in the
tests. This symbolizes that if the code change is approved, this is the new
state of the object to compare against.

Object Change Example
'''''''''''''''''''''

The following example shows the unit test workflow when changing an object
(Cluster was updated to hold a new 'foo' field)::

    tox -e py27 magnum.tests.unit.objects.test_objects

This results in a unit test failure with the following output:

  .. code-block:: python

    testtools.matchers._impl.MismatchError: !=:
    reference = {'Cluster': '1.0-35edde13ad178e9419e7ea8b6d580bcd'}
    actual    = {'Cluster': '1.0-22b40e8eed0414561ca921906b189820'}

  .. code-block:: console

    : Fields or remotable methods in some objects have changed. Make sure the versions of the objects has been bumped, and update the hashes in the static fingerprints tree (object_data). For more information, read http://docs.openstack.org/developer/magnum/objects.html.

This is an indication that me adding the 'foo' field to Cluster means I need
to bump the version of Cluster, so I increase the version and add a comment
saying what I changed in the new version:

  .. code-block:: python

    @base.MagnumObjectRegistry.register
    class Cluster(base.MagnumPersistentObject, base.MagnumObject,
                  base.MagnumObjectDictCompat):
        # Version 1.0: Initial version
        # Version 1.1: Added 'foo' field
        VERSION = '1.1'

Now that I have updated the version, I will run the tests again and let the
test tell me the fingerprint that I now need to put in the static tree:

  .. code-block:: python

    testtools.matchers._impl.MismatchError: !=:
    reference = {'Cluster': '1.0-35edde13ad178e9419e7ea8b6d580bcd'}
    actual    = {'Cluster': '1.1-22b40e8eed0414561ca921906b189820'}

I can now copy the new fingerprint needed
(1.1-22b40e8eed0414561ca921906b189820), to the object_data map within
magnum/tests/unit/objects/test_objects.py:

  .. code-block:: python

    object_data = {
        'Cluster': '1.1-22b40e8eed0414561ca921906b189820',
        'ClusterTemplate': '1.0-06863f04ab4b98307e3d1b736d3137bf',
        'Certificate': '1.0-69b579203c6d726be7878c606626e438',
        'MyObj': '1.0-b43567e512438205e32f4e95ca616697',
        'X509KeyPair': '1.0-fd008eba0fbc390e0e5da247bba4eedd',
        'MagnumService': '1.0-d4b8c0f3a234aec35d273196e18f7ed1',
    }

Running the unit tests now shows no failure.

If I did not update the version, and rather just copied the new hash to the
object_data map, the review would show the hash (but not the version) was
updated in object_data. At that point, a reviewer should point this out, and
mention that the object version needs to be updated.

If a remotable method were added/changed, the same process is followed, because
this will also cause a hash change.
