Merge pull request #53 from softlayer/v3.0

V3.0

CHANGELOG.textile

@@ -1,3 +1,12 @@
+*3.0*
+* Substantially rewrote the ObjectFilter class. ObjectFilters used to be hashes which made it easy to manipulate their content incorrectly. The new implementation has a strict interface that makes it harder to manipulate filters incorrectly.
+* Added a model for Virtual Server Image Templates (SoftLayer::ImageTemplate) - VirtualServerOrder now requires an instance of this class rather than allowing you to provide the global_id of an image
+* Added a model for data centers (SoftLayer::Datacenter). Bare Metal, Bare Metal Package, and Virtual server orders now use an instance of Datacenter to identify where their servers will be provisioned. The routines in those classes which used to provide lists of valid data center names now return data center objects.
+* Virtual Server Upgrades are now handled by the VirtualServerUpgradeOrder class and not the VirtualServer class. This change was made for several reasons. Firt and foremost, it allows multiple aspects of a virtual server to be upgraded at once without having to wait on separate transactions to complete between upgrades. Secondly it opens the door for additional upgrades (for example, to disk configuration) to be added in the future.
+* Added a method to reboot servers.
+* The routine to retreive the open tickets on an account has been moved from the Ticket class. The set of open tickets is now a dynamic property of an account object.
+* The Model Layer now includes models for Server (aka. Shared) and VLAN (aka. Dedicated) firewalls in the ServerFirewall, and VLANFireall classes respectively.  There are corresponding classes for ordering firewalls (ServerFirewallOrder and VLANFirewallOrder).  To facilitate the process of locating the 'id' for a firewall, the Account class includes the find_VLAN_with_number routine which lets you look up the segments of a firewall from the VLAN nubmer.
+
 *2.2.2*
 * Fixed a bug in BareMetalServerOrder_Package.rb where the order template did not use an array for the "hardware" key.  This lead to an order template that would be accepted by verifyOrder, but rejected by placeOrder.  An internal issue to review verifyOrder has also been generated. (reported by Rohit Singh)
 
@@ -7,7 +16,7 @@
 
 *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.
+* Formalized the RDoc documentation process. Added overview and welcome documentation and changed the README so it directs folks to the new documentation.
 
 *2.1.0*
 * Began implementing a model framework that allows Ruby developers to work with elements in the SoftLayer API in a more object-oriented fashion. The first release of this framework includes the Ticket, VirtualServer, and BareMetalServer classes.

README.md

@@ -26,6 +26,10 @@ This software is written by the SoftLayer Development Team [sldn@softlayer.com](
 
 Please join us in the [SoftLayer Developer Network forums](http://forums.softlayer.com/forum/softlayer-developer-network)
 
+# Contributer License Agreement
+
+Contributions to the softlayer-ruby project require the submission of a contributer license agreement. Please generate the documentation and carefully refer to the Contribution Guide to participate.
+
 # Copyright and License
 
 The `softlayer_api` Ruby Gem and it's source files are Copyright © 2010-2014 [SoftLayer Technologies, Inc](http://www.softlayer.com/).  The software is provided under an MIT license. Details of that license can be found in the embedded LICENSE.md file.

doc_src/Contribution Guide.md

@@ -15,7 +15,7 @@ Any requests for enhancements, new features, or bug reports should be entered in
 
 # Development Environment
 
-As a Ruby project, your first step will be to install the [Ruby Programming Language](https://www.ruby-lang.org/en/). Many Unix-derived environments, including Mac OS X, have a version or Ruby installed by default, however, the default version may be out-of-date. Please visit the main Ruby language [site](https://www.ruby-lang.org/en/) for instructions on installing an up-to-date build of Ruby for your computing environment. 
+As a Ruby project, your first step will be to install the [Ruby Programming Language](https://www.ruby-lang.org/en/). Many Unix-derived environments, including Mac OS X, have a version or Ruby installed by default, however, the default version may be out-of-date. Please visit the main Ruby language [site](https://www.ruby-lang.org/en/) for instructions on installing an up-to-date build of Ruby for your computing environment.
 
 The Gem supports multiple versions of Ruby, and we recommend using Ruby 2.0 or later. The [Ruby Version Manager (rvm)](https://rvm.io) is an invaluable tool to help keep track of multiple versions of Ruby. The Gem no longer supports Ruby 1.8.7.  Support for Ruby 1.9 will continue for a time, but the Core Ruby team is already withdrawing their support for that version.
 
@@ -100,7 +100,7 @@ The basic directory structure for the source tree is as follows
 	  softlayer   # Folder containing most of the gem's actual source code
 	log			  # RVM will create a log folder when running commands across multiple ruby versions.
 	pkg			  # Created when the gem is built, contains built versions of the gem
-	spec		  # Source directory for the RSpec testing specifications 
+	spec		  # Source directory for the RSpec testing specifications
 	  fixtures    # Files used by the unit tests to mock responses from the SoftLayer network API
 
 Most of the source files that implement the gem are found in `lib/softlayer`.  If you wish to add new functionality, or edit existing functionality, you will probably edit the class files in this directory. Unit tests using Rspec are found in the spec folder and should generally follow the naming convention of <Class>_spec.rb

doc_src/Foundation.md

@@ -21,7 +21,7 @@ SoftLayer provides two different endpoint URLs to scripts. One is associated wit
 
     # The base URL of the SoftLayer API available to the public internet.
     API_PUBLIC_ENDPOINT = 'https://api.softlayer.com/xmlrpc/v3/'
-    
+
     # The base URL of the SoftLayer API available through SoftLayer's private network
     API_PRIVATE_ENDPOINT = 'https://api.service.softlayer.com/xmlrpc/v3/'
 
@@ -65,7 +65,7 @@ The open_tickets variable should receive an array of hashes representing the ope
 
     softlayer_client = SoftLayer::Client.new( :username => "joecustomer", api_key => "feeddeadbeefbadf00d...)
     open_tickets = softlayer_client["Account"].getOpenTickets
-    
+
     open_tickets.each { |ticket_hash| puts ticket_hash["title"] }
 
 This short example shows the essence of working with the Foundation API, you create a client, obtain a service, and make calls to the network SoftLayer API through that service.
@@ -82,7 +82,7 @@ Calls to the network SoftLayer API that result in errors being returned by the s
 
 ## Troubleshooting
 
-Communication with the SoftLayer servers is handled through the XML-RPC client that is built into the Ruby Core library. As a consequence the network communication is also handled by Core library classes. 
+Communication with the SoftLayer servers is handled through the XML-RPC client that is built into the Ruby Core library. As a consequence the network communication is also handled by Core library classes.
 
 One aspect of network communication that the `softlayer_api` relies on the Ruby Core library to provide is SSL certificate authentication. Problems with this authentication often arise if your Ruby environment is not properly configured with SSL root certificates. If you find you are having trouble communicating with the network SoftLayer API, and the error messages point to SSL certificate authentication, please consider a web search using your specific error message as a search string. This will often reveal answers that can help you resolve networking issues your Ruby environment.
 

doc_src/Model Layer.md

@@ -10,7 +10,7 @@ The details of the individual classes that for the object class hierarchy of the
 
 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 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.
 
@@ -24,7 +24,7 @@ The initializer for classes in the ModelBase hierarchy are declared:
       …
     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 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.
 
@@ -43,7 +43,7 @@ The ModelBase class defines the subscript operator (`[]`) to accept a property n
     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. 
+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.
 

doc_src/Welcome.md

@@ -18,6 +18,6 @@ The Foundation layer, makes use of the [XMLRPC client](http://www.ruby-doc.org/s
 
 The Model layer is built atop the foundation as object class hierarchy. The class hierarchy models the  structures found in the SoftLayer environment using the object-oriented features of Ruby. It does this to abstract out some of the implementation detail that a developer would commonly have to work with to communicate with SoftLayer through the foundation layer.
 
-The Model layer is by no means complete; quite to the contrary it is in its infancy and we believe that much of the development effort in the Gem will focus on incorporating new models into this layer. Because it is incomplete, however, we have put some effort into bridges from the functionality of the model, down to the lower level foundation, without trouble. Also, as a result of this, developers interested in using the Model layer should also should familiarize themselves with the Foundation. 
+The Model layer is by no means complete; quite to the contrary it is in its infancy and we believe that much of the development effort in the Gem will focus on incorporating new models into this layer. Because it is incomplete, however, we have put some effort into bridges from the functionality of the model, down to the lower level foundation, without trouble. Also, as a result of this, developers interested in using the Model layer should also should familiarize themselves with the Foundation.
 
 All developers should continue their exploration of the `softlayer_api` gem by examining the Foundation documentation. Clients that wish to make use of the abstractions provided in the object hierarchy may continue their exploration by looking at the Model Layer documentation. Developers who wish to expand the models found in the `softlayer_api` Gem should read the [Contribution Guide](ContributionGuide_md.html)

examples/account_servers.rb

@@ -23,8 +23,8 @@
 require 'rubygems'
 require 'softlayer_api'
 require 'pp'
-  
-  # We can set the default client to be our client and that way 
+
+  # We can set the default client to be our client and that way
   # we can avoid supplying it later
   SoftLayer::Client.default_client = SoftLayer::Client.new(
     # :username => "joecustomer"              # enter your username here

examples/create_ticket.rb

@@ -35,15 +35,15 @@
   account = SoftLayer::Account.account_for_client(softlayer_client)
   account_user = account.service.getCurrentUser
   my_user_id = account_user["id"]
-  
+
   # We also need a subject for the ticket. Subjects are specified by id
   # This code prints out a table of all the ticket subjects with their
   # ids:
   ticket_subjects = SoftLayer::Ticket.ticket_subjects(softlayer_client)
   ticket_subjects.each do |subject|
     puts "#{subject['id']}\t#{subject['name']}"
   end
-  
+
   # For this example we'll use 'Public Network Question' as the subject.  That's id 1022
   public_network_question_id = 1022
 
@@ -58,7 +58,7 @@
   )
 
   puts "Created a new ticket : #{new_ticket.id} - #{new_ticket.title}"
-  
+
   # we can also add an update to the ticket:
   new_ticket.update("This is a ticket update sent from the Ruby library")
 

examples/open_tickets.rb

@@ -30,14 +30,14 @@
 # $SL_API_KEY = "feeddeadbeefbadf00d..."   # enter your api key here
 
 # The client constructed here must get it's credentials from somewhere
-# In this script you might uncomment the globals above and assign your 
+# In this script you might uncomment the globals above and assign your
 # credentials there
 SoftLayer::Client.default_client = SoftLayer::Client.new()
 
 # The openTickets routine will pick up the default client established above.
 open_tickets = SoftLayer::Ticket.open_tickets()
 
-open_tickets.sort!{ |lhs, rhs| -(lhs.lastEditDate <=> rhs.lastEditDate) } 
+open_tickets.sort!{ |lhs, rhs| -(lhs.lastEditDate <=> rhs.lastEditDate) }
 open_tickets.each do |ticket|
   printf "#{ticket.id} - #{ticket.title}"
 

examples/order_bare_metal_package.rb

@@ -129,11 +129,11 @@ def tl_dr_version
   # We have a configuration for the server, we also need a location for the new server.
   # The package can give us a list of locations. Let's print out that list
   puts "\nData Centers for '#{quad_intel_package.name}':"
-  quad_intel_package.datacenter_options.each { |location| puts "\t#{location}"}
+  quad_intel_package.datacenter_options.each { |datacenter| puts "\t#{datacenter.name}"}
 
   # With all the config options in place we can now construct the product order.
   server_order = SoftLayer::BareMetalServerOrder_Package.new(quad_intel_package, client)
-  server_order.datacenter = 'sng01'
+  server_order.datacenter = SoftLayer::Datacenter.datacenter_named 'sng01', client
   server_order.hostname = 'sample'
   server_order.domain = 'softlayerapi.org'
   server_order.configuration_options = config_options

examples/order_server_firewall.rb

@@ -0,0 +1,63 @@
+#
+# Copyright (c) 2014 SoftLayer Technologies, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+require 'rubygems'
+require 'softlayer_api'
+require 'pp'
+
+# This is the id of the server you want to protect with a firewall.
+# The server can be Bare Metal or Virtual.  It should have a public
+# network interface, and it should not already have a firewall on it.
+server_id = 257696 # 12345
+
+# In this example, we assume this is a Bare Metal Server
+is_virtual_server = false
+
+# Work with the SoftLayer API begins with a client.  By setting
+# the "default" client we avoid having to specify the client repeatedly
+# in calls that follow.
+SoftLayer::Client.default_client = SoftLayer::Client.new(
+  # :username => "joecustomer"              # enter your username here
+  # :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+)
+
+# in this case we go straight to the appropriate class to find the server
+# an alternative might be to create the account for this client and
+# search the list of servers for the one with the appropriate ID.
+if is_virtual_server
+  server = SoftLayer::VirtualServer.server_with_id(server_id)
+else
+  server = SoftLayer::BareMetalServer.server_with_id(server_id)
+end
+
+# Create an instance of SoftLayer::ServerFirewallOrder
+order = SoftLayer::ServerFirewallOrder.new(server)
+
+begin
+  # this example calls order.verify which will build the order, submit it 
+  # to the network API, and will throw an exception if the order is
+  # invalid.
+  order.verify()
+  puts "Firewall order is good for #{server.fullyQualifiedDomainName}"
+rescue => exception
+  puts "Firewall order failed for #{server.fullyQualifiedDomainName} because #{exception}"
+end

examples/ticket_info.rb

@@ -34,13 +34,13 @@
   # at information.  In this case we are talking directly to the ticket
   # service
   ticket_service = softlayer_client.service_named("Ticket");
-  
+
   # Retrive a particular ticket by ID (you will have to substitute an existing ticket's ID here)
   ticket_ref = ticket_service.object_with_id(12345)
 
   # Retrive very specific information about the ticket
   ticket = ticket_ref.object_mask("mask[updates[entry,createDate],assignedUserId,attachedHardware.datacenter]").getObject
-  
+
   pp ticket
 rescue Exception => exception
   puts "Unable to retrieve the ticket #{exception}"