zabbixapi 3.1.0 → 3.2.1

data/lib/zabbixapi.rb

@@ -1,127 +1,164 @@
-require "zabbixapi/version"
-require "zabbixapi/client"
-
-require "zabbixapi/basic/basic_alias"
-require "zabbixapi/basic/basic_func"
-require "zabbixapi/basic/basic_init"
-require "zabbixapi/basic/basic_logic"
-
-require "zabbixapi/classes/applications"
-require "zabbixapi/classes/errors"
-require "zabbixapi/classes/graphs"
-require "zabbixapi/classes/hostgroups"
-require "zabbixapi/classes/maintenance"
-require "zabbixapi/classes/hosts"
-require "zabbixapi/classes/httptests"
-require "zabbixapi/classes/items"
-require "zabbixapi/classes/mediatypes"
-require "zabbixapi/classes/proxies"
-require "zabbixapi/classes/screens"
-require "zabbixapi/classes/server"
-require "zabbixapi/classes/templates"
-require "zabbixapi/classes/triggers"
-require "zabbixapi/classes/unusable"
-require "zabbixapi/classes/usergroups"
-require "zabbixapi/classes/usermacros"
-require "zabbixapi/classes/users"
-require "zabbixapi/classes/configurations"
-require "zabbixapi/classes/actions"
-require "zabbixapi/classes/scripts"
+require 'zabbixapi/version'
+require 'zabbixapi/client'
+
+require 'zabbixapi/basic/basic_alias'
+require 'zabbixapi/basic/basic_func'
+require 'zabbixapi/basic/basic_init'
+require 'zabbixapi/basic/basic_logic'
+
+require 'zabbixapi/classes/actions'
+require 'zabbixapi/classes/applications'
+require 'zabbixapi/classes/configurations'
+require 'zabbixapi/classes/errors'
+require 'zabbixapi/classes/graphs'
+require 'zabbixapi/classes/hostgroups'
+require 'zabbixapi/classes/hosts'
+require 'zabbixapi/classes/httptests'
+require 'zabbixapi/classes/items'
+require 'zabbixapi/classes/maintenance'
+require 'zabbixapi/classes/mediatypes'
+require 'zabbixapi/classes/proxies'
+require 'zabbixapi/classes/screens'
+require 'zabbixapi/classes/scripts'
+require 'zabbixapi/classes/server'
+require 'zabbixapi/classes/templates'
+require 'zabbixapi/classes/triggers'
+require 'zabbixapi/classes/unusable'
+require 'zabbixapi/classes/usergroups'
+require 'zabbixapi/classes/usermacros'
+require 'zabbixapi/classes/users'
+require 'zabbixapi/classes/valuemaps'
 
 class ZabbixApi
+  # @return [ZabbixApi::Client]
+  attr_reader :client
 
-  attr :client
-
+  # Initializes a new ZabbixApi object
+  #
+  # @param options [Hash]
+  # @return [ZabbixApi]
   def self.connect(options = {})
     new(options)
   end
 
+  # @return [ZabbixApi]
   def self.current
     @current ||= ZabbixApi.new
   end
 
+  # Executes an API request directly using a custom query
+  #
+  # @param data [Hash]
+  # @return [Hash]
   def query(data)
     @client.api_request(:method => data[:method], :params => data[:params])
   end
 
+  # Initializes a new ZabbixApi object
+  #
+  # @param options [Hash]
+  # @return [ZabbixApi::Client]
   def initialize(options = {})
     @client = Client.new(options)
   end
 
-  def server
-    @server ||= Server.new(@client)
+  # @return [ZabbixApi::Actions]
+  def actions
+    @actions ||= Actions.new(@client)
   end
 
-  def users
-    @users ||= Users.new(@client)
+  # @return [ZabbixApi::Applications]
+  def applications
+    @applications ||= Applications.new(@client)
   end
 
-  def items
-    @items ||= Items.new(@client)
+  # @return [ZabbixApi::Configurations]
+  def configurations
+    @configurations ||= Configurations.new(@client)
   end
 
-  def hosts
-    @hosts ||= Hosts.new(@client)
+  # @return [ZabbixApi::Graphs]
+  def graphs
+    @graphs ||= Graphs.new(@client)
   end
 
-  def httptests
-    @httptests ||= HttpTests.new(@client)
+  # @return [ZabbixApi::HostGroups]
+  def hostgroups
+    @hostgroups ||= HostGroups.new(@client)
   end
 
-  def applications
-    @applications ||= Applications.new(@client)
+  # @return [ZabbixApi::Hosts]
+  def hosts
+    @hosts ||= Hosts.new(@client)
   end
 
-  def templates
-    @templates ||= Templates.new(@client)
+  # @return [ZabbixApi::HttpTests]
+  def httptests
+    @httptests ||= HttpTests.new(@client)
   end
 
-  def hostgroups
-    @hostgroups ||= HostGroups.new(@client)
+  # @return [ZabbixApi::Items]
+  def items
+    @items ||= Items.new(@client)
   end
 
+  # @return [ZabbixApi::Maintenance]
   def maintenance
     @maintenance ||= Maintenance.new(@client)
   end
 
-  def triggers
-    @triggers ||= Triggers.new(@client)
-  end
-
-  def graphs
-    @graphs ||= Graphs.new(@client)
+  # @return [ZabbixApi::Mediatypes]
+  def mediatypes
+    @mediatypes ||= Mediatypes.new(@client)
   end
 
+  # @return [ZabbixApi::Proxies]
   def proxies
     @proxies ||= Proxies.new(@client)
   end
 
+  # @return [ZabbixApi::Screens]
   def screens
     @screens ||= Screens.new(@client)
   end
 
-  def usergroups
-    @usergroups ||= Usergroups.new(@client)
+  # @return [ZabbixApi::Scripts]
+  def scripts
+    @scripts ||= Scripts.new(@client)
   end
 
-  def usermacros
-    @usermacros ||= Usermacros.new(@client)
+  # @return [ZabbixApi::Server]
+  def server
+    @server ||= Server.new(@client)
   end
 
-  def mediatypes
-    @mediatypes ||= Mediatypes.new(@client)
+  # @return [ZabbixApi::Templates]
+  def templates
+    @templates ||= Templates.new(@client)
   end
 
-  def configurations
-    @configurations ||= Configurations.new(@client)
+  # @return [ZabbixApi::Triggers]
+  def triggers
+    @triggers ||= Triggers.new(@client)
   end
 
-  def actions
-    @actions ||= Actions.new(@client)
+  # @return [ZabbixApi::Usergroups]
+  def usergroups
+    @usergroups ||= Usergroups.new(@client)
   end
 
-  def scripts
-    @scripts ||= Scripts.new(@client)
+  # @return [ZabbixApi::Usermacros]
+  def usermacros
+    @usermacros ||= Usermacros.new(@client)
+  end
+
+  # @return [ZabbixApi::Users]
+  def users
+    @users ||= Users.new(@client)
   end
 
+  # @return [ZabbixApi::ValueMaps]
+  def valuemaps
+    @valuemaps ||= ValueMaps.new(@client)
+  end
 end

data/lib/zabbixapi/basic/basic_alias.rb

@@ -1,20 +1,37 @@
 class ZabbixApi
   class Basic
-
+    # Get Zabbix object data from API by id
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Hash]
     def get(data)
       get_full_data(data)
     end
 
+    # Add new Zabbix object using API create
+    #
+    # @param data [Hash]
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is created
+    # @return [Boolean] True/False if multiple objects are created
     def add(data)
       create(data)
     end
 
+    # Destroy Zabbix object using API delete
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is deleted
+    # @return [Boolean] True/False if multiple objects are deleted
     def destroy(data)
       delete(data)
     end
 
-    def method_name
-    end
-
+    def method_name; end
   end
 end

data/lib/zabbixapi/basic/basic_func.rb

@@ -1,10 +1,17 @@
 class ZabbixApi
   class Basic
-
+    # Log messages to stdout when debugging
+    #
+    # @param message [String]
     def log(message)
-      puts "#{message}" if @client.options[:debug]
+      puts message.to_s if @client.options[:debug]
     end
 
+    # Compare two hashes for equality
+    #
+    # @param a [Hash]
+    # @param b [Hash]
+    # @return [Boolean]
     def hash_equals?(a, b)
       a_new = normalize_hash(a)
       b_new = normalize_hash(b)
@@ -13,40 +20,64 @@ class ZabbixApi
       hash1 == hash2
     end
 
-    def symbolize_keys(obj)
-      return obj.inject({}){|memo,(k,v)| memo[k.to_sym] =  symbolize_keys(v); memo} if obj.is_a? Hash
-      return obj.inject([]){|memo,v    | memo           << symbolize_keys(v); memo} if obj.is_a? Array
-      obj
+    # Convert all hash/array keys to symbols
+    #
+    # @param object [Array, Hash]
+    # @return [Array, Hash]
+    def symbolize_keys(object)
+      if object.is_a?(Array)
+        object.each_with_index do |val, index|
+          object[index] = symbolize_keys(val)
+        end
+      elsif object.is_a?(Hash)
+        object.keys.each do |key|
+          object[key.to_sym] = symbolize_keys(object.delete(key))
+        end
+      end
+      object
     end
 
+    # Normalize all hash values to strings
+    #
+    # @param hash [Hash]
+    # @return [Hash]
     def normalize_hash(hash)
       result = hash.dup
-      result.delete(:hostid) #TODO remove to logig. TemplateID and HostID has different id 
+
+      result.delete(:hostid) # TODO: remove to logig. TemplateID and HostID has different id
+
       result.each do |key, value|
-        case value
-          when Array
-            result[key] = normalize_array(value)
-          else
-            result[key] = value.to_s
-        end
+        result[key] = value.is_a?(Array) ? normalize_array(value) : value.to_s
       end
+
       result
     end
 
+    # Normalize all array values to strings
+    #
+    # @param array [Array]
+    # @return [Array]
     def normalize_array(array)
       result = []
+
       array.each do |e|
-        case e
-          when Array
-            result << normalize_array(e)
-          when Hash
-            result << normalize_hash(e)
-          else
-            result << e.to_s
+        if e.is_a?(Array)
+          result.push(normalize_array(e))
+        elsif e.is_a?(Hash)
+          result.push(normalize_hash(e))
+        else
+          result.push(e.to_s)
         end
       end
+
+      result
     end
 
+    # Parse a data hash for id key or boolean to return
+    #
+    # @param data [Hash]
+    # @return [Integer] The object id if a single object hash is provided with key
+    # @return [Boolean] True/False if multiple class object hash is provided
     def parse_keys(data)
       case data
       when Hash
@@ -55,15 +86,17 @@ class ZabbixApi
         true
       when FalseClass
         false
-      else
-        nil
       end
     end
 
+    # Merge two hashes into a single new hash
+    #
+    # @param a [Hash]
+    # @param b [Hash]
+    # @return [Hash]
     def merge_params(a, b)
       new = a.dup
       new.merge(b)
     end
-
   end
 end

data/lib/zabbixapi/basic/basic_init.rb

@@ -1,29 +1,46 @@
 class ZabbixApi
   class Basic
-
+    # Initializes a new Basic object with ZabbixApi Client
+    #
+    # @param client [ZabbixApi::Client]
+    # @return [ZabbixApi::Client]
     def initialize(client)
       @client = client
     end
 
+    # Placeholder for inherited objects to provide object-specific method name
+    #
+    # @raise [ApiError] Basic object does not directly support method_name
     def method_name
       raise ApiError.new("Can't call method_name here")
     end
 
+    # Placeholder for inherited objects to provide default options
+    #
+    # @return [Hash]
     def default_options
       {}
     end
 
+    # Returns the object's plural id field name (indentify) based on key
+    #
+    # @return [String]
     def keys
-      key + "s"
+      key + 's'
     end
 
+    # Returns the object's id field name (indentify) based on method_name + id
+    #
+    # @return [String]
     def key
-      method_name + "id"
+      method_name + 'id'
     end
 
+    # Placeholder for inherited objects to provide object-specific id field name
+    #
+    # @raise [ApiError] Basic object does not directly support indentify
     def indentify
       raise ApiError.new("Can't call indentify here")
     end
-
   end
 end

data/lib/zabbixapi/basic/basic_logic.rb

@@ -1,6 +1,12 @@
 class ZabbixApi
   class Basic
-
+    # Create new Zabbix object using API (with defaults)
+    #
+    # @param data [Hash]
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is created
+    # @return [Boolean] True/False if multiple objects are created
     def create(data)
       log "[DEBUG] Call create with parameters: #{data.inspect}"
 
@@ -10,6 +16,13 @@ class ZabbixApi
       parse_keys result
     end
 
+    # Delete Zabbix object using API
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is deleted
+    # @return [Boolean] True/False if multiple objects are deleted
     def delete(data)
       log "[DEBUG] Call delete with parameters: #{data.inspect}"
 
@@ -18,6 +31,13 @@ class ZabbixApi
       parse_keys result
     end
 
+    # Create or update Zabbix object using API
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is created
+    # @return [Boolean] True/False if multiple objects are created
     def create_or_update(data)
       log "[DEBUG] Call create_or_update with parameters: #{data.inspect}"
 
@@ -25,26 +45,36 @@ class ZabbixApi
       id ? update(data.merge(key.to_sym => id.to_s)) : create(data)
     end
 
-    def update(data, force=false)
+    # Update Zabbix object using API
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @param force [Boolean] Whether to force an object update even if provided data matches Zabbix
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is created
+    # @return [Boolean] True/False if multiple objects are created
+    def update(data, force = false)
       log "[DEBUG] Call update with parameters: #{data.inspect}"
-
       dump = {}
-      item_id = data[key.to_sym].to_i
       dump_by_id(key.to_sym => data[key.to_sym]).each do |item|
         dump = symbolize_keys(item) if item[key].to_i == data[key.to_sym].to_i
       end
-
-      if hash_equals?(dump, data) and not force
+      if hash_equals?(dump, data) && !force
         log "[DEBUG] Equal keys #{dump} and #{data}, skip update"
-        item_id
+        data[key.to_sym].to_i
       else
         data_update = [data]
         result = @client.api_request(:method => "#{method_name}.update", :params => data_update)
         parse_keys result
       end
-
     end
 
+    # Get full/extended Zabbix object data from API
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Hash]
     def get_full_data(data)
       log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
 
@@ -52,13 +82,19 @@ class ZabbixApi
         :method => "#{method_name}.get",
         :params => {
           :filter => {
-            indentify.to_sym => data[indentify.to_sym]
+            indentify.to_sym => data[indentify.to_sym],
           },
-          :output => "extend"
+          :output => 'extend',
         }
       )
     end
 
+    # Get raw Zabbix object data from API
+    #
+    # @param data [Hash]
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Hash]
     def get_raw(data)
       log "[DEBUG] Call get_raw with parameters: #{data.inspect}"
 
@@ -68,6 +104,12 @@ class ZabbixApi
       )
     end
 
+    # Dump Zabbix object data by key from API
+    #
+    # @param data [Hash] Should include desired object's key and value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Hash]
     def dump_by_id(data)
       log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
 
@@ -75,34 +117,44 @@ class ZabbixApi
         :method => "#{method_name}.get",
         :params => {
           :filter => {
-            key.to_sym => data[key.to_sym]
+            key.to_sym => data[key.to_sym],
           },
-          :output => "extend"
+          :output => 'extend',
         }
       )
     end
 
+    # Get full/extended Zabbix data for all objects of type/class from API
+    #
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Array<Hash>] Array of matching objects
     def all
       result = {}
-      @client.api_request(:method => "#{method_name}.get", :params => {:output => "extend"}).each do |item|
+      @client.api_request(:method => "#{method_name}.get", :params => {:output => 'extend'}).each do |item|
         result[item[indentify]] = item[key]
       end
       result
     end
 
+    # Get Zabbix object id from API based on provided data
+    #
+    # @param data [Hash]
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call or missing object's id field name (indentify).
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def get_id(data)
       log "[DEBUG] Call get_id with parameters: #{data.inspect}"
-
       # symbolize keys if the user used string keys instead of symbols
       data = symbolize_keys(data) if data.key?(indentify)
-      # raise an error if indentify name was not supplied 
+      # raise an error if indentify name was not supplied
       name = data[indentify.to_sym]
-      raise ApiError.new("#{indentify} not supplied in call to get_id") if name == nil
+      raise ApiError.new("#{indentify} not supplied in call to get_id") if name.nil?
       result = @client.api_request(
         :method => "#{method_name}.get",
         :params => {
           :filter => data,
-          :output => [key, indentify]
+          :output => [key, indentify],
         }
       )
       id = nil
@@ -110,6 +162,12 @@ class ZabbixApi
       id
     end
 
+    # Get or Create Zabbix object using API
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def get_or_create(data)
       log "[DEBUG] Call get_or_create with parameters: #{data.inspect}"
 
@@ -118,6 +176,5 @@ class ZabbixApi
       end
       id
     end
-
   end
 end