xdoc/orm.dox

   1 /** @page orm Ninja - ORM - Dev. Manual
   2
   3 Access to livestatus and some other tables is accessed through an Object Relational abstraction layer, which makes it possible to add logic to the objects.
   4
   5 @section structure Structure
   6
   7 Each table is modelled by three classes: Pool, Set and Object.
   8
   9 @subsection class_object Object
  10
  11 An instance of an object class represents a single object. For example, Host_Model, represents a single host.
  12
  13 The object is only instanced from within a set class. (see below). The user must never instance the class manually.
  14
  15 Each object have getters for it's variables:
  16 @code
  17 $host->get_name();
  18 $service->get_description();
  19 @endcode
  20
  21 Related objects have getters to get the related object
  22 @code
  23 $host = $services->get_host(); /* Returns: Host_Model */
  24 @endcode
  25
  26 ..and the other way, but because of multiple related objects, a set is returned (see below for sets)
  27 @code
  28 $services = $host->get_services(); /* Returns: ServiceSet_Model */
  29 @endcode
  30
  31 @subsection class_set Sets
  32
  33 Set classes models a defined set of objects. A set can be for example the collection of all problem hosts, all services in a servicegroup or all comments related to a certain host.
  34
  35 Sets can be reduced by a filter line, using a livestatus-compatible operator. A new set is always returned:
  36 @code
  37 $set = $set->reduce_by('column_name', 'value', 'operator');
  38 @endcode
  39
  40 Set operations can be applied to sets. All set opertaions returns a new set:
  41 @code
  42 $set = $seta->union($setb);
  43 $set = $seta->intersect($setb);
  44 $set = $set->complement();
  45 @endcode
  46
  47 Sets of object can be converted to sets of a related object:
  48 @code
  49 $services_on_hosts = $host_set->get_services();
  50
  51 $host_comments_on_problem_hosts = $problem_hosts->get_comments();
  52 $service_comments_on_problem_hosts = $problem_hosts->get_services()->get_comments();
  53 $comments_on_problem_hosts = $host_comments_on_problem_hosts->union($service_comments_on_problem_hosts);
  54 @endcode
  55
  56 A set is countable:
  57 @code
  58 $number_problem_hosts = count($problem_hosts_set);
  59 @endcode
  60
  61 A set is iterable:
  62
  63 The database is queried  for all columns and no limit, so objects can be accessed.
  64 @code
  65 foreach( $host_set as $host ) {
  66         print $host-get_name() . "\n";
  67 }
  68 @endcode
  69
  70 Preferred way to iterate over a set is to use the ->it() method, which takes up to four arguments:
  71   * An array of columns to fetch. Only those columns contains valid information in the result, or false to fetch everything
  72   * An array of columns to order on, with possible order. First column has precedence.
  73   * (optional) an integer with the number of elements to fetch
  74   * (optional) an integer describing how many objects to skip at the beginning of the result set.
  75
  76 @code
  77 foreach( $service_set->it(array('host.name', 'description', 'host.status', 'status'), array('host.name', 'description), 100) as $service ) {
  78         $host = $service->get_host();
  79         print $host->get_name() . ';' . $service->get_description() . ': ' . (($host->get_status()>0) || ($service->get_status()>0) ? ' Problem' : 'OK');
  80 }
  81 @endcode
  82
  83 If the set is expected to only have up to one object, direct access to that object is possible through the ->one() method. This method takes one optional argument containing an array of which columns to fetch.
  84 @code
  85 $all = HostPool_Model::all();
  86 $host = $all->reduce_by('name', 'kaka', '=')->one();
  87 @endcode
  88
  89 @subsection class_pool Pools
  90
  91 A pool class models the collection of everything of a certain type. The main function of the pools is to give access to sets. This collection contains two primary static methods: all and non.
  92
  93 @code
  94 $all_hosts = HostPool_Model::all();
  95 $no_services = ServicePool_Model::none();
  96 @endcode
  97
  98 @section base_classes Base classes
  99
 100 All generated code is put in classes with prefix Base. All classes has a corresponding wrapper class with the same name, except the prefix.
 101
 102 The reason of the wrapper class is to put business-specific logic to the model. The base class should never be instanced directly, and therefore is abstract.
 103
 104 @code
 105 class Host_Model extends BaseHost_Model {
 106         /* Return the state as a text instead of code */
 107         public function get_state_text() {
 108                 if( !$this->get_has_been_checked() )
 109                         return 'pending';
 110                 switch( $this->get_state() ) {
 111                         case 0: return 'up';
 112                         case 1: return 'down';
 113                         case 2: return 'unreachable';
 114                 }
 115                 return 'unknown'; // should never happen
 116         }
 117 }
 118 @endcode
 119
 120 All table-specific classes do also extend a generic class, for example:
 121
 122 @code
 123 class Host_Model extends BaseHost_Model {...}
 124 class BaseHost_Model extends Object_Model {...}
 125
 126 class Object_Model extends BaseObject_Model {...}
 127 class BaseObject_Model {...}
 128 @endcode
 129
 130 Set classes do also have a driver-specific class:
 131
 132 @code
 133 class HostSet_Model extends BaseHostSet_Model {...}
 134 class BaseHostSet_Model extends ObjectLSSet_Model {...}
 135
 136 class ObjectLSSet_Model extends BaseObjectLSSet_Model {...}
 137 class BaseObjectLSSet_Model extends ObjectSet_Model {...}
 138
 139 class ObjectSet_Model extends BaseObjectSet_Model {...}
 140 class BaseObjectSet_Model {...}
 141 @endcode
 142
 143
 144 @section examples Examples
 145
 146 @section example_list_of_hosts List of hosts given an array of names
 147 To iterate over a couple of host, given an array of name, start with a empty set of hosts, and add one host at a time.
 148
 149 To fetch a given host, start with a set of all hosts, and reduce by the name is equal to the expected name. Combine the sets:
 150
 151 @code
 152 $hostnames = array(...);
 153
 154 $set = HostPool_Model::none();
 155 $all = HostPool_Model::all();
 156 foreach( $hostnames as $hostname ) {
 157         $this_set = $all->reduce_by( 'name', $hostname, '=' );
 158         $set = $set->union($this_set);
 159 }
 160
 161 foreach( $set as $host ) {
 162         do_something( $host );
 163 }
 164 @endcode
 165
 166
 167 */