Add usage information

Add information about how to implement Oslo Versioned Objects
in your project.

Change-Id: I097d38fcd95b9ca6a7430046b23dda9877fd65fc

doc/source/usage.rst

@@ -2,6 +2,130 @@
  Usage
 =======
 
-To use oslo.versionedobjects in a project::
+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.
 
-    import oslo_versionedobjects