ibm_power_hmc 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 397feab84db9812185ab1125cd6778b52a1848519d6bae5950d69cb31e9b4845
-  data.tar.gz: 27dd4d94cd61a19c66d0d6e438c17987ea5926af78b7677b5044a11a50acdb18
+  metadata.gz: e42aa4d6eaa8915b8c37ce96aab995801533b81d8fa70b1e351bc550cc6eaa02
+  data.tar.gz: 6022fb088c67eeb0c20e8435c20567ef62fb34e365419cfa20f6fb9bc1e769f5
 SHA512:
-  metadata.gz: 1171816de48bed97b1837ab39d3bd639772928ebee98fb8f287c85006196bdf068320599b921a239d10d5ce74e98629cde754eca14b12c6cf6be85477e7a7fb3
-  data.tar.gz: 10f7397e58acab288715283de98480caf915fb628021b2f8c5261b13b2c7b273cdec5e1d7a52b35560acbe5cae6dfed5c9e68516673d97ff5f91a9fb44daa370
+  metadata.gz: 7ca0280aaeff1a1a0ce0cf5c53c40b6f0ddfc94725536e53d19031b1b107de4c8b44919580eaf1716e60f302bf339363508597b9188634412511bcc7869e4f83
+  data.tar.gz: b0251d621a729e2b7d97c7655709fd68bd1e796466967f2021924ab7658a12c2dc13c34dfe71597f96f6ed2114e24c405362232c4dab2e88b653afbe2b7d679a

data/.gitignore

@@ -1,3 +1,4 @@
+/Gemfile.lock
 /.bundle/
 /.yardoc
 /_yardoc/

data/.rubocop.yml

@@ -0,0 +1,4 @@
+inherit_gem:
+  manageiq-style: ".rubocop_base.yml"
+inherit_from:
+- ".rubocop_local.yml"

data/.rubocop_local.yml

@@ -0,0 +1,7 @@
+AllCops:
+  Exclude:
+  - '*.gemspec'
+Layout/HashAlignment:
+  Enabled: false
+Style/ConditionalAssignment:
+  Enabled: false

data/README.md

@@ -42,6 +42,12 @@ puts hmc.name
 puts hmc.version
 ```
 
+Retrieving managed systems that are powered on:
+
+```ruby
+hc.managed_systems("State" => "operating")
+```
+
 Listing the logical partitions and virtual I/O servers of each managed system:
 
 ```ruby

data/lib/ibm_power_hmc/connection.rb

@@ -2,10 +2,21 @@
 
 # Module for IBM HMC Rest API Client
 module IbmPowerHmc
-  # HMC REST Client connection
+  class Error < StandardError; end
+
+  ##
+  # HMC REST Client connection.
   class Connection
+    ##
+    # @!method initialize(host:, username: "hscroot", password:, port: 12_443, validate_ssl: true)
+    # Create a new HMC connection.
+    #
+    # @param host [String] Hostname of the HMC.
+    # @param username [String] User name.
+    # @param password [String] Password.
+    # @param port [Integer] TCP port number.
+    # @param validate_ssl [Boolean] Verify SSL certificates.
     def initialize(host:, username: "hscroot", password:, port: 12_443, validate_ssl: true)
-      # Damien: use URI::HTTPS
       @hostname = "#{host}:#{port}"
       @username = username
       @password = password
@@ -13,72 +24,107 @@ module IbmPowerHmc
       @api_session_token = nil
     end
 
+    ##
+    # @!method logon
+    # Establish a trusted session with the Web Services APIs.
+    # @return [String] The X-API-Session token.
     def logon
       method_url = "/rest/api/web/Logon"
       headers = {
-        content_type: "application/vnd.ibm.powervm.web+xml; type=LogonRequest"
+        :content_type => "application/vnd.ibm.powervm.web+xml; type=LogonRequest"
       }
       doc = REXML::Document.new("")
-      doc.add_element("LogonRequest", {
-                        "xmlns" => "http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/",
-                        "schemaVersion" => "V1_1_0"
-                      })
+      doc.add_element("LogonRequest", "schemaVersion" => "V1_1_0")
+      doc.root.add_namespace("http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/")
       doc.root.add_element("UserID").text = @username
       doc.root.add_element("Password").text = @password
 
-      # Damien: begin/rescue
       @api_session_token = ""
       response = request(:put, method_url, headers, doc.to_s)
       doc = REXML::Document.new(response.body)
-      @api_session_token = doc.root.elements["X-API-Session"].text
+      elem = doc.elements["LogonResponse/X-API-Session"]
+      raise Error, "LogonResponse/X-API-Session not found" if elem.nil?
+
+      @api_session_token = elem.text
     end
 
+    ##
+    # @!method logoff
+    # Close the session.
     def logoff
+      # Don't want to trigger automatic logon here!
+      return if @api_session_token.nil?
+
       method_url = "/rest/api/web/Logon"
-      request(:delete, method_url)
+      begin
+        request(:delete, method_url)
+      rescue
+        # Ignore exceptions as this is best effort attempt to log off.
+      end
       @api_session_token = nil
     end
 
+    ##
+    # @!method management_console
+    # Retrieve information about the management console.
+    # @return [IbmPowerHmc::ManagementConsole] The management console.
     def management_console
       method_url = "/rest/api/uom/ManagementConsole"
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      entry = doc.root.elements["entry"]
-      ManagementConsole.new(entry)
+      # This request returns a feed with a single entry.
+      FeedParser.new(response.body).objects(:ManagementConsole).first
     end
 
-    def managed_systems
+    ##
+    # @!method managed_systems(search = {})
+    # Retrieve the list of systems managed by the HMC.
+    # @param search [Hash] The optional property name and value to match.
+    # @return [Array<IbmPowerHmc::ManagedSystem>] The list of managed systems.
+    def managed_systems(search = {})
       method_url = "/rest/api/uom/ManagedSystem"
+      search.each { |key, value| method_url += "/search/(#{key}==#{value})" }
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      systems = []
-      return systems if doc.root.nil?
+      FeedParser.new(response.body).objects(:ManagedSystem)
+    end
 
-      doc.root.each_element("entry") do |entry|
-        system = ManagedSystem.new(entry)
-        systems += [system]
-      end
-      systems
+    ##
+    # @!method managed_system(lpar_uuid, sys_uuid = nil, group_name = nil)
+    # Retrieve information about a managed system.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param group_name [String] The extended group attributes.
+    # @return [IbmPowerHmc::ManagedSystem] The managed system.
+    def managed_system(sys_uuid, group_name = nil)
+      method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}"
+      method_url += "?group=#{group_name}" unless group_name.nil?
+
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:ManagedSystem)
     end
 
-    def lpars(sys_uuid = nil)
+    ##
+    # @!method lpars(sys_uuid = nil, search = {})
+    # Retrieve the list of logical partitions managed by the HMC.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param search [Hash] The optional property name and value to match.
+    # @return [Array<IbmPowerHmc::LogicalPartition>] The list of logical partitions.
+    def lpars(sys_uuid = nil, search = {})
       if sys_uuid.nil?
         method_url = "/rest/api/uom/LogicalPartition"
+        search.each { |key, value| method_url += "/search/(#{key}==#{value})" }
       else
         method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/LogicalPartition"
       end
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      lpars = []
-      return lpars if doc.root.nil?
-
-      doc.root.each_element("entry") do |entry|
-        lpar = LogicalPartition.new(entry)
-        lpars += [lpar]
-      end
-      lpars
+      FeedParser.new(response.body).objects(:LogicalPartition)
     end
 
+    ##
+    # @!method lpar(lpar_uuid, sys_uuid = nil, group_name = nil)
+    # Retrieve information about a logical partition.
+    # @param lpar_uuid [String] The UUID of the logical partition.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param group_name [String] The extended group attributes.
+    # @return [IbmPowerHmc::LogicalPartition] The logical partition.
     def lpar(lpar_uuid, sys_uuid = nil, group_name = nil)
       if sys_uuid.nil?
         method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}"
@@ -88,11 +134,15 @@ module IbmPowerHmc
       method_url += "?group=#{group_name}" unless group_name.nil?
 
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      entry = doc.elements["entry"]
-      LogicalPartition.new(entry)
+      Parser.new(response.body).object(:LogicalPartition)
     end
 
+    ##
+    # @!method lpar_quick_property(lpar_uuid, property_name)
+    # Retrieve a quick property of a logical partition.
+    # @param lpar_uuid [String] The UUID of the logical partition.
+    # @param property_name [String] The quick property name.
+    # @return [String] The quick property value.
     def lpar_quick_property(lpar_uuid, property_name)
       method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}/quick/#{property_name}"
 
@@ -100,141 +150,292 @@ module IbmPowerHmc
       response.body[1..-2]
     end
 
-    def vioses(sys_uuid = nil)
+    ##
+    # @!method rename_lpar(lpar_uuid, newname)
+    # Rename a logical partition.
+    # @param lpar_uuid [String] The UUID of the logical partition.
+    # @param newname [String] The new name of the logical partition.
+    def rename_lpar(lpar_uuid, newname)
+      method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}"
+      headers = {
+        :content_type => "application/vnd.ibm.powervm.uom+xml; type=LogicalPartition",
+      }
+      modify_object(method_url, headers) do |lpar|
+        lpar.xml.elements["PartitionName"].text = newname
+      end
+    end
+
+    ##
+    # @!method vioses(sys_uuid = nil, search = {})
+    # Retrieve the list of virtual I/O servers managed by the HMC.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param search [Hash] The optional property name and value to match.
+    # @return [Array<IbmPowerHmc::VirtualIOServer>] The list of virtual I/O servers.
+    def vioses(sys_uuid = nil, search = {})
       if sys_uuid.nil?
         method_url = "/rest/api/uom/VirtualIOServer"
+        search.each { |key, value| method_url += "/search/(#{key}==#{value})" }
       else
         method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/VirtualIOServer"
       end
-      begin
-        response = request(:get, method_url)
-      rescue StandardError
-        return []
-      end
-      doc = REXML::Document.new(response.body)
-      vioses = []
-      return vioses if doc.root.nil?
-
-      doc.root.each_element("entry") do |entry|
-        vios = VirtualIOServer.new(entry)
-        vioses += [vios]
-      end
-      vioses
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:VirtualIOServer)
     end
 
-    # Damien: share the same method for VIOS and LPAR?
-    def lpar_profiles(lpar_uuid)
-      method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}/LogicalPartitionProfile"
-      begin
-        response = request(:get, method_url)
-      rescue StandardError
-        return []
+    ##
+    # @!method vios(vios_uuid, sys_uuid = nil, group_name = nil)
+    # Retrieve information about a virtual I/O server.
+    # @param vios_uuid [String] The UUID of the virtual I/O server.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param group_name [String] The extended group attributes.
+    # @return [IbmPowerHmc::VirtualIOServer] The virtual I/O server.
+    def vios(vios_uuid, sys_uuid = nil, group_name = nil)
+      if sys_uuid.nil?
+        method_url = "/rest/api/uom/VirtualIOServer/#{vios_uuid}"
+      else
+        method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/VirtualIOServer/#{vios_uuid}"
       end
-      doc = REXML::Document.new(response.body)
-      profiles = []
-      return profiles if doc.root.nil?
+      method_url += "?group=#{group_name}" unless group_name.nil?
 
-      doc.root.each_element("entry") do |entry|
-        profile = LogicalPartitionProfile.new(lpar_uuid, entry)
-        profiles += [profile]
-      end
-      profiles
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:VirtualIOServer)
     end
 
-    def poweron_lpar(lpar_uuid, params = {})
+    ##
+    # @!method poweron_lpar(lpar_uuid, params = {}, sync = true)
+    # Power on a logical partition.
+    # @param lpar_uuid [String] The UUID of the logical partition.
+    # @param params [Hash] Job parameters.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def poweron_lpar(lpar_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}/do/PowerOn"
 
       job = HmcJob.new(self, method_url, "PowerOn", "LogicalPartition", params)
-      job.start
-      job.wait
-      job.delete
+      job.run if sync
+      job
     end
 
-    def poweroff_lpar(lpar_uuid, params = {})
+    ##
+    # @!method poweroff_lpar(lpar_uuid, params = {}, sync = true)
+    # Power off a logical partition.
+    # @param lpar_uuid [String] The UUID of the logical partition.
+    # @param params [Hash] Job parameters.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def poweroff_lpar(lpar_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}/do/PowerOff"
 
       job = HmcJob.new(self, method_url, "PowerOff", "LogicalPartition", params)
-      job.start
-      job.wait
-      job.delete
+      job.run if sync
+      job
     end
 
-    # Damien: share with poweron_lpar?
-    def poweron_vios(vios_uuid, params = {})
+    ##
+    # @!method poweron_vios(vios_uuid, params = {}, sync = true)
+    # Power on a virtual I/O server.
+    # @param vios_uuid [String] The UUID of the virtual I/O server.
+    # @param params [Hash] Job parameters.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def poweron_vios(vios_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/VirtualIOServer/#{vios_uuid}/do/PowerOn"
 
       job = HmcJob.new(self, method_url, "PowerOn", "VirtualIOServer", params)
-      job.start
-      job.wait
-      job.delete
+      job.run if sync
+      job
     end
 
-    # Damien: share with poweroff_lpar?
-    def poweroff_vios(vios_uuid, params = {})
+    ##
+    # @!method poweroff_vios(vios_uuid, params = {}, sync = true)
+    # Power off a virtual I/O server.
+    # @param vios_uuid [String] The UUID of the virtual I/O server.
+    # @param params [Hash] Job parameters.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def poweroff_vios(vios_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/VirtualIOServer/#{vios_uuid}/do/PowerOff"
 
       job = HmcJob.new(self, method_url, "PowerOff", "VirtualIOServer", params)
-      job.start
-      job.wait
-      job.delete
+      job.run if sync
+      job
     end
 
-    def poweron_managed_system(sys_uuid, params = {})
+    ##
+    # @!method poweron_managed_system(sys_uuid, params = {}, sync = true)
+    # Power on a managed system.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param params [Hash] Job parameters.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def poweron_managed_system(sys_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/do/PowerOn"
 
       job = HmcJob.new(self, method_url, "PowerOn", "ManagedSystem", params)
-      job.start
-      job.wait
-      job.delete
+      job.run if sync
+      job
     end
 
-    def poweroff_managed_system(sys_uuid, params = {})
+    ##
+    # @!method poweroff_managed_system(sys_uuid, params = {}, sync = true)
+    # Power off a managed system.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param params [Hash] Job parameters.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def poweroff_managed_system(sys_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/do/PowerOff"
 
       job = HmcJob.new(self, method_url, "PowerOff", "ManagedSystem", params)
-      job.start
-      job.wait
-      job.delete
+      job.run if sync
+      job
+    end
+
+    ##
+    # @!method remove_connection(hmc_uuid, sys_uuid, sync = true)
+    # Remove a managed system from the management console.
+    # @param hmc_uuid [String] The UUID of the management console.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def remove_connection(hmc_uuid, sys_uuid, sync = true)
+      method_url = "/rest/api/uom/ManagementConsole/#{hmc_uuid}/ManagedSystem/#{sys_uuid}/do/RemoveConnection"
+
+      job = HmcJob.new(self, method_url, "RemoveConnection", "ManagedSystem")
+      job.run if sync
+      job
     end
 
-    # Blocks until new events occur.
-    def next_events
+    ##
+    # @!method cli_run(hmc_uuid, cmd, sync = true)
+    # Run a CLI command on the HMC as a job.
+    # @param hmc_uuid [String] The UUID of the management console.
+    # @param cmd [String] The command to run.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def cli_run(hmc_uuid, cmd, sync = true)
+      method_url = "/rest/api/uom/ManagementConsole/#{hmc_uuid}/do/CLIRunner"
+
+      params = {
+        "cmd" => cmd,
+        "acknowledgeThisAPIMayGoAwayInTheFuture" => "true",
+      }
+      job = HmcJob.new(self, method_url, "CLIRunner", "ManagementConsole", params)
+      job.run if sync
+      job
+    end
+
+    ##
+    # @!method next_events(wait = true)
+    # Retrieve a list of events that occured since last call.
+    # @param wait [Boolean] If no event is available, block until new events occur.
+    # @return [Array<IbmPowerHmc::Event>] The list of events.
+    def next_events(wait = true)
       method_url = "/rest/api/uom/Event"
 
-      events = []
+      response = nil
       loop do
         response = request(:get, method_url)
-        next if response.code == 204
+        # No need to sleep as the HMC already waits a bit before returning 204
+        break if response.code != 204 || !wait
+      end
+      FeedParser.new(response.body).objects(:Event)
+    end
+
+    ##
+    # @!method schema(type)
+    # Retrieve the XML schema file for a given object type.
+    # @param type [String] The object type (e.g. "LogicalPartition", "inc/Types")
+    # @return [REXML::Document] The XML schema file.
+    def schema(type)
+      method_url = "/rest/api/web/schema/#{type}.xsd"
+      response = request(:get, method_url)
+      REXML::Document.new(response.body)
+    end
 
-        doc = REXML::Document.new(response.body)
-        doc.root.each_element("entry") do |entry|
-          event = Event.new(entry)
-          events += [event]
+    class HttpError < Error
+      attr_reader :status, :uri, :reason, :message, :original_exception
+
+      ##
+      # @!method initialize(err)
+      # Create a new HttpError exception.
+      # @param err [RestClient::Exception] The REST client exception.
+      def initialize(err)
+        super
+        @original_exception = err
+        @status = err.http_code
+        @message = err.message
+
+        # Try to parse body as an HttpErrorResponse
+        unless err.response.nil?
+          resp = Parser.new(err.response.body).object(:HttpErrorResponse)
+          unless resp.nil?
+            @uri = resp.uri
+            @reason = resp.reason
+            @message = resp.message
+          end
         end
-        break
       end
-      events
+
+      def to_s
+        "msg=\"#{@message}\" status=\"#{@status}\" reason=\"#{@reason}\" uri=#{@uri}"
+      end
     end
 
+    ##
+    # @!method request(method, url, headers = {}, payload = nil)
+    # Perform a REST API request.
+    # @param method [String] The HTTP method.
+    # @param url [String] The method URL.
+    # @param headers [Hash] HTTP headers.
+    # @param payload [String] HTTP request payload.
+    # @return [RestClient::Response] The response from the HMC.
     def request(method, url, headers = {}, payload = nil)
       logon if @api_session_token.nil?
+      reauth = false
+      # Check for relative URLs
+      url = "https://#{@hostname}#{url}" if url.start_with?("/")
+      begin
+        headers = headers.merge("X-API-Session" => @api_session_token)
+        RestClient::Request.execute(
+          :method => method,
+          :url => url,
+          :verify_ssl => @verify_ssl,
+          :payload => payload,
+          :headers => headers
+        )
+      rescue RestClient::Exception => e
+        # Do not retry on failed logon attempts
+        if e.http_code == 401 && @api_session_token != "" && !reauth
+          # Try to reauth
+          reauth = true
+          logon
+          retry
+        end
+        raise HttpError.new(e), "REST request failed"
+      end
+    end
 
-      headers = headers.merge({ "X-API-Session" => @api_session_token })
-      # Damien: use URI module and prepare in initialize?
-      response = RestClient::Request.execute(
-        method: method,
-        url: "https://" + @hostname + url,
-        verify_ssl: @verify_ssl,
-        payload: payload,
-        headers: headers
-      )
-      if response.code == 403
-        # Damien: if token expires, reauth?
-        @api_session_token = nil
-        logon
-        # Damien: retry TBD
+    private
+
+    def modify_object(method_url, headers = {}, attempts = 5)
+      while attempts > 0
+        response = request(:get, method_url)
+        obj = Parser.new(response.body).object
+
+        yield obj
+
+        # Use ETag to ensure object has not changed.
+        headers = headers.merge("If-Match" => obj.etag)
+        begin
+          request(:post, method_url, headers, obj.xml.to_s)
+          break
+        rescue HttpError => e
+          attempts -= 1
+          # Will get 412 ("Precondition Failed" if ETag mismatches)
+          raise if e.status != 412 || attempts == 0
+        end
       end
-      response
     end
   end
 end

data/lib/ibm_power_hmc/job.rb

@@ -1,70 +1,116 @@
 # frozen_string_literal: true
 
-# Module for IBM HMC Rest API Client
 module IbmPowerHmc
-  # HMC Job for long running operations
+  ##
+  # HMC Job for long running operations.
   class HmcJob
-    def initialize(hc, method_url, operation, group, params)
-      @hc = hc
+    class JobNotStarted < StandardError; end
+
+    ##
+    # @!method initialize(conn, method_url, operation, group, params = {})
+    # Construct a new HMC Job.
+    #
+    # @param conn [IbmPowerHmc::Connection] The connection to the HMC.
+    # @param method_url [String] The method URL.
+    # @param operation [String] The name of the requested operation.
+    # @param group [String] The name of the group.
+    # @param params [Hash] The job name/value parameters.
+    def initialize(conn, method_url, operation, group, params = {})
+      @conn = conn
       @method_url = method_url
       @operation = operation
       @group = group
       @params = params
     end
 
+    ##
+    # @!method start
+    # Start the job asynchronously.
+    # @return [String] The ID of the job.
     def start
       headers = {
-        content_type: "application/vnd.ibm.powervm.web+xml; type=JobRequest"
+        :content_type => "application/vnd.ibm.powervm.web+xml; type=JobRequest"
       }
       doc = REXML::Document.new("")
-      doc.add_element("JobRequest:JobRequest", {
-                        "xmlns:JobRequest" => "http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/",
-                        "xmlns" => "http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/",
-                        "schemaVersion" => "V1_1_0"
-                      })
-      op = doc.root.add_element("RequestedOperation", { "schemaVersion" => "V1_1_0" })
+      doc.add_element("JobRequest:JobRequest", "schemaVersion" => "V1_1_0")
+      doc.root.add_namespace("http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/")
+      doc.root.add_namespace("JobRequest", "http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/")
+      op = doc.root.add_element("RequestedOperation", "schemaVersion" => "V1_1_0")
       op.add_element("OperationName").text = @operation
       op.add_element("GroupName").text = @group
-      # Damien: ProgressType?
-      jobparams = doc.root.add_element("JobParameters", { "schemaVersion" => "V1_1_0" })
+
+      jobparams = doc.root.add_element("JobParameters", "schemaVersion" => "V1_1_0")
       @params.each do |key, value|
-        jobparam = jobparams.add_element("JobParameter", { "schemaVersion" => "V1_1_0" })
+        jobparam = jobparams.add_element("JobParameter", "schemaVersion" => "V1_1_0")
         jobparam.add_element("ParameterName").text = key
         jobparam.add_element("ParameterValue").text = value
       end
-      response = @hc.request(:put, @method_url, headers, doc.to_s)
-      doc = REXML::Document.new(response.body)
-      info = doc.root.elements["content/JobResponse:JobResponse"]
-      @id = info.elements["JobID"].text
+      response = @conn.request(:put, @method_url, headers, doc.to_s)
+      jobresp = Parser.new(response.body).object(:JobResponse)
+      @id = jobresp.id
     end
 
+    # @return [Hash] The job results returned by the HMC.
+    attr_reader :results
+
+    ##
+    # @!method status
+    # Return the status of the job.
+    # @return [String] The status of the job.
     def status
-      # Damien: check id is defined
+      raise JobNotStarted unless defined?(@id)
+
       method_url = "/rest/api/uom/jobs/#{@id}"
       headers = {
-        content_type: "application/vnd.ibm.powervm.web+xml; type=JobRequest"
+        :content_type => "application/vnd.ibm.powervm.web+xml; type=JobRequest"
       }
-      response = @hc.request(:get, method_url, headers)
-      doc = REXML::Document.new(response.body)
-      info = doc.root.elements["content/JobResponse:JobResponse"]
-      status = info.elements["Status"].text
-      # Damien: also retrieve "ResponseException/Message"
-      status
+      response = @conn.request(:get, method_url, headers)
+      jobresp = Parser.new(response.body).object(:JobResponse)
+      @results = jobresp.results
+      jobresp.status
     end
 
-    def wait(timeout = 120, poll_interval = 30)
-      endtime = Time.now + timeout
-      while Time.now < endtime do
+    ##
+    # @!method wait(timeout = 120, poll_interval = 0)
+    # Wait for the job to complete.
+    # @param timeout [Integer] The maximum time in seconds to wait for the job to complete.
+    # @param poll_interval [Integer] The interval in seconds between status queries (0 means auto).
+    # @return [String] The status of the job.
+    def wait(timeout = 120, poll_interval = 0)
+      endtime = Time.now.utc + timeout
+      auto = poll_interval == 0
+      poll_interval = 1 if auto
+      while Time.now.utc < endtime
         status = self.status
-        break if status != "RUNNING" # Damien: and != "STARTING"?
+        return status if status != "RUNNING" && status != "NOT_STARTED"
+
+        poll_interval *= 2 if auto && poll_interval < 30
         sleep(poll_interval)
       end
+      "TIMEDOUT"
+    end
+
+    ##
+    # @!method run(timeout = 120, poll_interval = 0)
+    # Run the job synchronously.
+    # @param timeout [Integer] The maximum time in seconds to wait for the job to complete.
+    # @param poll_interval [Integer] The interval in seconds between status queries (0 means auto).
+    # @return [String] The status of the job.
+    def run(timeout = 120, poll_interval = 0)
+      start
+      wait(timeout, poll_interval)
+    ensure
+      delete if defined?(@id)
     end
 
+    ##
+    # @!method delete
+    # Delete the job from the HMC.
     def delete
-      # Damien: check id is defined
+      raise JobNotStarted unless defined?(@id)
+
       method_url = "/rest/api/uom/jobs/#{@id}"
-      @hc.request(:delete, method_url)
+      @conn.request(:delete, method_url)
       # Returns HTTP 204 if ok
     end
   end

data/lib/ibm_power_hmc/parser.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'uri'
+
+module IbmPowerHmc
+  # Parser for HMC feeds and entries.
+  class Parser
+    def initialize(body)
+      @doc = REXML::Document.new(body)
+    end
+
+    def entry
+      @doc.elements["entry"]
+    end
+
+    def object(filter_type = nil)
+      self.class.to_obj(entry, filter_type)
+    end
+
+    def self.to_obj(entry, filter_type = nil)
+      return if entry.nil?
+
+      content = entry.elements["content"]
+      return if content.nil?
+
+      type = content.attributes["type"]
+      return if type.nil?
+
+      type = type.split("=").last
+      return unless filter_type.nil? || filter_type.to_s == type
+
+      Module.const_get("IbmPowerHmc::#{type}").new(entry)
+    end
+  end
+
+  class FeedParser < Parser
+    def entries
+      objs = []
+      @doc.each_element("feed/entry") do |entry|
+        objs << yield(entry)
+      end
+      objs
+    end
+
+    def objects(filter_type = nil)
+      entries do |entry|
+        self.class.to_obj(entry, filter_type)
+      end.compact
+    end
+  end
+
+  private_constant :Parser
+  private_constant :FeedParser
+
+  # HMC generic XML entry
+  class AbstractRest
+    ATTRS = {}.freeze
+    attr_reader :uuid, :published, :etag, :xml
+
+    def initialize(doc)
+      @uuid = doc.elements["id"]&.text
+      @published = Time.xmlschema(doc.elements["published"]&.text)
+      @etag = doc.elements["etag:etag"]&.text&.strip
+      type = self.class.name.split("::").last
+      @xml = doc.elements["content/#{type}:#{type}"]
+      define_attrs(self.class::ATTRS)
+    end
+
+    def define_attr(varname, xpath)
+      value = text_element(xpath)
+      self.class.__send__(:attr_reader, varname)
+      instance_variable_set("@#{varname}", value)
+    end
+
+    def define_attrs(hash)
+      hash.each do |key, value|
+        define_attr(key, value)
+      end
+    end
+
+    def text_element(xpath)
+      xml.elements[xpath]&.text&.strip
+    end
+
+    def extract_uuid_from_href(href)
+      URI(href).path.split('/').last
+    end
+  end
+
+  # HMC information
+  class ManagementConsole < AbstractRest
+    ATTRS = {
+      :name => "ManagementConsoleName",
+      :build_level => "VersionInfo/BuildLevel",
+      :version => "BaseVersion"
+    }.freeze
+
+    def managed_systems_uuids
+      xml.get_elements("ManagedSystems/link").map do |link|
+        extract_uuid_from_href(link.attributes["href"])
+      end.compact
+    end
+  end
+
+  # Managed System information
+  class ManagedSystem < AbstractRest
+    ATTRS = {
+      :name => "SystemName",
+      :state => "State",
+      :hostname => "Hostname",
+      :ipaddr => "PrimaryIPAddress",
+      :fwversion => "SystemFirmware",
+      :memory => "AssociatedSystemMemoryConfiguration/InstalledSystemMemory",
+      :avail_mem => "AssociatedSystemMemoryConfiguration/CurrentAvailableSystemMemory",
+      :cpus => "AssociatedSystemProcessorConfiguration/InstalledSystemProcessorUnits",
+      :avail_cpus => "AssociatedSystemProcessorConfiguration/CurrentAvailableSystemProcessorUnits",
+      :mtype => "MachineTypeModelAndSerialNumber/MachineType",
+      :model => "MachineTypeModelAndSerialNumber/Model",
+      :serial => "MachineTypeModelAndSerialNumber/SerialNumber"
+    }.freeze
+
+    def lpars_uuids
+      xml.get_elements("AssociatedLogicalPartitions/link").map do |link|
+        extract_uuid_from_href(link.attributes["href"])
+      end.compact
+    end
+
+    def vioses_uuids
+      xml.get_elements("AssociatedVirtualIOServers/link").map do |link|
+        extract_uuid_from_href(link.attributes["href"])
+      end.compact
+    end
+  end
+
+  # Common class for LPAR and VIOS
+  class BasePartition < AbstractRest
+    ATTRS = {
+      :os => "OperatingSystemVersion",
+      :name => "PartitionName",
+      :id => "PartitionID",
+      :state => "PartitionState",
+      :type => "PartitionType",
+      :memory => "PartitionMemoryConfiguration/CurrentMemory",
+      :dedicated => "PartitionProcessorConfiguration/HasDedicatedProcessors",
+      :rmc_state => "ResourceMonitoringControlState",
+      :rmc_ipaddr => "ResourceMonitoringIPAddress",
+      :ref_code => "ReferenceCode"
+    }.freeze
+
+    def sys_uuid
+      sys_href = xml.elements["AssociatedManagedSystem"].attributes["href"]
+      extract_uuid_from_href(sys_href)
+    end
+  end
+
+  # Logical Partition information
+  class LogicalPartition < BasePartition
+  end
+
+  # VIOS information
+  class VirtualIOServer < BasePartition
+  end
+
+  # HMC Event
+  class Event < AbstractRest
+    ATTRS = {
+      :id     => "EventID",
+      :type   => "EventType",
+      :data   => "EventData",
+      :detail => "EventDetail"
+    }.freeze
+  end
+
+  # Error response from HMC
+  class HttpErrorResponse < AbstractRest
+    ATTRS = {
+      :status  => "HTTPStatus",
+      :uri     => "RequestURI",
+      :reason  => "ReasonCode",
+      :message => "Message"
+    }.freeze
+  end
+
+  # Job Response
+  class JobResponse < AbstractRest
+    ATTRS = {
+      :id      => "JobID",
+      :status  => "Status",
+      :message => "ResponseException/Message"
+    }.freeze
+
+    def results
+      results = {}
+      xml.each_element("Results/JobParameter") do |result|
+        name = result.elements["ParameterName"]&.text&.strip
+        value = result.elements["ParameterValue"]&.text&.strip
+        results[name] = value unless name.nil?
+      end
+      results
+    end
+  end
+end

data/lib/ibm_power_hmc/pcm.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module IbmPowerHmc
+  class Connection
+    def pcm_preferences
+      method_url = "/rest/api/pcm/preferences"
+
+      response = request(:get, method_url)
+      REXML::Document.new(response.body)
+    end
+
+    ##
+    # @!method phyp_metrics(sys_uuid:, start_ts: nil, end_ts: nil, short_term: false)
+    # Retrieve PowerVM metrics for a given managed system.
+    # @param sys_uuid [String] The managed system UUID.
+    # @param start_ts [Time] Start timestamp.
+    # @param end_ts [Time] End timestamp.
+    # @param short_term [Boolean] Retrieve short term monitor metrics (default to long term).
+    # @return [Array<Hash>] The PowerVM metrics for the managed system.
+    def phyp_metrics(sys_uuid:, start_ts: nil, end_ts: nil, short_term: false)
+      type = short_term ? "ShortTermMonitor" : "LongTermMonitor"
+      method_url = "/rest/api/pcm/ManagedSystem/#{sys_uuid}/RawMetrics/#{type}"
+      query = {}
+      query["StartTS"] = self.class.format_time(start_ts) unless start_ts.nil?
+      query["EndTS"] = self.class.format_time(end_ts) unless end_ts.nil?
+      method_url += "?" + query.map { |h| h.join("=") }.join("&") unless query.empty?
+
+      response = request(:get, method_url)
+      FeedParser.new(response.body).entries do |entry|
+        link = entry.elements["link"]
+        next if link.nil?
+
+        href = link.attributes["href"]
+        next if href.nil?
+
+        response = request(:get, href)
+        JSON.parse(response.body)
+      end.compact
+    end
+
+    ##
+    # @!method managed_system_metrics(sys_uuid:, start_ts: nil, end_ts: nil, no_samples: nil, aggregated: false)
+    # Retrieve metrics for a managed system.
+    # @param sys_uuid [String] The managed system UUID.
+    # @param start_ts [Time] Start timestamp.
+    # @param end_ts [Time] End timestamp.
+    # @param no_samples [Integer] Number of samples.
+    # @param aggregated [Boolean] Retrieve aggregated metrics (default to Processed).
+    # @return [Array<Hash>] The metrics for the managed system.
+    def managed_system_metrics(sys_uuid:, start_ts: nil, end_ts: nil, no_samples: nil, aggregated: false)
+      type = aggregated ? "AggregatedMetrics" : "ProcessedMetrics"
+      method_url = "/rest/api/pcm/ManagedSystem/#{sys_uuid}/#{type}"
+      query = {}
+      query["StartTS"] = self.class.format_time(start_ts) unless start_ts.nil?
+      query["EndTS"] = self.class.format_time(end_ts) unless end_ts.nil?
+      query["NoOfSamples"] = no_samples unless no_samples.nil?
+      method_url += "?" + query.map { |h| h.join("=") }.join("&") unless query.empty?
+
+      response = request(:get, method_url)
+      FeedParser.new(response.body).entries do |entry|
+        category = entry.elements["category"]
+        next if category.nil?
+
+        term = category.attributes["term"]
+        next if term.nil? || term != "ManagedSystem"
+
+        link = entry.elements["link"]
+        next if link.nil?
+
+        href = link.attributes["href"]
+        next if href.nil?
+
+        response = request(:get, href)
+        JSON.parse(response.body)
+      end.compact
+    end
+
+    ##
+    # @!method lpar_metrics(sys_uuid:, lpar_uuid:, start_ts: nil, end_ts: nil, no_samples: nil, aggregated: false)
+    # Retrieve metrics for a logical partition.
+    # @param sys_uuid [String] The managed system UUID.
+    # @param lpar_uuid [String] The logical partition UUID.
+    # @param start_ts [Time] Start timestamp.
+    # @param end_ts [Time] End timestamp.
+    # @param no_samples [Integer] Number of samples.
+    # @param aggregated [Boolean] Retrieve aggregated metrics (default to Processed).
+    # @return [Array<Hash>] The metrics for the logical partition.
+    def lpar_metrics(sys_uuid:, lpar_uuid:, start_ts: nil, end_ts: nil, no_samples: nil, aggregated: false)
+      type = aggregated ? "AggregatedMetrics" : "ProcessedMetrics"
+      method_url = "/rest/api/pcm/ManagedSystem/#{sys_uuid}/LogicalPartition/#{lpar_uuid}/#{type}"
+      query = {}
+      query["StartTS"] = self.class.format_time(start_ts) unless start_ts.nil?
+      query["EndTS"] = self.class.format_time(end_ts) unless end_ts.nil?
+      query["NoOfSamples"] = no_samples unless no_samples.nil?
+      method_url += "?" + query.map { |h| h.join("=") }.join("&") unless query.empty?
+
+      response = request(:get, method_url)
+      FeedParser(response.body).entries do |entry|
+        link = entry.elements["link"]
+        next if link.nil?
+
+        href = link.attributes["href"]
+        next if href.nil?
+
+        response = request(:get, href)
+        JSON.parse(response.body)
+      end.compact
+    end
+
+    ##
+    # @!method format_time(time)
+    # Convert ruby time to HMC time format.
+    # @param time [Time] The ruby time to convert.
+    # @return [String] The time in HMC format.
+    def self.format_time(time)
+      time.utc.xmlschema
+    end
+  end
+end

data/lib/ibm_power_hmc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IbmPowerHmc
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/ibm_power_hmc.rb

@@ -7,7 +7,8 @@ require "ibm_power_hmc/version"
 
 # Module for IBM HMC Rest API Client
 module IbmPowerHmc
-  require_relative "./ibm_power_hmc/objects.rb"
+  require_relative "./ibm_power_hmc/parser.rb"
   require_relative "./ibm_power_hmc/job.rb"
   require_relative "./ibm_power_hmc/connection.rb"
+  require_relative "./ibm_power_hmc/pcm.rb"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ibm_power_hmc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - IBM Power
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-06 00:00:00.000000000 Z
+date: 2021-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -31,9 +31,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rubocop.yml"
+- ".rubocop_local.yml"
 - CHANGELOG.md
 - Gemfile
-- Gemfile.lock
 - LICENSE
 - README.md
 - Rakefile
@@ -43,7 +44,8 @@ files:
 - lib/ibm_power_hmc.rb
 - lib/ibm_power_hmc/connection.rb
 - lib/ibm_power_hmc/job.rb
-- lib/ibm_power_hmc/objects.rb
+- lib/ibm_power_hmc/parser.rb
+- lib/ibm_power_hmc/pcm.rb
 - lib/ibm_power_hmc/version.rb
 homepage: http://github.com/IBM/ibm_power_hmc_sdk_ruby
 licenses:

data/Gemfile.lock

@@ -1,37 +0,0 @@
-PATH
-  remote: .
-  specs:
-    ibm_power_hmc (0.1.0)
-      rest-client (~> 2.1)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    domain_name (0.5.20190701)
-      unf (>= 0.0.5, < 1.0.0)
-    http-accept (1.7.0)
-    http-cookie (1.0.4)
-      domain_name (~> 0.5)
-    mime-types (3.3.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2021.0704)
-    netrc (0.11.0)
-    rake (12.3.3)
-    rest-client (2.1.0)
-      http-accept (>= 1.7.0, < 2.0)
-      http-cookie (>= 1.0.2, < 2.0)
-      mime-types (>= 1.16, < 4.0)
-      netrc (~> 0.8)
-    unf (0.1.4)
-      unf_ext
-    unf_ext (0.0.7.7)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  ibm_power_hmc!
-  rake (~> 12.0)
-
-BUNDLED WITH
-   2.1.4

data/lib/ibm_power_hmc/objects.rb

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-require 'uri'
-
-# Module for IBM HMC Rest API Client
-module IbmPowerHmc
-  # HMC generic object
-  class HmcObject
-    attr_reader :uuid
-
-    def initialize(doc)
-      @uuid = doc.elements["id"].text
-    end
-
-    def get_value(doc, xpath, varname)
-      value = doc.elements[xpath]
-      value = value.text unless value.nil?
-      value = value.strip unless value.nil?
-      self.class.__send__(:attr_reader, "#{varname}")
-      instance_variable_set("@#{varname}", value)
-    end
-
-    def get_values(doc, hash)
-      hash.each do |key, value|
-        get_value(doc, key, value)
-      end
-    end
-
-    def to_s
-      "uuid=#{@uuid}"
-    end
-  end
-
-  # HMC information
-  class ManagementConsole < HmcObject
-    XMLMAP = {
-      "ManagementConsoleName" => "name",
-      "VersionInfo/BuildLevel" => "build_level",
-      "BaseVersion" => "version"
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/ManagementConsole:ManagementConsole"]
-      get_values(info, XMLMAP)
-    end
-
-    def to_s
-      "hmc name=#{@name} version=#{@version} build_level=#{@build_level}"
-    end
-  end
-
-  # Managed System information
-  class ManagedSystem < HmcObject
-    XMLMAP = {
-      "SystemName" => "name",
-      "State" => "state",
-      "Hostname" => "hostname",
-      "PrimaryIPAddress" => "ipaddr",
-      "AssociatedSystemMemoryConfiguration/InstalledSystemMemory" => "memory",
-      "AssociatedSystemMemoryConfiguration/CurrentAvailableSystemMemory" => "avail_mem",
-      "AssociatedSystemProcessorConfiguration/InstalledSystemProcessorUnits" => "cpus",
-      "AssociatedSystemProcessorConfiguration/CurrentAvailableSystemProcessorUnits" => "avail_cpus"
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/ManagedSystem:ManagedSystem"]
-      get_values(info, XMLMAP)
-    end
-
-    def to_s
-      "sys name=#{@name} state=#{@state} ip=#{@ipaddr} mem=#{@memory}MB avail=#{@avail_mem}MB CPUs=#{@cpus} avail=#{@avail_cpus}"
-    end
-  end
-
-  # Logical Partition information
-  class LogicalPartition < HmcObject
-    attr_reader :sys_uuid
-
-    XMLMAP = {
-      "PartitionName" => "name",
-      "PartitionID" => "id",
-      "PartitionState" => "state",
-      "PartitionType" => "type",
-      "PartitionMemoryConfiguration/CurrentMemory" => "memory",
-      "PartitionProcessorConfiguration/HasDedicatedProcessors" => "dedicated",
-      "ResourceMonitoringControlState" => "rmc_state",
-      "ResourceMonitoringIPAddress" => "rmc_ipaddr"
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/LogicalPartition:LogicalPartition"]
-      sys_href = info.elements["AssociatedManagedSystem"].attributes["href"]
-      @sys_uuid = URI(sys_href).path.split('/').last
-      get_values(info, XMLMAP)
-    end
-
-    def to_s
-      "lpar name=#{@name} id=#{@id} state=#{@state} type=#{@type} memory=#{@memory}MB dedicated cpus=#{@dedicated}"
-    end
-  end
-
-  # VIOS information
-  class VirtualIOServer < HmcObject
-    attr_reader :sys_uuid
-
-    XMLMAP = {
-      "PartitionName" => "name",
-      "PartitionID" => "id",
-      "PartitionState" => "state",
-      "PartitionType" => "type",
-      "PartitionMemoryConfiguration/CurrentMemory" => "memory",
-      "PartitionProcessorConfiguration/HasDedicatedProcessors" => "dedicated"
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/VirtualIOServer:VirtualIOServer"]
-      sys_href = info.elements["AssociatedManagedSystem"].attributes["href"]
-      @sys_uuid = URI(sys_href).path.split('/').last
-      get_values(info, XMLMAP)
-    end
-
-    def to_s
-      "vios name=#{@name} id=#{@id} state=#{@state} type=#{@type} memory=#{@memory}MB dedicated cpus=#{@dedicated}"
-    end
-  end
-
-  # LPAR profile
-  class LogicalPartitionProfile < HmcObject
-    attr_reader :lpar_uuid
-
-    # Damien: TBD
-  end
-
-  # HMC Event
-  class Event < HmcObject
-    XMLMAP = {
-      "EventID" => "id",
-      "EventType" => "type",
-      "EventData" => "data",
-      "EventDetail" => "detail",
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/Event:Event"]
-      get_values(info, XMLMAP)
-    end
-
-    def to_s
-      "event id=#{@id} type=#{@type} data=#{@data} detail=#{@detail}"
-    end
-  end
-end