Added the first bit of Model Layer documentation and renamed the Contribution Guide placeholder.

Author: SLsthompson

CHANGELOG.textile

@@ -1,3 +1,6 @@
+*2.2*
+* Added a method to reboot servers.
+
 *2.1.1*
 * Virtual server upgrades no longer raise exceptions
 * Formalized the RDoc documentation process.  Added overview and welcome documentation and changed the README so it directs folks to the new documentation.

doc_src/ContributionGuide.md doc_src/Contribution Guide.mddoc_src/ContributionGuide.md renamed to doc_src/Contribution Guide.md

@@ -0,0 +1,64 @@
+# `softlayer_api` Model Layer
+
+The Model Layer builds upon the Foundation layer and offers abstractions of the entities in the SoftLayer enviornment. For example, computing assets in the SoftLayer environment are found in two separate services [SoftLayer_Hardware](http://sldn.softlayer.com/reference/services/SoftLayer_Hardware) and [SoftLayer_Virtual_Guest](http://sldn.softlayer.com/reference/services/SoftLayer_Virtual_Guest). The Model Layer, however, creates a Server abstraction on top of those services. By doing so, a Ruby script can work with an instance of the SoftLayer::Server object class, send that object the "cancel!" message, and trust the underlying object framework to route the message to the appropriate service and routine within the network API.
+
+The Model Layer is not meant to be complete. In fact, it models just a few key elements of the SoftLayer environment at this point, however we hope the Model Layer will grow and encompass more of the entities found in the API over time. In the interim, however, the current framework includes some convenient bridges that allow Ruby scripts to move from working with the abstractions of the Model Layer to the lower-level routines of the Foundation API easily.
+
+The details of the individual classes that for the object class hierarchy of the Model layer are included in the API documentaiton. This document will discuss some of the general features of the Model Layer and the bridges that are in place to help code move between the Foundation and Model Layers.
+
+# The ModelBase Class
+
+The ModelBase is the abstract base class of object class hierarchy that forms the Model Layer of the `softlayer_api` Gem. An instance of ModelBase represents a single entity within the SoftLayer API.
+
+In the Foundation layer, SoftLayer entities are represented as a Ruby hash whose keys and values are the are property names and property values of the entity. In the Model Layer, SoftLayer entities are represented by instances of the concrete subclasses of the Model Base class. 
+
+In implementation terms, an instance of the ModelBase class (or more accurately and instance of a concrete subclass of the ModelBase class) encapsulates the hashes of the Foundation layer defines the attributes and operations that form a convenient model for working with the underlying entity.
+
+Here we will discuss the general features that all concrete subclasses of ModelBase share.
+
+## Initializing Instances
+
+The initializer for classes in the ModelBase hierarchy are declared:
+
+    def initialize(softlayer_client, network_hash)
+      …
+    end
+
+The first argument is the client that the object may use to make requests to the network API. The second is the `network_hash`, the hash representation of the entity as returned by the network API. 
+
+The hash used to initialize an instance of ModelBase *must* contain a key, `id`, whose value is the `id` of the SoftLayer entity that the object model instance will represent. Correspondingly, the ModelBase class defines the `id` as having the same value as the `id` property in the network hash.
+
+## Updating Instances from the Network
+
+If you wish to ask an instance of ModelBase to update itself with the latest information from the SoftLayer network API, you may call the `refresh_details` method defined in the ModelBase class. This method is likely to make one or more calls through to the network API and will, consequently, incur the overhead of network communication. (Note: subclasses should not override `refresh_details` but should, instead, override the `softlayer_properties` method. Correspondingly, the softlayer_properties method is an implementation detail of ModelBase and is not intended to be called by outside code.)
+
+## Bridging to the Foundation layer
+
+Because the Model Layer offers limited coverage of the vast expanse of functionality found in the network API, it is often necessary to move from an object instance in the Model Layer to the implementation details from the Foundation layer. The Model Base class includes several features to help bridge the between layers gap.
+
+### Accessing Properties
+
+The ModelBase class defines the subscript operator (`[]`) to accept a property name as a string and return that property of the underlying hash. For example, given a ticket, represented by an instance of the SoftLayer::Ticket model layer class, there is no Model Layer representation corresponding to the `serviceProvider` property of the SoftLayer ticket entity. However, the subscript operator can be used to access that property from a model layer object:
+
+    ticket = SoftLayer::Ticket.ticket_with_id(123456)
+	service_provider = ticket['serviceProvider']
+
+In this case we ask the ticket for the value of the `serviceProvider` property. Note that the argument to the subscript operator is a string containing the property name. 
+
+This technique can only return values stored in the `softlayer_hash` encapsulated in the ModelBase class. Many classes in the Model Layer limit the information retrieved from the network (using object masks) to a subset of the full set of properties available through the network API. Scripts can check whether or not a given property is included in the underlying hash by calling the `has_sl_property?` method of ModelBase.
+
+### Calling Network API routines
+
+Where possible, each subclass of ModelBase should provide a `service` attribute. The value of that attribute should be an instance of SoftLayer::Service, with Service Helpers applied, suitable for addressing the SoftLayer entity represented by the object through the network API.  For example, consider an instance of the Model Layer class SoftLayer::Ticket which represents a service ticket within the network API. The Ticket class defines the `service` attribute of that instance to be the value:
+
+    self.softlayer_client['Ticket'].object_with_id(self.id)
+
+because this service object includes `object_with_id` service helper the result can be used to call through to the network API and that call will be directed at the SoftLayer_Ticket entity with the same id as the model object.  For example:
+
+    ticket_object.service.getAttachedFile(file_id)
+
+calls the `getAttachedFile` method of the SoftLayer_Ticket service which is not yet available in the SoftLayer::Ticket object model class.
+
+## The rest of the model
+
+The ModelBase class is literally the tip of the iceberg for the Model Layer, the bulk of functionality found in this layer is defined by concrete classes like SoftLayer::Ticket and SoftLayer::BareMetalServer, and in other abstract base classes like SoftLayer::Server.  To understand the model presented by each class, we invite you to explore the API documentation.

doc_src/Model Layer.md

@@ -82,17 +82,6 @@ def refresh_details(object_mask = nil)
       @softlayer_hash = self.softlayer_properties(object_mask)
     end
 
-    ##
-    # Subclasses should implement this method as part of enabling the
-    # refresh_details fuctionality The implementation should make a request
-    # to the SoftLayer API and retrieve an up-to-date SoftLayer hash
-    # representation of this object. That hash should be the return value
-    # of this routine.
-    #
-    def softlayer_properties(object_mask = nil)
-      raise "Abstract method softlayer_properties in ModelBase was called"
-    end
-
     ##
     # Returns the value of of the given property as stored in the
     # softlayer_hash. This gives you access to the low-level, raw
@@ -132,6 +121,17 @@ def to_ary()
 
     protected
 
+    ##
+    # Subclasses should implement this method as part of enabling the
+    # refresh_details fuctionality The implementation should make a request
+    # to the SoftLayer API and retrieve an up-to-date SoftLayer hash
+    # representation of this object. That hash should be the return value
+    # of this routine.
+    #
+    def softlayer_properties(object_mask = nil)
+      raise "Abstract method softlayer_properties in ModelBase was called"
+    end
+    
     ##
     # The softlayer_hash stores the low-level information about an
     # object as it was retrieved from the SoftLayer API.

lib/softlayer/ModelBase.rb

@@ -84,7 +84,7 @@
 end
 
 describe Hash, "#to_sl_object_mask" do
-  it "rejects the empty empty hash" do
+  it "rejects the empty hash" do
       expect { {}.to_sl_object_mask }.to raise_error(RuntimeError)
   end