1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
=======
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.
|
