From e99653b60c870959099315a5ec2c0b14718b434b Mon Sep 17 00:00:00 2001
From: Brian Elliott <brian.elliott@rackspace.com>
Date: Fri, 16 Nov 2012 15:45:59 +0000
Subject: [PATCH] Add generic customization hooks via decorator.

Hooks add the ability to insert custom code around operations that
declare a named hook:

e.g.

@hooks.add_hooks('create_instance')
def create_instance(....):
   ....

The above hook allows Hook objects to be run 'pre' and 'post' the
execution of create_instance()

Hook objects are discovered via the setuptools entry point group
'nova.hooks'.

Change-Id: I3961df12ef415085de7459438967edacc34500c2
---
 doc/source/devref/hooks.rst | 57 +++++++++++++++++++++++++++++++++++++
 doc/source/devref/index.rst |  1 +
 2 files changed, 58 insertions(+)
 create mode 100644 doc/source/devref/hooks.rst

diff --git a/doc/source/devref/hooks.rst b/doc/source/devref/hooks.rst
new file mode 100644
index 000000000..a53e37352
--- /dev/null
+++ b/doc/source/devref/hooks.rst
@@ -0,0 +1,57 @@
+Hooks
+=====
+
+Hooks provide a mechanism to extend Nova with custom code through a plugin
+mechanism.
+
+Named hooks are added to nova code via a decorator that will lazily load
+plugin code matching the name.  The loading works via setuptools
+`entry points`_.
+
+.. _`entry points`: http://packages.python.org/distribute/pkg_resources.html#entry-points
+
+What are hooks good for?
+------------------------
+
+Hooks are good for anchoring your custom code to Nova internal APIs.
+
+What are hooks NOT good for?
+----------------------------
+
+Hooks should not be used when API stability is a key factor.  Internal APIs may
+change.  Consider using a notification driver if this is important to you.
+
+Declaring hooks in the Nova codebase
+------------------------------------
+
+The following example declares a *resize_hook* around the *resize_instance* method::
+
+    from nova import hooks
+
+    @hooks.add_hook("resize_hook")
+    def resize_instance(self, context, instance, a=1, b=2):
+        ...
+
+Hook objects can now be attached via entry points to the *resize_hook*.
+
+Adding hook object code
+-----------------------
+
+1. Setup a Python package with a setup.py file.
+2. Add the following to the setup.py setup call::
+
+    entry_points = [
+        'nova.hooks': [
+            'resize_hook': your_package.hooks.YourHookClass,
+        ]
+    ]
+
+3. *YourHookClass* should be an object with *pre* and/or *post* methods::
+
+    class YourHookClass(object):
+
+        def pre(self, *args, **kwargs):
+            ....
+
+        def post(self, rv, *args, **kwargs):
+            ....
diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst
index 239848c62..0b7883f7b 100644
--- a/doc/source/devref/index.rst
+++ b/doc/source/devref/index.rst
@@ -43,6 +43,7 @@ Background Concepts for Nova
    filter_scheduler
    multinic
    rpc
+   hooks
 
 Other Resources
 ---------------