NAME

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

SYNOPSIS

  package Zabbix2::API::Unicorn;

  use Moo;
  extends 'Zabbix2::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.

ATTRIBUTES

Note that subclasses may define their own attributes in addition to the ones in this base class.

data

(read-only hashref of object properties, defaults to {})

This is where the object properties obtained from the server are stored. To update the object on the server, modify the contents of the hashref and call the update method. Similarly, to create a brand new object on the server, create a Perl object with the desired properties in the data attribute, and call the create method.

root

(read-only required Zabbix2::API instance)

Reference to the current Zabbix connection object.

METHODS

_readonly_properties (optional abstract method)

  (not intended for public consumption)

This method, if implemented in a subclass, must return a hashref whose keys are property names. Those properties will be filtered out when the create and update methods are called. This is sometimes necessary because Zabbix complains that read-only properties must not be updated, even when their values have not changed.

create

  my $unicorn = Zabbix2::API::Unicorn->new(...);
  $unicorn->create;

This method calls the corresponding API CLASS.create method, which returns the ID of the new object. This ID is then set in the object.

If pull_after_push_mode is true in the Zabbix2::API object, the API CLASS.get method is then called to fetch the values of all server-generated properties.

delete

  $unicorn->delete;

This method calls the corresponding API CLASS.delete method. The object itself is not modified; you should probably stop using it afterwards as it will no longer exist on the server.

An exception is thrown if the object does not have an ID.

exists

  $unicorn->exists or say 'deleted';

This method checks that the ID still exists on the server. This is usually a good way to determine if the object has been deleted on the server, since Zabbix object IDs are not usually reused.

An exception is thrown if the object does not have an ID.

_extension (required abstract method)

  (not intended for public consumption)

This method's return value will be added to the API method call parameters when trying to fetch an object from the server. It should return valid CLASS.get parameters as a hash (not a hashref, mind). E.g., Zabbix2::API::Item's implementation is as follows:

  sub _extension {
      return (output => 'extend');
  }

id (required abstract method)

  # accessor
  say 'the id is '. $unicorn->id;
  # mutator
  $unicorn->id(3);

This method must implement a mutator for the object's ID. This is generally a wrapper around the "unicornid" key in the data attribute.

name (optional abstract method)

  say 'this thing is ' . $unicorn->name;

This method should return a human-readable name for the object; e.g. the implementation in the Zabbix2::API::Item class returns the parent host's name and the item's key, separated by a slash. No guarantees are made on the unicity or even usefulness of any implementation of this method, nor are any required.

Currently, not all subclasses implement this method, since it is optional. If you have a good implementation for a missing name method, please send a patch!

node_id

  say 'the unicorn lives on node ' . $unicorn->node_id;

This method returns the object's node's ID, or false if it does not live on a decentralized setup. Note that node-based setups are being deprecated in the 2.x series.

An exception is thrown if the object does not have an ID.

_prefix (required abstract method)

  (not intended for public consumption)

This method is where most class differentiation is done. It receives a single argument, usually a method name (prepended by a dot), and it should return the derivation appropriate for the class.

Most implementations just return a constant string prepended to the argument, e.g. Item's implementation returns "item$suffix": "item.create", etc. However, some implementations are more complicated; the Macro class, for instance, needs to check the instance to determine if it is used as a host macro or a global macro.

pull

  $unicorn->pull;

The pull method fetches an object's properties from the server and sets the data attribute with them.

An exception is thrown if the object does not have an ID.

Note that this method is not aware if you previously retrieved the object with an "output" parameter to limit the columns retrieved, so it will pull all columns from the server every time.

short_class

  # this is a Unicorn
  say 'this is a ' . $unicorn->short_class;

This method returns a shortened class name. The "Zabbix2::API::" prefix is removed.

update

  $unicorn->data->{some_property} = 'some_value';
  $unicorn->update;

This is the opposite of pull.

"PARTIAL" SUBCLASSES

Some subclasses do not actually need to be a full implementation to be useful; e.g. the Zabbix2::API::HostInterface class is only ever manipulated through Zabbix2::API::Host instances. Calling fetch with the intent of creating objects of these classes will throw an exception.

SEE ALSO

Zabbix2::API and the Zabbix API documentation at http://www.zabbix.com/documentation/start.

AUTHOR

Fabrice Gabolde <fga@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011, 2014 SFR

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

cpanm Zabbix2::API

perl -MCPAN -e shell
install Zabbix2::API