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.

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.