<?php
  /**

   * PHP OpenCloud library
   * 
   * @copyright 2014 Rackspace Hosting, Inc. See LICENSE for information.
   * @license   https://www.apache.org/licenses/LICENSE-2.0
   * @author    Glen Campbell <glen.campbell@rackspace.com>
   * @author    Jamie Hannaford <jamie.hannaford@rackspace.com>

   */
  
  namespace OpenCloud\Common;

  use Guzzle\Http\Exception\BadResponseException;
  use Guzzle\Http\Message\Response;
  use Guzzle\Http\Url;
  use OpenCloud\Common\Constants\State as StateConst;
  use OpenCloud\Common\Service\ServiceInterface;
  use OpenCloud\Common\Exceptions\RuntimeException;
  use OpenCloud\Common\Http\Message\Formatter;

  /**
   * Represents an object that can be retrieved, created, updated and deleted.
   *
   * This class abstracts much of the common functionality between: 
   *  
   *  * Nova servers;
   *  * Swift containers and objects;
   *  * DBAAS instances;
   *  * Cinder volumes;
   *  * and various other objects that:
   *    * have a URL;
   *    * can be created, updated, deleted, or retrieved;
   *    * use a standard JSON format with a top-level element followed by 
   *      a child object with attributes.
   *
   * In general, you can create a persistent object class by subclassing this
   * class and defining some protected, static variables:
   * 
   *  * $url_resource - the sub-resource value in the URL of the parent. For
   *    example, if the parent URL is `http://something/parent`, then setting this
   *    value to "another" would result in a URL for the persistent object of 
   *    `http://something/parent/another`.
   *
   *  * $json_name - the top-level JSON object name. For example, if the
   *    persistent object is represented by `{"foo": {"attr":value, ...}}`, then
   *    set $json_name to "foo".
   *
   *  * $json_collection_name - optional; this value is the name of a collection
   *    of the persistent objects. If not provided, it defaults to `json_name`
   *    with an appended "s" (e.g., if `json_name` is "foo", then
   *    `json_collection_name` would be "foos"). Set this value if the collection 
   *    name doesn't follow this pattern.
   *
   *  * $json_collection_element - the common pattern for a collection is:
   *    `{"collection": [{"attr":"value",...}, {"attr":"value",...}, ...]}`
   *    That is, each element of the array is a \stdClass object containing the
   *    object's attributes. In rare instances, the objects in the array
   *    are named, and `json_collection_element` contains the name of the
   *    collection objects. For example, in this JSON response:
   *    `{"allowedDomain":[{"allowedDomain":{"name":"foo"}}]}`,
   *    `json_collection_element` would be set to "allowedDomain".
   *
   * The PersistentObject class supports the standard CRUD methods; if these are 
   * not needed (i.e. not supported by  the service), the subclass should redefine 
   * these to call the `noCreate`, `noUpdate`, or `noDelete` methods, which will 
   * trigger an appropriate exception. For example, if an object cannot be created:
   *
   *    function create($params = array()) 
   *    { 
   *       $this->noCreate(); 
   *    }
   */
  abstract class PersistentObject extends Base
  {

      private $service;

      private $parent;

      protected $metadata;

  
      /**
       * Retrieves the instance from persistent storage
       *
       * @param mixed $service The service object for this resource
       * @param mixed $info    The ID or array/object of data
       */
      public function __construct($service = null, $info = null)
      {

          if ($service instanceof ServiceInterface) {

              $this->setService($service);
          }
          

          $this->metadata = new Metadata;

          $this->populate($info);
      }

      /**
       * Sets the service associated with this resource object.
       * 

       * @param \OpenCloud\Common\Service\ServiceInterface $service
       * @return \OpenCloud\Common\PersistentObject

       */

      public function setService(ServiceInterface $service)

      {
          $this->service = $service;
          return $this;
      }
      
      /**
       * Returns the service object for this resource; required for making
       * requests, etc. because it has direct access to the Connection.
       * 

       * @return \OpenCloud\Common\Service\ServiceInterface
       * @throws \OpenCloud\Common\Exceptions\ServiceException

       */
      public function getService()
      {
          if (null === $this->service) {

              throw new Exceptions\ServiceException(

                  'No service defined'
              );
          }
          return $this->service;
      }
      
      /**

       * Set the parent object for this resource.
       * 
       * @param \OpenCloud\Common\PersistentObject $parent

       * @return \OpenCloud\Common\PersistentObject

       */
      public function setParent(PersistentObject $parent)
      {
          $this->parent = $parent;
          return $this;
      }
      
      /**
       * Returns the parent.
       * 
       * @return \OpenCloud\Common\PersistentObject
       */
      public function getParent()
      {
          if (null === $this->parent) {
              $this->parent = $this->getService();
          }
          return $this->parent;
      }

          
      public function getClient()

      {

          return $this->getService()->getClient();

      }
      

      public function setMetadata($metadata)
      {
          $this->metadata = $metadata;
          
          return $this;
      }

      public function getMetadata()
      {
          return $this->metadata;
      }

      /**
       * Creates a new object
       *

       * @param array $params array of values to set when creating the object
       * @return HttpResponse
       * @throws VolumeCreateError if HTTP status is not Success
       */
      public function create($params = array())
      {
          // set parameters
          if (!empty($params)) {
              $this->populate($params, false);
          }

          // construct the JSON

          $json = json_encode($this->createJson());

          $this->checkJsonError();

          $createUrl = $this->createUrl();

          $response = $this->getClient()->post($createUrl, self::getJsonHeader(), $json)->send();
  
          // We have to try to parse the response body first because it should have precedence over a Location refresh.
          // I'd like to reverse the order, but Nova instances return ephemeral properties on creation which are not
          // available when you follow the Location link...
          if (null !== ($decoded = $this->parseResponse($response))) {
              $this->populate($decoded);
          } elseif ($location = $response->getHeader('Location')) {
              $this->refreshFromLocationUrl($location);

          }

  
          return $response;
      }

      public function refreshFromLocationUrl($url)
      {
          $fullUrl = Url::factory($url);
  
          $response = $this->getClient()->get($fullUrl)->send();
  
          if (null !== ($decoded = $this->parseResponse($response))) {
              $this->populate($decoded);
          }
      }

      /**
       * Updates an existing object
       *
       * @api
       * @param array $params array of values to set when updating the object
       * @return HttpResponse
       * @throws VolumeCreateError if HTTP status is not Success
       */
      public function update($params = array())
      {
          // set parameters
          if (!empty($params)) {
              $this->populate($params);
          }
  
          // debug
          $this->getLogger()->info('{class}::Update({name})', array(
              'class' => get_class($this),

              'name'  => $this->getProperty($this->primaryKeyField())

          ));
  
          // construct the JSON

          $json = json_encode($this->updateJson($params));

          $this->checkJsonError();

          // send the request

          return $this->getClient()->put($this->getUrl(), self::getJsonHeader(), $json)->send();
      }
  
      /**
       * Refreshes the object from the origin (useful when the server is
       * changing states)
       *
       * @param string|null $id
       * @param string|null $url
       *
       * @return void
       * @throws Exceptions\IdRequiredError
       */
      public function refresh($id = null, $url = null)
      {
          $primaryKey = $this->primaryKeyField();
          $primaryKeyVal = $this->getProperty($primaryKey);
          
          if (!$url) {
              
              if (!$id = $id ?: $primaryKeyVal) {
                  throw new Exceptions\IdRequiredError(sprintf(
                      Lang::translate("%s has no %s; cannot be refreshed"),
                      get_class($this),
                      $primaryKey
                  ));
              }
              
              if ($primaryKeyVal != $id) {
                  $this->setProperty($primaryKey, $id);
              }
              
              $url = $this->getUrl();
          }
          
          // reset status, if available
          if ($this->getProperty('status')) {
              $this->setProperty('status', null);

          }

          $response = $this->getClient()->get($url)->send();
    
          if (null !== ($decoded = $this->parseResponse($response))) {
              $this->populate($decoded);
          }
          

          return $response;
      }

      /**
       * Deletes an object
       *
       * @api
       * @return HttpResponse
       * @throws DeleteError if HTTP status is not Success
       */
      public function delete()
      {
          $this->getLogger()->info('{class}::Delete()', array('class' => get_class($this)));
  
          // send the request

          return $this->getClient()->delete($this->getUrl())->send();

      }
  
      /**

       * @deprecated

       */

      public function url($path = null, array $query = array())

      {

          return $this->getUrl($path, $query);

      }
  
      /**

       * Returns the default URL of the object
       *
       * This may have to be overridden in subclasses.
       *
       * @param string $subresource optional sub-resource string
       * @param array $qstr optional k/v pairs for query strings
       * @return string

       */

      public function getUrl($path = null, array $query = array())

      {

          if (!$url = $this->findLink('self')) {

              // ...otherwise construct a URL from parent and this resource's
              // "URL name". If no name is set, resourceName() throws an error.
              $url = $this->getParent()->getUrl($this->resourceName());

              // Does it have a primary key?
              if (null !== ($primaryKey = $this->getProperty($this->primaryKeyField()))) {
                  $url->addPath((string) $primaryKey);
              }

          }

          if (!$url instanceof Url) {
              $url = Url::factory($url);

          }

          return $url->addPath((string) $path)->setQuery($query);

      }
  
      /**
       * Waits for the server/instance status to change
       *
       * This function repeatedly polls the system for a change in server
       * status. Once the status reaches the `$terminal` value (or 'ERROR'),
       * then the function returns.
       *

       * @api
       * @param string $terminal the terminal state to wait for
       * @param integer $timeout the max time (in seconds) to wait
       * @param callable $callback a callback function that is invoked with
       *      each repetition of the polling sequence. This can be used, for
       *      example, to update a status display or to permit other operations
       *      to continue
       * @return void

       * @codeCoverageIgnore

       */

      public function waitFor($state = null, $timeout = null, $callback = null, $interval = null)
      {
          $state    = $state ?: StateConst::ACTIVE;
          $timeout  = $timeout ?: StateConst::DEFAULT_TIMEOUT;
          $interval = $interval ?: StateConst::DEFAULT_INTERVAL;

  
          // save stats
          $startTime = time();
          

          $states = array('ERROR', $state);

          
          while (true) {
              

              $this->refresh($this->getProperty($this->primaryKeyField()));

              
              if ($callback) {
                  call_user_func($callback, $this);
              }
              
              if (in_array($this->status(), $states) || (time() - $startTime) > $timeout) {
                  return;
              }

              sleep($interval);

          }

      }

      
      /**

       * Sends the json string to the /action resource
       *
       * This is used for many purposes, such as rebooting the server,
       * setting the root password, creating images, etc.
       * Since it can only be used on a live server, it checks for a valid ID.
       *
       * @param $object - this will be encoded as json, and we handle all the JSON
       *     error-checking in one place

       * @throws Exceptions\IdRequiredError if server ID is not defined
       * @throws Exceptions\ServerActionError on other errors

       * @returns boolean; TRUE if successful, FALSE otherwise
       */
      protected function action($object)
      {

          if (!$this->getProperty($this->primaryKeyField())) {

              throw new Exceptions\IdRequiredError(sprintf(
                  Lang::translate('%s is not defined'),

                  get_class($this),
                  $this->primaryKeyField()

              ));
          }
  
          if (!is_object($object)) {
              throw new Exceptions\ServerActionError(sprintf(
                  Lang::translate('%s::Action() requires an object as its parameter'),
                  get_class($this)
              ));
          }
  
          // convert the object to json
          $json = json_encode($object);

          $this->checkJsonError();
  
          // debug - save the request
          $this->getLogger()->info(Lang::translate('{class}::action [{json}]'), array(
              'class' => get_class($this), 
              'json'  => $json
          ));
  
          // get the URL for the POST message
          $url = $this->url('action');
  
          // POST the message

          return $this->getClient()->post($url, self::getJsonHeader(), $json)->send();
      }

       /**
       * Returns an object for the Create() method JSON
       * Must be overridden in a child class.
       *
       * @throws CreateError if not overridden
       */
      protected function createJson()
      {
          if (!isset($this->createKeys)) {
              throw new RuntimeException(sprintf(
                  'This resource object [%s] must have a visible createKeys array',

                  get_class($this)
              ));
          }
          

          $element = (object) array();
  
          foreach ($this->createKeys as $key) {
              if (null !== ($property = $this->getProperty($key))) {
                  $element->$key = $property;
              }

          }

          if (isset($this->metadata) && count($this->metadata)) {
              $element->metadata = (object) $this->metadata->toArray();
          }
  
          return (object) array($this->jsonName() => (object) $element);

      }

      /**

       * Returns an object for the Update() method JSON
       * Must be overridden in a child class.
       *
       * @throws Exceptions\UpdateError if not overridden

       */

      protected function updateJson($params = array())

      {

          throw new Exceptions\UpdateError(sprintf(
              Lang::translate('[%s] UpdateJson() must be overridden'),
              get_class($this)
          ));
      }

      /**
       * throws a CreateError for subclasses that don't support Create
       *
       * @throws Exceptions\CreateError
       */
      protected function noCreate()
      {
          throw new Exceptions\CreateError(sprintf(
              Lang::translate('[%s] does not support Create()'),
              get_class($this)
          ));
      }

      /**
       * throws a DeleteError for subclasses that don't support Delete
       *
       * @throws Exceptions\DeleteError
       */
      protected function noDelete()
      {
          throw new Exceptions\DeleteError(sprintf(
              Lang::translate('[%s] does not support Delete()'),
              get_class($this)
          ));
      }

      /**
       * throws a UpdateError for subclasses that don't support Update
       *
       * @throws Exceptions\UpdateError
       */
      protected function noUpdate()
      {
          throw new Exceptions\UpdateError(sprintf(
              Lang::translate('[%s] does not support Update()'),
              get_class($this)
          ));
      }
          
      /**
       * Returns the displayable name of the object
       *
       * Can be overridden by child objects; *must* be overridden by child
       * objects if the object does not have a `name` attribute defined.
       *
       * @api
       * @return string
       * @throws Exceptions\NameError if attribute 'name' is not defined
       */
      public function name()
      {
          if (null !== ($name = $this->getProperty('name'))) {
              return $name;
          } else {
              throw new Exceptions\NameError(sprintf(
                  Lang::translate('Name attribute does not exist for [%s]'),
                  get_class($this)

              ));
          }

      }
  
      /**
       * returns the object's status or `N/A` if not available
       *
       * @api
       * @return string
       */
      public function status()
      {
          return (isset($this->status)) ? $this->status : 'N/A';
      }
  
      /**
       * returns the object's identifier
       *
       * Can be overridden by a child class if the identifier is not in the
       * `$id` property. Use of this function permits the `$id` attribute to
       * be protected or private to prevent unauthorized overwriting for
       * security.
       *
       * @api
       * @return string
       */
      public function id()
      {
          return $this->id;
      }
  
      /**
       * checks for `$alias` in extensions and throws an error if not present
       *

       * @throws Exceptions\UnsupportedExtensionError

       */
      public function checkExtension($alias)
      {
          if (!in_array($alias, $this->getService()->namespaces())) {
              throw new Exceptions\UnsupportedExtensionError(sprintf(
                  Lang::translate('Extension [%s] is not installed'),
                  $alias
              ));
          }
          
          return true;
      }
  
      /**
       * returns the region associated with the object
       *
       * navigates to the parent service to determine the region.
       *
       * @api
       */
      public function region()
      {
          return $this->getService()->Region();
      }
      
      /**
       * Since each server can have multiple links, this returns the desired one
       *
       * @param string $type - 'self' is most common; use 'bookmark' for
       *      the version-independent one
       * @return string the URL from the links block
       */
      public function findLink($type = 'self')
      {
          if (empty($this->links)) {
              return false;
          }
  
          foreach ($this->links as $link) {
              if ($link->rel == $type) {
                  return $link->href;
              }
          }
  
          return false;
      }
  
      /**
       * returns the URL used for Create
       *
       * @return string
       */

      public function createUrl()

      {

          return $this->getParent()->getUrl($this->resourceName());

      }
  
      /**
       * Returns the primary key field for the object
       *
       * The primary key is usually 'id', but this function is provided so that
       * (in rare cases where it is not 'id'), it can be overridden.
       *
       * @return string
       */
      protected function primaryKeyField()
      {
          return 'id';
      }
  
      /**
       * Returns the top-level document identifier for the returned response
       * JSON document; must be overridden in child classes
       *
       * For example, a server document is (JSON) `{"server": ...}` and an
       * Instance document is `{"instance": ...}` - this function must return
       * the top level document name (either "server" or "instance", in
       * these examples).
       *

       * @throws Exceptions\DocumentError if not overridden

       */
      public static function jsonName()
      {
          if (isset(static::$json_name)) {
              return static::$json_name;
          }
  
          throw new Exceptions\DocumentError(sprintf(
              Lang::translate('No JSON object defined for class [%s] in JsonName()'),
              get_class()
          ));
      }
  
      /**
       * returns the collection JSON element name
       *
       * When an object is returned in a collection, it usually has a top-level
       * object that is an array holding child objects of the object types.
       * This static function returns the name of the top-level element. Usually,
       * that top-level element is simply the JSON name of the resource.'s';
       * however, it can be overridden by specifying the $json_collection_name
       * attribute.
       *
       * @return string
       */
      public static function jsonCollectionName()
      {
          if (isset(static::$json_collection_name)) {
              return static::$json_collection_name;
          } else {
              return static::$json_name . 's';
          }
      }
  
      /**
       * returns the JSON name for each element in a collection
       *
       * Usually, elements in a collection are anonymous; this function, however,
       * provides for an element level name:
       *
       *  `{ "collection" : [ { "element" : ... } ] }`
       *
       * @return string
       */
      public static function jsonCollectionElement()
      {
          if (isset(static::$json_collection_element)) {
              return static::$json_collection_element;
          }
      }
  
      /**
       * Returns the resource name for the URL of the object; must be overridden
       * in child classes
       *
       * For example, a server is `/servers/`, a database instance is
       * `/instances/`. Must be overridden in child classes.
       *

       * @throws Exceptions\UrlError

       */
      public static function resourceName()
      {
          if (isset(static::$url_resource)) {
              return static::$url_resource;
          }
  
          throw new Exceptions\UrlError(sprintf(
              Lang::translate('No URL resource defined for class [%s] in ResourceName()'),
              get_class()
          ));
      }

      
      public function parseResponse(Response $response)
      {
          $body = Formatter::decode($response);
          
          $top = $this->jsonName();
              
          if ($top && isset($body->$top)) {
              $content = $body->$top;
          } else {
              $content = $body;
          }
          
          return $content;
      }

  }