NAME

       Zabbix::API::CRUDE -- Base abstract class for most Zabbix::API::* objects

SYNOPSIS

         package Zabbix::API::Unicorn;

         use parent qw/Zabbix::API::CRUDE/;

         # now override some virtual methods so that it works for the specific case of
         # unicorns

         sub id { ... }
         sub prefix { ... }
         sub extension { ... }

DESCRIPTION

       This module handles most aspects of pushing, pulling and deleting the various types of
       Zabbix objects.  You do not want to use this directly; a few abstract methods need to be
       implemented by a subclass.

   WHY "CRUDE"?
       1.  On top of Create, Read, Update and Delete, the Zabbix API also implements an Exists
           operation.

       2.  It was written in a hurry.

METHODS

       new([DATA]) (constructor)
           This is the standard, boilerplate Perl OO constructor.  It returns a blessed hashref
           with the contents of "DATA", which should be a hash.

       id([NEWID]) (abstract method)
           This method must implement a mutator for the relevant unique Zabbix ID (e.g. for
           hosts, "hostid").  What this means is, it must accept zero or one argument; if zero,
           return the current ID or undef; if one, set the current ID in the raw data hash (see
           the "data()" method) and return it.

       node_id()
           This method returns the current object's node ID, for distributed setups.  For objects
           in non-distributed setups, whose IDs do not include a node ID, and objects that have
           never been pushed to the server, this method will return false.

       prefix([SUFFIX]) (abstract method)
           This method must return a string that corresponds to its type (e.g. "host").  It
           should accept one optional argument to concatenate to the type; this kludge is
           necessary for types that have a different name depending on where they are used (e.g.
           graph items -- not currently implemented as such -- have a "graphitemid" but are
           referred to as "gitems" elsewhere).

           This is a class and instance method (and it returns the same thing in both cases so
           far).  Warning: do not rely too much on this returning the correct compound name for
           any SUFFIX, as I have implemented only those special cases that were of interest for
           the rest of the distribution.

       extension() (abstract method)
           This method must return a list that contains the various parameters necessary to fetch
           more data.  (Returning an empty hash means that in most cases, only the IDs will be
           sent by the server.)  E.g. for hosts, this is "return (output => 'extend')".

       name() (abstract method)
           This method must return a preferably unique human-readable identifier.  For instance,
           hosts return the "host" attribute.

       data()
           This is a standard accessor for the raw data as fetched from Zabbix and converted into
           a hashref.  You can use "pull()" as a mutator on the same (but not for long).

       pull([DATA])
           Without an argument, fetches the raw data from the Zabbix server and updates the Perl
           object appropriately.  Calling "pull" on objects that do not have an ID set (they have
           not been fetched from the server, have never been pushed, or you have removed the ID
           yourself for obscure reasons) throws an exception.

           With a hashref argument, sets the raw data on the object directly, although this will
           change in a future version.

           In any case, this does not save your modifications for you.  If you have changed the
           object's data in any way and not pushed the modifications to the server, they will be
           overwritten.

       created()
           This checks that the server knows about the object (has an object of the same type
           with the same ID).

       collides() (abstract method)
           This method must return a list of objects (hashrefs of data, not instances of
           "Zabbix::API"!)  that would cause the Zabbix server to reply "... already exists" if
           the invocant were created (as with a push).

       push()
           Create the object on the server if it doesn't exist, update it if it does.  This
           distinction means that an object which has an ID, but not a server representation, is
           in an illegal state; calling "push" on such an object throws an exception.  Some
           classes (e.g. "Screen") override this to ensure that other objects they depend on are
           created before they are.

       delete()
           Deletes the object on the server and the local index (if you fetch it again it will be
           a different object from the one you're "holding").

SEE ALSO

       Zabbix::API, the Zabbix API documentation at <http://www.zabbix.com/documentation/start>.

AUTHOR

       Fabrice Gabolde <fabrice.gabolde@uperto.com>

COPYRIGHT AND LICENSE

       Copyright (C) 2011 SFR

       This library is free software; you can redistribute it and/or modify it under the terms of
       the GPLv3.