Status.dat query fixes and documentation after rebase

refs #3801

library/Icinga/Protocol/Statusdat/IReader.php

@@ -35,11 +35,6 @@ interface IReader
      */
     public function getState();
 
-    /**
-     * @return mixed
-     */
-    public function getObjects();
-
     /**
      * @param $type
      * @param $name

library/Icinga/Protocol/Statusdat/ObjectContainer.php

@@ -48,7 +48,7 @@ class ObjectContainer extends \stdClass
      * @param \stdClass $obj
      * @param IReader $reader
      */
-    public function __construct(\stdClass &$obj, IReader &$reader)
+    public function __construct(&$obj, IReader &$reader)
     {
         $this->ref = & $obj;
         $this->reader = & $reader;
@@ -68,6 +68,7 @@ public function __get($attribute)
                 $result = $result->$elem;
             }
         }
+
         return $result;
     }
 }

library/Icinga/Protocol/Statusdat/Parser.php

@@ -34,45 +34,59 @@
 use Icinga\Protocol\Statusdat\Exception\ParsingException as ParsingException;
 
 /**
- * Class Parser
- * @package Icinga\Protocol\Statusdat
+ * Status.dat and object.cache parser implementation
  */
 class Parser
 {
     /**
+     * An array of objects that couldn't be resolved yet due to missing dependencies
+     *
      * @var array
      */
     private $deferred = array();
 
     /**
-     * @var null|resource
+     * The resource pointing to the currently read  file
+     *
+     * @var resource
      */
-    private $filehandle = null;
+    private $filehandle;
 
     /**
-     * @var null
+     * String representation of the currently parsed object type
+     *
+     * @var string
      */
-    private $currentObjectType = null;
+    private $currentObjectType;
 
     /**
-     * @var null
+     * The current state type (host, service)
+     *
+     * @var string
      */
-    private $currentStateType = null;
+    private $currentStateType;
 
     /**
-     * @var null
+     * The internal representation of the icinga statue
+     *
+     * @var array
      */
-    private $icingaState = null;
+    private $icingaState;
 
     /**
+     * The current line being read
+     *
      * @var int
      */
     private $lineCtr = 0;
 
     /**
-     * @param null $filehandle
-     * @param null $baseState
-     * @throws \Icinga\Exception\ConfigurationError
+     * Create a new parser using the given file
+     *
+     * @param resource $filehandle                      The file handle to usefor parsing
+     * @param array $baseState                          The state using for the base
+     *
+     * @throws ConfigurationError                       When the file can't be used
      */
     public function __construct($filehandle = null, $baseState = null)
     {
@@ -85,7 +99,7 @@ public function __construct($filehandle = null, $baseState = null)
     }
 
     /**
-     *
+     * Parse the given file handle as an objects file and read object information
      */
     public function parseObjectsFile()
     {
@@ -110,8 +124,7 @@ public function parseObjectsFile()
     }
 
     /**
-     * @param null $filehandle
-     * @throws ProgrammingError
+     * Parse the given file handle as an status.dat file and read runtime information
      */
     public function parseRuntimeState($filehandle = null)
     {
@@ -126,26 +139,25 @@ public function parseRuntimeState($filehandle = null)
         }
         $this->overwrites = array();
         while (!feof($filehandle)) {
-
             $line = trim(fgets($filehandle));
-
             $this->lineCtr++;
             if ($line === "" || $line[0] === "#") {
                 continue;
             }
-
             $this->currentStateType = trim(substr($line, 0, -1));
             $this->readCurrentState();
         }
     }
 
     /**
-     * @throws Exception\ParsingException
+     * Read the next object from the object.cache file handle
+     *
+     * @throws ParsingException
      */
     private function readCurrentObject()
     {
         $filehandle = $this->filehandle;
-        $monitoringObject = new \stdClass();
+        $monitoringObject = new PrintableObject();
         while (!feof($filehandle)) {
             $line = explode("\t", trim(fgets($filehandle)), 2);
             $this->lineCtr++;
@@ -167,6 +179,8 @@ private function readCurrentObject()
     }
 
     /**
+     * Read the next state from the status.dat file handler
+     *
      * @throws Exception\ParsingException
      */
     private function readCurrentState()
@@ -201,9 +215,9 @@ private function readCurrentState()
         $type = substr($this->currentStateType, strlen($objectType));
 
         if ($type == "status") {
+            // directly set the status to the status field of the given object
             $base[$name]->status = & $statusdatObject;
         } else {
-
             if (!isset($base[$name]->$type) || !in_array($base[$name]->$type, $this->overwrites)) {
                 $base[$name]->$type = array();
                 $this->overwrites[] = & $base[$name]->$type;
@@ -225,7 +239,9 @@ private function readCurrentState()
     }
 
     /**
-     * @return null|string
+     * Get the corresponding object type name for the given state
+     *
+     * @return string
      */
     private function getObjectTypeForState()
     {
@@ -249,8 +265,10 @@ private function getObjectTypeForState()
     }
 
     /**
-     * @param bool $returnString
-     * @return string
+     * Skip the current object definition
+     *
+     * @param bool $returnString        If true, the object string will be returned
+     * @return string                   The skipped object if $returnString is true
      */
     protected function skipObject($returnString = false)
     {
@@ -268,7 +286,9 @@ protected function skipObject($returnString = false)
     }
 
     /**
-     * @param $object
+     * Register the given object in the icinga state
+     *
+     * @param object $object        The monitoring object to register
      */
     protected function registerObject(&$object)
     {
@@ -281,7 +301,11 @@ protected function registerObject(&$object)
     }
 
     /**
-     * @param $object
+     * Register the given object as a property in related objects
+     *
+     * This registers for example hosts underneath their hostgroup and vice cersa
+     *
+     * @param object $object        The object to register as a property
      */
     protected function registerObjectAsProperty(&$object)
     {
@@ -344,16 +368,18 @@ protected function registerObjectAsProperty(&$object)
     }
 
     /**
-     * @param $object
-     * @param $objType
+     * Defer registration of the given object
+     *
+     * @param object $object        The object to defer
+     * @param String $objType       The name of the object type
      */
     protected function deferRegistration($object, $objType)
     {
         $this->deferred[] = array($object, $objType);
     }
 
     /**
-     *
+     * Process deferred objects
      */
     protected function processDeferred()
     {
@@ -364,8 +390,10 @@ protected function processDeferred()
     }
 
     /**
-     * @param $object
-     * @return array
+     * Return the resolved members directive of an object
+     *
+     * @param  object $object       The object to get the members from
+     * @return array                An array of member names
      */
     protected function getMembers(&$object)
     {
@@ -388,8 +416,10 @@ protected function getMembers(&$object)
     }
 
     /**
-     * @param $object
-     * @return bool|string
+     * Return the unique name of the given object
+     *
+     * @param  object $object   The object to retrieve the name from
+     * @return string           The name of the object or null if no name can be retrieved
      */
     protected function getObjectIdentifier(&$object)
     {
@@ -409,11 +439,13 @@ protected function getObjectIdentifier(&$object)
         } elseif (isset($object->host_name)) {
             return $object->host_name;
         }
-        return false;
+        return null;
 
     }
 
     /**
+     * Return the internal state of the parser
+     *
      * @return null
      */
     public function getRuntimeState()

library/Icinga/Protocol/Statusdat/PrintableObject.php

@@ -0,0 +1,44 @@
+<?php
+// {{{ICINGA_LICENSE_HEADER}}}
+/**
+ * This file is part of Icinga 2 Web.
+ *
+ * Icinga 2 Web - Head for multiple monitoring backends.
+ * Copyright (C) 2013 Icinga Development Team
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * @copyright 2013 Icinga Development Team <info@icinga.org>
+ * @license   http://www.gnu.org/licenses/gpl-2.0.txt GPL, version 2
+ * @author    Icinga Development Team <info@icinga.org>
+ */
+// {{{ICINGA_LICENSE_HEADER}}}
+
+namespace Icinga\Protocol\Statusdat;
+
+class PrintableObject
+{
+    public function __toString()
+    {
+        if (isset($this->contact_name)) {
+            return $this->contact_name;
+        } else if (isset($this->service_description)) {
+            return $this->service_description;
+        } else if (isset($this->host_name)) {
+            return $this->host_name;
+        }
+        return '';
+    }
+}