<?php

/* RDFInt.php - RDF Interfaces for PHP
 * Copyright 2011 netlabs.org
 * Author: Christian Langanke, Adrian Gschwend
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

namespace rdfa;

/**
 *  \class   Projection
 *  \brief   This class implements a projection as described  in the RDF API and RDFa API specs of W3C.
 *  \details A projection relates to a specific subject of RDF data parsed by an instance of
 *           the rdfa::Data class and is to be created by the projection API methods this class only.
 *  \note   Non-standard methods are marked as library specific extensions
 *          and the methodname is prepended by a single underscore character.
 *          For further information on differences to the W3C specifications,
 *          see the section
 *          \htmllink{page_w3cspecs.html,W3C Specifications Overview and Library Compatibility}
 *  \author  Christian Langanke
 *  \author  Adrian Gschwend
 *  \date    2011
 */
class Projection {

  /**
   * Version of the class
   */
  const version = '1.0.0';
  /**
   * Name of the fDebug context
   */
  const debugcontext = 'RDFA_PROJECTION';

  private $debugger;
  private $rdfaData;
  private $subject;

  // ---------------------------------------

  /**
   * Creates a Projection instance from a Data instance, reflecting a given subject in the triple data.
   *
   * \param rdfaData     instance of rdfa::Data holding the graph of the subject
   * \param subject      Subject of the projection
   * \param template     Associative array( URI/CURIE => membername) as a template to be applied to the projection object
   *
   * \exception Exception The parameter rdfaData is not of object rdfa::Data
   *
   * \note A projection is to be created by the following methods only:
   * - rdfa::Data::getProjection()
   * - rdfa::Data::getProjections()
   * - rdfa::Data::query()
   */
  public function __construct( $rdfaData, $subject, $template) {

    // setup debugger
    $this->debugger = \fDebug::getInstance();

    // check for required class
    if ((!is_object( $rdfaData)) ||
        ('\\' . get_class(  $rdfaData) != '\\rdfa\\Data'))
      throw new \Exception( 'Invalid Parameter: $rdfdata is not object of class \rdfa\Data.');

    // initialize
    $this->rdfaData = $rdfaData;
    $this->subject = $subject;

    $debugmessage = "Creating projection for subject: $subject";

    // create public members from template
    if (($template != Null) && (is_array( $template))) {
      $debugmessage .= "\nApplying template:\n";
      foreach ( $template as $key => $uri) {
        $value =  $this->get( $uri);
        if ($value != false) {
          $this->$key = $value;
          $debugmessage .= "$key=$value\n";
        } else {
          $debugmessage .= "### not found: $key\n";
        }
      }
    }

    $this->debugger->sendMessage( $debugmessage,
                                  self::debugcontext);

  } // public function __construct

  // --------------------------------------------------------

  /**
   * Gets properties of the subject of the projection.
   *
   * \retval array List of properties
   */
  public function getProperties() {
    return $this->rdfaData->getProperties( $this->subject);
  } // public function getProperties

  // --------------------------------------------------------

  /**
   * Gets an associative list of unique properties of the projection
   * with their values.
   *
   * \retval array  Associative list of unqique properties and their values
   *
   * \note
   * - All non-unique properties are \c NOT returned !
   * - This method is a library specific extension to the RDF API and RDFa API
   */
  public function _getUniqueProperties() {
    return $this->rdfaData->_getUniqueProperties( $this->subject);
  } // public function _getUniqueProperties

  // --------------------------------------------------------

  /**
   * Gets the subject of of the subject of the projection.
   *
   * \retval string  Subject of the property
   */
  public function getSubject() {
    return $this->subject;
  } // public function getSubject

  // --------------------------------------------------------

  /**
   * Gets the first available value of a given property.
   *
   * \param  property   Property to retrieve the first value of#
   * \retval string     First value of the property
   */

  public function get( $property) {
    return $this->rdfaData->_getFirstValue( $this->subject, $property);
  } // public function get

  // --------------------------------------------------------

  /**
   * Gets a list of all available values of a given property.
   *
   * \param property   Property to retrieve all values of
   */

  public function getAll( $property) {
    return $this->rdfaData->getValues( $this->subject, $property);
  } // public function getAll

  // --------------------------------------------------------

  /**
   * Sets a property value.
   *
   * \param property  Property to be added
   * \param value     Value to be set for the property
   * \param type      The type of the value, either 'uri', 'literal' or 'bnode'
   *                  (case-insensitive). Specifying the first character is sufficient.
   *                  If not specified, strings starting with 'http://' are taken as a URI,
   *                  strings starting with '_:' as a blank node, otherwise as a literal
   * \retval rdfa::Projection Success
   * \retval boolean   false: invalid value type specified
   *
   * \see rdfa::Data::_setValue
   *
   * \note
   * - This method is a library specific extension to the RDFa API
   * - The parameter type is a library specific extension to the RDF API
   */

  public function set( $property, $value, $type = NULL) {
    
    $ret = $this->rdfaData->_setValue($this->subject, $property, $value, $type );    
    
    if($ret)
      return $this;
    else
      return false;
  }

} // class Projection

?>