Jump to: navigation, search

Difference between revisions of "PythonOpenStackSDK/ClassDesignDiscussion"

Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
  
In order to help make this SDK easy to develop, maintain, and test, a clean class design with clearly separated responsibilities is important. This is just one possibility, based on work done on the python-novaclient library.
+
In order to help make this SDK easy to develop, maintain, and test, a clean class design with clearly separated responsibilities is important. This is just one possibility, based on work done on the python-novaclient library. In an attempt to simplify things, the Identity class has been left out, as it is an entire discussion in and of itself. For the purposes of this discussion, assume that Identity is present and can do everything that is needed.
  
 
Here is a general overview of the proposed class relationships:
 
Here is a general overview of the proposed class relationships:
Line 7: Line 7:
 
[[File:Python sdk class design.png|none|center|Class Design Overview]]
 
[[File:Python sdk class design.png|none|center|Class Design Overview]]
  
''NOTE: For this discussion, I have used the term 'Client' to refer to the class that acts as the interface between the application code and the SDK. This is not a universally-loved term, and changing it to something else will not affect the design itself.''
+
''NOTE: For this discussion, the term 'Client' has been used to refer to the class that acts as the interface between the application code and the SDK. This is not a universally-loved term, and changing it to something else will not affect the design itself. Similarly, the class that handles all the HTTP traffic has been named 'HTTP', but that is also not critical.''
 +
 
 +
== Overview ==
 +
 
 +
There is a single '''Client''' class that contains the interface that the application developer will work with. Any functionality in the SDK should be available as a method in the Client class. Each Client instance has a reference to an instance of its Manager class. There is no logic in the Client class except to pass the request to its manager, and return the result from the manager to the application.
 +
 
 +
The '''Manager''' class contains the logic to construct the appropriate URIs from the base endpoints (returned from the service catalog), and the particulars of the request. If needed, it also creates the appropriate data to include with the request. It then passes that request to the HTTP class, and handles the response. If there is an exception, the appropriate class of Exception is determined and raised with the information the developer would need to understand and correct the exception. Otherwise, the Manager returns the appropriate response, which can be '''None''', or it can be one or more Resource objects.
 +
 
 +
The '''Resource''' class represents a resource in the cloud, such as a compute instance, a stored object, a network, etc. Rather than have fixed attributes, its attributes should be populated with the information returned from the API. Every resource should have an '''id''' attribute; in the cases where there is not a native id, such as a stored object in Swift, an 'id' property should be created to return the unique identifier for the resource, such as a name.
 +
 
 +
The '''HTTP''' class handled all communication between the local system and the API server. This functionality is separated out in order to make testing simpler, so that it can be replaced with a local API ''server'' that acts as a test double.

Revision as of 17:55, 27 March 2014

Introduction

In order to help make this SDK easy to develop, maintain, and test, a clean class design with clearly separated responsibilities is important. This is just one possibility, based on work done on the python-novaclient library. In an attempt to simplify things, the Identity class has been left out, as it is an entire discussion in and of itself. For the purposes of this discussion, assume that Identity is present and can do everything that is needed.

Here is a general overview of the proposed class relationships:

Class Design Overview

NOTE: For this discussion, the term 'Client' has been used to refer to the class that acts as the interface between the application code and the SDK. This is not a universally-loved term, and changing it to something else will not affect the design itself. Similarly, the class that handles all the HTTP traffic has been named 'HTTP', but that is also not critical.

Overview

There is a single Client class that contains the interface that the application developer will work with. Any functionality in the SDK should be available as a method in the Client class. Each Client instance has a reference to an instance of its Manager class. There is no logic in the Client class except to pass the request to its manager, and return the result from the manager to the application.

The Manager class contains the logic to construct the appropriate URIs from the base endpoints (returned from the service catalog), and the particulars of the request. If needed, it also creates the appropriate data to include with the request. It then passes that request to the HTTP class, and handles the response. If there is an exception, the appropriate class of Exception is determined and raised with the information the developer would need to understand and correct the exception. Otherwise, the Manager returns the appropriate response, which can be None, or it can be one or more Resource objects.

The Resource class represents a resource in the cloud, such as a compute instance, a stored object, a network, etc. Rather than have fixed attributes, its attributes should be populated with the information returned from the API. Every resource should have an id attribute; in the cases where there is not a native id, such as a stored object in Swift, an 'id' property should be created to return the unique identifier for the resource, such as a name.

The HTTP class handled all communication between the local system and the API server. This functionality is separated out in order to make testing simpler, so that it can be replaced with a local API server that acts as a test double.