Usage¶

Add oslo.versionedobjects to requirements¶

To use oslo.versionedobjects in an OpenStack project remember to add it to the requirements.txt

Create objects subdirectory and a base.py inside it¶

Objects reside in the <project>/objects directory and this is the place from which all objects should be imported.

Start the implementation by creating objects/base.py with these main classes:

Create base object with the project namespace¶

oslo_versionedobjects.base.VersionedObject

The VersionedObject base class for the project. You have to fill up the OBJ_PROJECT_NAMESPACE property. OBJ_SERIAL_NAMESPACE is used only for backward compatibility and should not be set in new projects.

Create other base objects if needed¶

class:oslo_versionedobjects.base.VersionedPersistentObject

A mixin class for persistent objects can be created, defining repeated fields like created_at, updated_at. Fields are defined in the fields property (which is a dict).

If objects were previously passed as dicts (a common situation), a oslo_versionedobjects.base.VersionedObjectDictCompat can be used as a mixin class to support dict operations.

Implement objects and place them in objects/*.py¶

Objects classes should be created for all resources/objects passed via RPC as IDs or dicts in order to:

• spare the database (or other resource) from extra calls
• pass objects instead of dicts, which are tagged with their version
• handle all object versions in one place (the obj_make_compatible method)

To make sure all objects are accessible at all times, you should import them in __init__.py in the objects/ directory.

Implement extra fields in objects/fields.py¶

New field types can be implemented by inheriting from oslo_versionedobjects.field.Field and overwriting the from_primitive and to_primitive methods.

By subclassing oslo_versionedobjects.fields.AutoTypedField you can stack multiple fields together, making sure even nested data structures are being validated.

Create object registry and register all objects¶

oslo_versionedobjects.base.VersionedObjectRegistry

The place where all objects are registered. All object classes should be registered by the oslo_versionedobjects.base.ObjectRegistry.register class decorator.

Create and attach the object serializer¶

oslo_versionedobjects.base.VersionedObjectSerializer

To transfer objects by RPC, subclass the oslo_versionedobjects.base.VersionedObjectSerializer setting the OBJ_BASE_CLASS property to the previously defined Object class.

Connect the serializer to oslo_messaging:

serializer = RequestContextSerializer(objects_base.MagnumObjectSerializer())
target = messaging.Target(topic=topic, server=server)
self._server = messaging.get_rpc_server(transport, target, handlers, serializer=serializer)

Implement the indirection API¶

oslo_versionedobjects.base.VersionedObjectIndirectionAPI

oslo.versionedobjects supports remotable method calls. These are calls of the object methods and classmethods which can be executed locally or remotely depending on the configuration. Setting the indirection_api as a property of an object relays the calls to decorated methods through the defined RPC API. The attachment of the indirection_api should be handled by configuration at startup time.

Second function of the indirection API is backporting. When the object serializer attempts to deserialize an object with a future version, not supported by the current instance, it calls the object_backport method in an attempt to backport the object to a version which can then be handled as normal.