tripal/tripal_ws/includes/TripalWebService.inc

<?php

class TripalWebService {

  // --------------------------------------------------------------------------
  //                     EDITABLE STATIC CONSTANTS
  //
  // The following constants SHOULD be set for each descendent class.  They are
  // used by the static functions to provide information to Drupal about
  // the field and it's default widget and formatter.
  // --------------------------------------------------------------------------
  /**
   * The human-readable label for this web service.
   */
  public static $label = 'Base WebService';
  /**
   * A bit of text to describe what this service provides.
   */
  public static $description = 'This is the base class for Tripal web services as is not meant to be used on it\'s own';
  /**
   * A machine-readable type for this service. This name must be unique
   * among all Tripal web services and is used to form the URL to access
   * this service.
   */
  public static $type = 'services';


  // --------------------------------------------------------------------------
  //              PROTECTED CLASS MEMBERS -- DO NOT OVERRIDE
  // --------------------------------------------------------------------------
  /**
   * The resource that will be returned by the webservice given the
   * arguments provided.  This is a private
   */
  protected $resource;

  /**
   * An array containing the elements of the URL path. Each level of the
   * URL appears in a separate element of the array. The service type and
   * version are automatically removed from the array.
   */
  protected $path;

  /**
   * The set of paramters provided to the sesrvice. These are the values
   * that would occur in a URL after the question mark in an HTTP GET or
   * the data items of an HTTP POST.
   */
  protected $params;

  /**
   * The URL at which Tripal web services are found.  This is used
   * for creating the IRI for resources.
   */
  protected $base_path;

  /**
   * The list of documented classes used by this service. For the web service
   * to be discoverable all of the entity classes and their collections
   * must be defined.
   */
  protected $documentation;

  // --------------------------------------------------------------------------
  //                             CONSTRUCTORS
  // --------------------------------------------------------------------------
  /**
   * Implements the constructor.
   */
  public function __construct($base_path) {
    if (!$base_path) {
      throw new Exception('Please provide a $base_path argument when creating a new TripalWebService.');
    }

    // Create a default resource so that the service always some something.
    $this->resource = new TripalWebServiceResource($base_path);

    // Intialize the private members variables.
    $this->path = array();
    $this->params = array();
    $this->base_path = $base_path;
    $this->documentation = array();

    $this->addDocClass(array(
      "id" => "http://www.w3.org/ns/hydra/core#Resource",
      "name" => 'resource',
      "title" => "Resource",
      'subClassOf' => NULL,
    ));

  }

  // --------------------------------------------------------------------------
  //                          OVERRIDEABLE FUNCTIONS
  // --------------------------------------------------------------------------


  /**
   * Responds to the request argument provided to the service.
   *
   * This function should be implemented by a TripalWebService child class.
   *
   */
  public function handleRequest() {
    // TODO: make sure the $this->path and $this->params are set before
    // continuing.
  }

  // --------------------------------------------------------------------------
  //                     CLASS FUNCTIONS -- DO NOT OVERRIDE
  // --------------------------------------------------------------------------
  /**
   * Sets the URL path for the resource being called.
   *
   * @param $path
   *   An array containing the elements of the URL path. Each level of the
   *   URL appears in a separate element of the array. The service type and
   *   version are automatically removed from the array. For example, a
   *   URL of the type http://localhost/web-services/content/v0.1/Gene/sequence
   *   will result in a $path array containing the following:
   *   @code
   *     array(
   *       'Gene',
   *       'sequence',
   *     );
   *   @endcode
   *
   * @param unknown $path
   */
  public function setPath($path) {
    $this->path = $path;
  }
  /**
   * Sets the parameters for the resource.
   *
   * @param $params
   *   The set of paramters provided to the sesrvice. These are the values
   *   that would occur in a URL after the question mark in an HTTP GET or
   *   the data items of an HTTP POST.
   */
  public function setParams($params) {
    $this->params = $params;
  }

  /**
   * Retrieves the version number for this web service.
   *
   * Each web service must have version number built into the name of the
   * class. The version number appears at the end of the class name, begins
   * with a lower-case 'v' and is followed by two numbers (major and minor) that
   * are separated by an underscore.  This function identifies the version
   * from the class name and returns it here in a human-readable format.
   *
   * @param $sanitize
   *   Set to TRUE to convert the period to underscore.
   *
   * @return
   *   The version number for this web service.
   */
  public function getVersion($sanitize = FALSE) {

    $class = get_class($this);
    $major_version = '';
    $minor_version = '';

    if (preg_match('/v(\d+)_(\d+)$/', $class, $matches)) {
      $major_version = $matches[1];
      $minor_version = $matches[2];
      return 'v' . $major_version . '.' . $minor_version;
    }
    return '';
  }


  /**
   * Retrieves the context section of the response.
   *
   * The JSON-LD response constists of two sections the '@context' section
   * and the data section.  This function only returns the context section
   * of the response.
   *
   * @return
   *   An associative array containing the context section of the response.
   */
  public function getContext() {
    return $this->resource->getContext();
  }



  /**
   * Returns the full web service response.
   *
   * The response includes both the @context and data sections of the
   * JSON-LD response.
   *
   * @return
   *   An associative array containing that can be converted to JSON.
   */
  public function getResponse() {

    $context = $this->resource ? $this->resource->getContext() : array();
    $type = $this->resource ? $this->resource->getType() : 'unknown';
    $json_ld = array(
      '@context' => $context,
      '@id' => '',
      '@type' => $type,
    );
    $data = $this->getData();
    return array_merge($json_ld, $data);
  }

  /**
   * Retreives the service URL for this service.
   */
  public function getServicePath() {
    $class = get_class($this);
    $version = $this->getVersion();
    $type = $class::$type;
    return $this->base_path . '/' . $type . '/' . $version;
  }

  /**
   * Retrieves the data section of the response.
   *
   * The JSON-LD response constists of two sections the '@context' section
   * and the data section.  This function only returns the data section
   * of the response.
   *
   * @return
   *   An associative array containing the data section of the response.
   */
  public function getData() {

    if ($this->resource) {
      return $this->resource->getData();
    }
    return array();
  }

  /**
   * Sets the resource to be returned by this web service.
   *
   * @param $resource.
   *   An implementation of a TripalWebServiceResource.
   */
  public function setResource($resource) {
    // Make sure the $servcie provides is a TripalWebServcie class.
    if (!is_a($resource, 'TripalWebServiceResource')) {
      throw new Exception("Cannot add a new resource to this web service as it is not a TripalWebServiceResource.");
    }

    $this->resource = $resource;
  }



  /**
   * Set an error for the service.
   *
   * @param $message
   *   The error message to report.
   */
  public function setError($message) {
    $this->resource = new TripalWebServiceResource($this->base_path);
    $this->resource->setID('error');
    $this->resource->addContextItem('error', 'rdfs:error');
    $this->resource->setType('error');
    $this->resource->addProperty('error', $message);
  }

  /**
   * Retrieves an array contining the supported classes.
   *
   * Supported classe are resources provided by this web services and the
   * operations supported by those classes.
   *
   * @return
   *   An array of TripalWebServiceResource objects that follow the Hydra
   *   documentation for documenting supported classes.
   */
  public function getDocumentation() {
    return $this->documentation;
  }

  /**
   *  Defines an entity class for the web services.
   *
   *  A class defines a resource including information about its properties
   *  and the actions that can be performed.  Each class as a unique @id,
   *  title, type and description.  The $details parameter is used to provide
   *  this information.  Additionally, a resource may support Create, Read
   *  Update and Delete (CRUD) operations.  Those are defined using the
   *  $ops argument. Finally, resources may have properties (or fields). These
   *  properties should be defined using the $props arugment.
   *
   *  @param $details.
   *    An array of key/value pairs providing the details for the class. Valid
   *    keys include:
   *      - id: The unique IRI for this class.
   *      - name: a computer-readable name for this class (i.e. no spaces,
   *        no special characters).  This name is used to construct
   *        type identifiers for operations.
   *      - title:  The title for the resource that this Class represents.
   *      - description: (Optional). A description of the resource.
   *      - subClassOf: (Optional). If this class is a subclass of another
   *        class then the value should be the @id of the parent class. This
   *        defaults to hydra:Resource. If no subClass is desired, set it
   *        to NULL.
   *      - type: (Optional). Indicates the type of class. Defaults to
   *        hydra:Class
   *  @param $ops
   *    If the resource supports CRUD functionality then those functions should
   *    be defined using this argument.  This is an associative array with
   *    the following keys: GET, POST, PUT, DELETE. These keys, if provided,
   *    indicate that a resource of this type can be retrieved (GET),
   *    created (POST), updated (PUT) or deleted (DELETE).  The value for each
   *    key should be an associative array that supports the following keys:
   *      = type: the @id that determines the type of operation.  This type
   *        should be specific to the resource, and it need not be a term
   *        from a real vocabulary.  Use the '_:' prefix for the term. For
   *        example, for an 'Event' resource with a GET method, an appropriate
   *        type would be '_:event_retrieve'.
   *      - label: A label that describes the operation in the
   *        context of the resource.
   *      - description: A description for the operation.  Can be set to NULL
   *        for no description.
   *      - expects: The information expected by the Web API.
   *      - returns: The @id of a Class that will be returned by
   *        the operation. Set to NULL if there is no return value.
   *      - statusCodes: An array of status codes that could be returned when
   *        an error occurs.  Each element of the array is an associative
   *        array with two key/value pairs: 'code' and 'description'.  Set the
   *        'code' to be the HTTP code that can be returned on error and the
   *        'description' to an error message appropriate for the error. For
   *        example an HTTP 404 error means "Not Found".  You can sepecify this
   *        code and provide a description appropriate for the method and
   *        class.
   *  @param $props.
   *    Defines the list of properties that the resource provides.  This is an
   *    array of properties where each property is an associative array
   *    containing the following keys:
   *      - type:  The @id of the type of property. Alternatively, this can
   *        be an instance of a TripalWebServiceResource when the property
   *        must support operations such as a property of type hydra:Link.
   *      - title:  (Optional). The human-readable title of this property. If
   *        this key is absent then the title will be set to the term's title.
   *      - description:  (Optional). A short description of this property. If
   *        this key is absent then the description will be set to the term's
   *        description.
   *      - required:  Set to TRUE to indicate if this property is a required
   *        field when creating a new resource.
   *      - readable:  Set to TRUE to indicate that the client can retrieve the
   *        property's value?
   *        altered by an update.
   *      - writeable: Set to TRUE if the client can alter the value of the
   *        property.
   *      - domain: the @id of the rdfs:domain.
   *      - range:  the @id of the rdfs:range.
   */
  protected function addDocClass($details = array(), $ops = array(), $props = array()) {
    $supported_class = new TripalWebServiceResource($this->getServicePath());

    // Add the context which all classes will need
    $supported_class->addContextItem('description', 'rdfs:comment');
    $supported_class->addContextItem('subClassOf', 'hydra:subClassOf');
    $supported_class->addContextItem('description', 'rdfs:comment');
    $supported_class->addContextItem('label', 'rdfs:label');

    // Set the Class ID.
    $class_id = $details['id'];
    $supported_class->setID($class_id);

    // Set the class Type.
    if (array_key_exists('type', $details)) {
      $supported_class->setType($details['type']);
    }
    else {
      $supported_class->setType('hydra:Class');
    }

    // Set title and description.
    $supported_class->addProperty('hydra:title', $details['title']);
    $supported_class->addProperty('hydra:description', array_key_exists('description', $details) ? $details['description'] : NULL);

    // Set the sub class.
    if (array_key_exists('subClassOf', $details)) {
      if ($details['subClassOf']) {
        $supported_class->addProperty('subClassOf', $details['subClassOf']);
      }
    }
    else {
      $supported_class->addProperty('subClassOf', 'hydra:Resource');
    }

    // Now add the supported operations.
    $class_ops = array();
    foreach ($ops as $op => $op_details) {
      $class_ops[] = $this->generateDocClassOp($supported_class, $op, $op_details);
    }
    $supported_class->addContextItem('supportedOperation', 'hydra:supportedOperation');
    $supported_class->addProperty('supportedOperation', $class_ops);

    // Now add in the supported proprerties.
    $class_props = array();
    foreach ($props as $prop) {
      $class_props[] = $this->generateDocClassProp($supported_class, $prop);
    }
    $supported_class->addContextItem('supportedProperty', 'hydra:supportedProperty');
    $supported_class->addProperty('supportedProperty', $class_props);

    $this->documentation[] = $supported_class;
  }

  /**
   * A helper function for the addClass() function for generating a property.
   */
  private function generateDocClassProp($supported_class, $prop) {
    $supported_class->addContextItem('property', array(
      "@id" => "hydra:property",
      "@type" => "@id"
    ));
    $supported_class->addContextItem('domain', array(
      "@id" => "rdfs:domain",
      "@type" => "@id"
    ));
    $supported_class->addContextItem('range', array(
      "@id" => "rdfs:range",
      "@type" => "@id"
    ));
    $supported_class->addContextItem('readable', 'hydra:readable');
    $supported_class->addContextItem('writeable', 'hydra:writeable');
    $supported_class->addContextItem('required', 'hydra:required');
    $class_prop = array(
      'property' => $prop['type'],
      'hydra:title' => $prop['title'],
      'hydra:description' => array_key_exists('description', $prop) ? $prop['description'] : NULL,
      'required' => array_key_exists('required', $prop) ? $prop['required'] : NULL,
      'readable' => array_key_exists('readonly', $prop) ? $prop['readonly'] : NULL,
      'writeable' => array_key_exists('writeonly', $prop) ? $prop['writeonly'] : NULL,
    );
    if (array_key_exists('domain', $prop)) {
      $class_prop['domain'] = $prop['domain'];
    }
    if (array_key_exists('range', $prop)) {
      $class_prop['range'] = $prop['range'];
    }
    if (array_key_exists('operations', $prop)) {
      $class_prop['supportedOperation'] = array();
      foreach ($prop['operations'] as $op => $op_details) {
        $class_prop['supportedOperation'][] = $this->generateOp($supported_class, $op, $op_details);
      }
    }
    return $class_prop;
  }
  /**
   * A helper function for the addClass() function for generating an operation.
   */
  private function generateDocClassOp($supported_class, $op, $op_details) {

    if ($op != 'GET' and $op != 'PUT' and $op != 'DELETE' and $op != 'POST') {
      throw new Exception(t('The method, @method, provided to the TripalWebService::addClass function is not an oppropriate operations.', array('@method' => $op)));
    }

    if (!array_key_exists('type', $op_details)) {
      throw new Exception(t('Please provide a type in the operations array passed to the TripalWebService::addClass() function: @details', array('@details' => print_r($op_details, TRUE))));
    }
    if (!array_key_exists('label', $op_details)) {
      throw new Exception(t('Please provide a label in the operations array passed to the TripalWebService::addClass() function: @details', array('@details' => print_r($op_details, TRUE))));
    }

    $class_op = new TripalWebServiceResource($this->base_path);
    $class_op->setID($op_details['type']);
    switch($op) {
      case 'GET':
        $class_op->setType('hydra:Operation');
        break;
      case 'POST':
        $class_op->setType('http://schema.org/AddAction');
        break;
      case 'DELETE':
        $class_op->setType('http://schema.org/DeleteAction');
        break;
      case 'PUT':
        $class_op->setType('http://schema.org/UpdateAction');
        break;
    }

    $class_op->addContextItem('method', 'hydra:method');
    $class_op->addContextItem('label', 'rdfs:label');
    $class_op->addContextItem('description', 'rdfs:comment');
    $class_op->addContextItem('expects', array(
      "@id" => "hydra:expects",
      "@type" => "@id"
    ));
    $class_op->addContextItem('returns', array(
      "@id" => "hydra:returns",
      "@type" => "@id"
    ));
    $class_op->addContextItem('statusCodes', 'hydra:statusCodes');
    $class_op->addContextItem('code', 'hydra:statusCode');

    $class_op->addProperty('method', $op);
    $class_op->addProperty('label', array_key_exists('label', $op_details) ? $op_details['label'] : 'Retrieves an instance of this resource');
    $class_op->addProperty('description', array_key_exists('description', $op_details) ? $op_details['description'] : NULL);
    $status_codes = array_key_exists('statusCodes', $op_details) ? $op_details['statusCodes'] : array();
    foreach ($status_codes as $code) {
      if (array_key_exists('code', $code) and array_key_exists('description', $code)) {
        $class_op->addProperty('statusCodes', $code);
      }
      else {
        throw new Exception(t('The status code provided to TripalWebService::addClass function is improperly formatted @code.', array('@code' => print_r($code, TRUE))));
      }
    }
    if (count($status_codes) == 0) {
      $class_op->addProperty('statusCodes', array());
    }
    $class_op->addProperty('expects', array_key_exists('expects', $op_details) ? $op_details['expects'] : NULL);
    $class_op->addProperty('returns', array_key_exists('returns', $op_details) ? $op_details['returns'] : ' "http://www.w3.org/2002/07/owl#Nothing",');

    return $class_op;
  }

  /**
   * Converts a term array into an value appropriate for an @id or @type.
   *
   * @param $term
   *   The term array.
   * @param $santize
   *   An array of keywords indicating how to santize the key.  By default,
   *   no sanitizing occurs.  The two valid types are 'lowercase', and 'spacing'
   *   where 'lowercase' converts the term name to all lowercase and
   *   'spacing' replaces any spaces with underscores.
   *
   * @return
   *   The id (the term name but with spaces replaced with underscores).
   */
  protected function getContextTerm($term, $sanitize = array()) {
    if (!$term) {
      $backtrace = debug_backtrace();
      throw new Exception('getContextTerm: Please provide a non NUll or non empty $term.');

    }
    if (!$term['name']) {
      throw new Exception('getContextTerm: The provided term does not have a name: ' . print_r($term, TRUE));
    }

    $key = $term['name'];
    $key_adj = $key;
    if (in_array('spacing', $sanitize)) {
      $key_adj = preg_replace('/ /', '_', $key_adj);
    }
    if (in_array('lowercase', $sanitize)) {
      $key_adj = strtolower($key_adj);
    }
    return $key_adj;
  }
  /**
   * Adds a term to the '@context' section for a given resource.
   *
   * @param $resource
   *   A TripalWebServiceResource instance.
   * @param $term
   *   The term array.
   * @param $santize
   *   An array of keywords indicating how to santize the key.  By default,
   *   no sanitizing occurs.  The two valid types are 'lowercase', and 'spacing'
   *   where 'lowercase' converts the term name to all lowercase and
   *   'spacing' replaces any spaces with underscores.
   * @return
   *   The id (the term name but with spaces replaced with underscores).
   */
  protected function addContextTerm($resource, $term, $sanitize = array()) {
    if (!is_a($resource, 'TripalWebServiceResource')) {
      throw new Exception('addContextTerm: Please provide a $resource of type TripalWebServiceResource.');
    }

    if (!$term) {
      $backtrace = debug_backtrace();
      throw new Exception('addContextTerm: Please provide a non NUll or non empty $term.');

    }
    if (!$term['name']) {
      throw new Exception('addContextTerm: The provided term does not have a name: ' . print_r($term, TRUE));
    }

    // Make sure the vocab is present
    $vocab = $term['vocabulary'];
    $this->addContextVocab($resource, $vocab);

    // Sanitize the term key
    $key_adj = $this->getContextTerm($term, $sanitize);

    // Create the compact IRI
    $compact_iri = $vocab['short_name'] . ':' . $term['accession'];

    // If the full naming is indicated in the service parameters then
    // set the full name of the keys to include the vocab short name.
    if (array_key_exists('full_keys', $this->params)) {
      //$key_adj = $vocab['short_name'] . ':' . $key_adj;
    }

    $iri = $term['url'];

    $resource->addContextItem($key_adj, $compact_iri);
    $resource->addContextItem($compact_iri, $iri);

    return $key_adj;
  }

  /**
   * Adds a vocabulary to the '@context' section for a given resource.
   *
   * @param $resource
   *   A TripalWebServiceResource instance.
   * @param $vocab
   *   The vocabulary array.
   */
  protected function addContextVocab($resource, $vocab) {

    if (!is_a($resource, 'TripalWebServiceResource')) {
      throw new Exception('addContextVocab: Please provide a $resource of type TripalWebServiceResource.');
    }

    $key = $vocab['short_name'];
    // The URL here should be the URL prefix not the database home
    // page.  But unfortunately, the URL prefix can't be guaranteed to be
    // a true prefix. Not all databases place by the rules.  For this reason,
    // we can never use JSON-LD compact IRIs. :-(
    $iri = $vocab['url'];
    $resource->addContextItem($key, $iri);
  }

  /**
   * Adds a key/value property to the given resource.
   *
   * @param $resource
   *   A TripalWebServiceResource instance.
   * @param $term
   *   The term array for the key.
   * @param $value
   *   The value to add.
   * @param $santize
   *   An array of keywords indicating how to santize the key.  By default,
   *   no sanitizing occurs.  The two valid types are 'lowercase', and 'spacing'
   *   where 'lowercase' converts the term name to all lowercase and
   *   'spacing' replaces any spaces with underscores.
   * @return $key
   *   The key (the term name but with spaces replaced with underscores).
   */
  public function addResourceProperty($resource, $term, $value, $sanitize = array()) {
    if (!is_a($resource, 'TripalWebServiceResource')) {
      throw new Exception('addProperty: Please provide a $resource of type TripalWebServiceResource.');
    }

    // First add the term
    $key = $this->addContextTerm($resource, $term, $sanitize);

    // Then add the property.
    $resource->addProperty($key, $value);
  }
  /**
   * Sets the type for the given resource.
   *
   * The type exist in the context of the web service.
   *
   * @param $resource
   *   A TripalWebServiceResource instance.
   * @param $type
   *   The type
   * @param $santize
   *   An array of keywords indicating how to santize the key.  By default,
   *   no sanitizing occurs.  The two valid types are 'lowercase', and 'spacing'
   *   where 'lowercase' converts the term name to all lowercase and
   *   'spacing' replaces any spaces with underscores.
   */
  public function setResourceType($resource, $term, $sanitize = array('spacing')) {

    if (!is_a($resource, 'TripalWebServiceResource')) {
      throw new Exception('addProperty: Please provide a $resource of type TripalWebServiceResource.');
    }
    // First add the term
    $key = $this->addContextTerm($resource, $term, $sanitize);

    // Then set the type
    $resource->setType($key);
  }
}