bdcce8b8ad
Minor formatting improvements found during the document check are also done. Change-Id: I55d582100c40961a5b0f5ec4b2ea9a55f2d8d8a1
132 lines
4.5 KiB
ReStructuredText
132 lines
4.5 KiB
ReStructuredText
=======
|
|
Usage
|
|
=======
|
|
|
|
Incorporating oslo.versionedobjects into your projects can be accomplished in
|
|
the following steps:
|
|
|
|
1. `Add oslo.versionedobjects to requirements`_
|
|
2. `Create objects subdirectory and a base.py inside it`_
|
|
3. `Create base object with the project namespace`_
|
|
4. `Create other base objects if needed`_
|
|
5. `Implement objects and place them in objects/\*.py`_
|
|
6. `Implement extra fields in objects/fields.py`_
|
|
7. `Create object registry and register all objects`_
|
|
8. `Create and attach the object serializer`_
|
|
9. `Implement the indirection API`_
|
|
|
|
|
|
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
|
|
---------------------------------------------
|
|
|
|
:class:`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
|
|
:class:`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
|
|
:class:`oslo_versionedobjects.field.Field` and overwriting the `from_primitive`
|
|
and `to_primitive` methods.
|
|
|
|
By subclassing :class:`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
|
|
-----------------------------------------------
|
|
|
|
:class:`oslo_versionedobjects.base.VersionedObjectRegistry`
|
|
|
|
The place where all objects are registered. All object classes should be
|
|
registered by the :attr:`oslo_versionedobjects.base.ObjectRegistry.register`
|
|
class decorator.
|
|
|
|
|
|
|
|
Create and attach the object serializer
|
|
---------------------------------------
|
|
|
|
:class:`oslo_versionedobjects.base.VersionedObjectSerializer`
|
|
|
|
To transfer objects by RPC, subclass the
|
|
:class:`oslo_versionedobjects.base.VersionedObjectSerializer` setting the
|
|
OBJ_BASE_CLASS property to the previously defined Object class.
|
|
|
|
Connect the serializer to oslo_messaging:
|
|
|
|
.. code:: python
|
|
|
|
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
|
|
-----------------------------
|
|
|
|
:class:`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.
|
|
|