Create SecurityGroupServerRpcApi and add some docs

Create SecurityGroupServerRpcApi, which is intended to replace
SecurityGroupServerRpcApiMixin over time.  The new class is the same
code, but used as a standalone class.  This is needed to be able to
eventually move this API into a messaging namespace.

In passing, add docstrings that show where to find the corresponding
other side of this interface in the code base.

Part of blueprint rpc-docs-and-namespaces.

Change-Id: If959b2f8bf21b4963bf6876a3eedc0a4b06c6400

doc/source/devref/security_group_api.rst

@@ -34,7 +34,7 @@ running on the compute nodes, and modifying the IPTables rules on each hyperviso
 
 * `Agent RPC classes <https://github.com/openstack/neutron/blob/master/neutron/agent/securitygroups_rpc.py>`_
 
-  * The SecurityGroupServerRpcApiMixin defines the API methods that can be called by agents, back to the plugin that runs on the Neutron controller
+  * The SecurityGroupServerRpcApi defines the API methods that can be called by agents, back to the plugin that runs on the Neutron controller
   * The SecurityGroupAgentRpcCallbackMixin defines methods that a plugin uses to call back to an agent after performing an action called by an agent.
 
 

neutron/agent/securitygroups_rpc.py

@@ -21,6 +21,7 @@ from oslo import messaging
 from oslo.utils import importutils
 
 from neutron.agent import firewall
+from neutron.common import rpc as n_rpc
 from neutron.common import topics
 from neutron.i18n import _LI, _LW
 from neutron.openstack.common import log as logging
@@ -101,6 +102,28 @@ class SecurityGroupServerRpcApiMixin(object):
                           devices=devices)
 
 
+# NOTE(russellb) This class currently serves as a transition point as the code
+# base is migrated away from using the Mixin class.  Once the mixin usage is
+# removed, the body of the mixin will be folded into this class.  This class
+# must become standalone before we can move this API into a messaging
+# namespace.  For more info on why this should be put in a namespace, see
+# http://specs.openstack.org/openstack/neutron-specs/
+#           specs/kilo/rpc-docs-and-namespaces.html
+class SecurityGroupServerRpcApi(SecurityGroupServerRpcApiMixin):
+    """RPC client for security group methods in the plugin.
+
+    This class implements the client side of an rpc interface.  This interface
+    is used by agents to call security group related methods implemented on the
+    plugin side.  The other side of this interface can be found in
+    neutron.api.rpc.handlers.SecurityGroupServerRpcCallback.  For more
+    information about changing rpc interfaces, see
+    doc/source/devref/rpc_api.rst.
+    """
+    def __init__(self, topic):
+        target = messaging.Target(topic=topic, version='1.0')
+        self.client = n_rpc.get_client(target)
+
+
 class SecurityGroupAgentRpcCallbackMixin(object):
     """A mix-in that enable SecurityGroup agent
     support in agent implementations.

neutron/api/rpc/handlers/securitygroups_rpc.py

@@ -22,7 +22,13 @@ from neutron import manager
 
 
 class SecurityGroupServerRpcCallback(object):
-    """Callback for SecurityGroup agent RPC in plugin implementations."""
+    """Callback for SecurityGroup agent RPC in plugin implementations.
+
+    This class implements the server side of an rpc interface.  The client side
+    can be found in neutron.agent.securitygroups_rpc.SecurityGroupServerRpcApi.
+    For more information on changing rpc interfaces, see
+    doc/source/devref/rpc_api.rst.
+    """
 
     # API version history:
     #   1.1 - Initial version