EDIT

<?php

// $Id: cdm_api.php 1012 2007-12-05 17:58:45Z a.kohlbecker $

/**

 * @file

 * Functions which are required or useful when accessing and processing CDM Data Store Webservices

 * 

 * Naming conventions:

 * ----------------------

 * 

 *  - all webservice access methods are prefixed with cdm_ws

 * 

 *

 * Copyright (C) 2007 EDIT

 * European Distributed Institute of Taxonomy 

 * http://www.e-taxonomy.eu

 * 

 * The contents of this file are subject to the Mozilla Public License Version 1.1

 * See LICENSE.TXT at the top of this package for the full license terms.

 */

require_once ('xml2json.php');

// Taxon Relationship Types

define('UUID_TAXONOMICALLY_INCLUDED_IN',  'd13fecdf-eb44-4dd7-9244-26679c05df1c');

define('UUID_MISAPPLIED_NAME_FOR',  '1ed87175-59dd-437e-959e-0d71583d8417');

define('UUID_INVALID_DESIGNATION_FOR',  '605b1d01-f2b1-4544-b2e0-6f08def3d6ed');

define('UUID_CONTRADICTION',  'a8f03491-2ad6-4fae-a04c-2a4c117a2e9b');

define('UUID_CONGRUENT_TO',  '60974c98-64ab-4574-bb5c-c110f6db634d');

define('UUID_INCLUDES',  '0501c385-cab1-4fbe-b945-fc747419bb13');

define('UUID_OVERLAPS',  '2046a0fd-4fd6-45a1-b707-2b91547f3ec7');

define('UUID_EXCLUDES',  '4535a63c-4a3f-4d69-9350-7bf02e2c23be');

define('UUID_DOES_NOT_EXCLUDE',  '0e5099bb-87c0-400e-abdc-bcfed5b5eece');

define('UUID_DOES_NOT_OVERLAP',  'ecd2382b-3d94-4169-9dd2-2c4ea1d24605');

define('UUID_NOT_INCLUDED_IN',  '89dffa4e-e004-4d42-b0d1-ae1827529e43');

define('UUID_NOT_CONGRUENT_TO',  '6c16c33b-cfc5-4a00-92bd-a9f9e448f389');

// Synonym Relationship Types

define('UUID_SYNONYM_OF', '1afa5429-095a-48da-8877-836fa4fe709e');

define('UUID_PRO_PARTE_SYNONYM_OF', '130b752d-2eff-4a62-a132-104ed8d13e5e');

define('UUID_PARTIAL_SYNONYM_OF', '8b0d1d34-cc00-47cb-999d-b67f98d1af6e');

define('UUID_HOMOTYPIC_SYNONYM_OF', '294313a9-5617-4ed5-ae2d-c57599907cb2');

define('UUID_HETEROTYPIC_SYNONYM_OF', '4c1e2c59-ca55-41ac-9a82-676894976084');

/**

 * Converts an array of TagedText items into a sequence of corresponding html tags whereas 

 * each item will provided with a class attribute which set to the key of the TaggedText item.

 * 

 * @param array $taggedtxt

 * @param String $tag

 * @param String $glue the string by which the chained text tokens are concatenated together. 

 *       Default is a blak character

 * @return String of HTML 

 */

function cdm_taggedtext2html(array &$taggedtxt, $tag = 'span', $glue = ' '){

  $out = '';

   foreach($taggedtxt as $tt){

     $out .= (strlen($out) > 0 ? $glue : '').'<'.$tag.' class="'.$tt->tag.'">'.$tt->text.'</'.$tag.'>';

   }

   return $out;

}

/**

 * Finds the text tagged with $tagname in an array of taggedText instances

 *

 * @param array $taggedtxt

 * @param string $tagname

 * @return the text mapped by $tagname or an empty string

 */

function cdm_taggedtext_value(array &$taggedtxt = array(), $tagname){

  foreach($taggedtxt as $tagtxt){

    if($tagtxt->tag == $tagname)

    return $tagtxt->text;

  }

  return '';

}

/**

 * Searches the appay of LocalisedTermTO instances for an entry mapped with the language

 * specified as parameter $language if existing. If not the term mapped with the $defauklt_language 

 * is returend otherwise the first term in $localised_terms is returned or fale if 

 * $localised_terms is empty. 

 * 

 *

 * @param array $localised_terms

 * @param string $language

 * @param string $default_language

 * @return string

 */

function cdm_get_localised_term($localised_terms, $language, $default_language = 'en'){

  $default_term = (count($localised_terms) > 0 ? $localised_terms[0]->term : '') ;

  foreach($localised_terms as $lt){

    if($lt->language == $language){

      return $lt->term;

    }

    if($lt->language == $default_language){

      $default_term = $lt->term;

    }

  }

  return $default_term;

}

/**

 * Enter description here...

 *

 * @param unknown_type $uuid

 */

function cdm_localized_term_is($uuid){

}

/**

 * Produces a path to a static web service stub out of a cdm web service path. 

 * These stubs are object serialisations stored in files whereas the filename

 * consists of the service name and of a 

 * encoded version of the request query parameters

 *

 * @param string $path

 * @param string $fileextension

 * @return string

 */

function cdm_encode_stub($path, $fileextension){

  return variable_get('cdm_webservice_type', 'xml').'/'.str_replace('&',',', str_replace('?',';',$path)).'.'.$fileextension;

}

/**

 * Decodes a path to a static web service stub to turn it into a path 

 * suitable for a cdm web service

 *

 * @param string $path

 * @return string

 */

function cdm_decode_stub($path){

  // remove fileextension

  $path = substr_replace($path, '', strrpos($path, '.'));

  return str_replace(',','&', str_replace(';','?',$path));

}

/**

 * Enter description here...

 *

 * @param unknown_type $file

 * @param unknown_type $parameters

 * @return unknown

 */

function cdm_compose_url($file, $parameters = array()){

  $pstr = '';

  foreach($parameters as $key=>$value){

    $pstr .= ( strlen($pstr) == 0 ? '?' : '&').$key.'='.urlencode($value);

  }

  $file .= $pstr;

  if(variable_get('cdm_webservice_isStub', 0)){

    $file = cdm_encode_stub($file, variable_get('cdm_webservice_type', 'json'));

  }

  $url = variable_get('cdm_webservice_url', '').$file; 

  return $url;

}

/**

 * Return string content from a remote file

 * 

 * @param string $url

 * @return string

 * 

 * @author Luiz Miguel Axcar (lmaxcar@yahoo.com.br)

*/

function _get_content_curl($url)

{

    $ch = curl_init();

    curl_setopt ($ch, CURLOPT_URL, $url);

    curl_setopt ($ch, CURLOPT_HEADER, 0);

    ob_start();

    curl_exec ($ch);

    if(curl_errno($ch)){

      watchdog('CDM', curl_error($ch).' URL: '.$url, WATCHDOG_ERROR);

    }

    curl_close ($ch);

    $string = ob_get_contents();

    ob_end_clean();

    return $string;    

}

function _get_content_fsockopen($url){

  //FIXME implement get_content_fsockopen($url);

}

function get_content($url){

  /* FIXME: all requests must be sent with the correct request headers:

   *  

   *  - Accept: application/json, text/xml, ...

   *  - Accept-Language: en, de, ....

   *  - Accept-Encoding: UTF8

   * 

   */

  if(function_exists('curl_init')){

    // use the CURL lib if installed it is supposed to be 20x faster

    return _get_content_curl($url);

  } else {

    return _get_content_fsockopen($url);

  }

}

/**

 * Implementation of hook_menu()

 */

function cdm_api_menu($may_cache) {

  $items = array();

  if ($may_cache) {

   $items[] = array(

      'path' => 'cdm_api/proxy',

      'callback' => 'proxy_content',

      'access' => true,

      'type' => MENU_CALLBACK,

      );

  }

  return $items;

}

/**

 * Implementation of hook_requirements()

 */

function cdm_api_requirements() {

  $requirements['cdm_api'] = array(

    'title' => t('CDM API')

  );

  if( function_exists('curl_init') ){

    $requirements['cdm_api']['description'] = ''; // description below title is not jet in use 

    $requirements['cdm_api']['value'] =  'CURL php extension is available.';

  } else {

    $requirements['cdm_api']['value'] =  'CURL php extension is missing.';

  }

  //FIXME: once _get_content_fsockopen is implemented change  severity to  REQUIREMENT_WARNING,

  $requirements['cdm_api']['severity'] =  (function_exists('curl_init') ? REQUIREMENT_OK : REQUIREMENT_ERROR);

  return $requirements;

}

function proxy_content($url, $theme = null){

  $data = get_content(urldecode($url));

  if(!$theme){

    print $data;

  } else {

    print theme($theme, cdm_load_obj($data));

  }

}

function cdm_load_obj($datastr){

  // if the webservice deilvers XML convert it into json

  if(variable_get('cdm_webservice_type', 'xml') == 'xml'){

    $datastr = xml2json::transformXmlStringToJson($datastr);  

  }

  $json = new Services_JSON();

  $obj = $json->decode($datastr);

  return $obj->root;

}

/**

 * Loads the XML or JSON response for the given url from the CDM Data Store Webservice.

 * The XML is turned into a object which is returned. In case of an error a 

 * appropriate watchdog message is generated and the function returns false.

 * 

 * @param String $url the relative url of the web service call. 

 *        Relative means relative to the web service base url which is stored in cdm_webservice_url

 * @return An object or false

 */

function cdm_ws_load($url){

  $datastr = get_content($url);

  if( !($obj = cdm_load_obj($datastr)) ){

    $backtrace = debug_backtrace();

    watchdog('CDM', 'cdm_ws_load() - '.$url.' failed to load', WATCHDOG_ERROR);

  }

  return $obj;

}

/* ------------------------------------------------------------------------- */

/**

 * Enter description here...

 *

 * @return unknown

 */

function cdm_ws(){

  $args = func_get_args();

  $method = array_shift($args);

  $url_function = 'cdm_ws_'.$method.'_url';

  if(function_exists($url_function)){

    $url = call_user_func_array($url_function, $args);

    return cdm_ws_load($url);

  }

  watchdog("cdm-api", 'cdm_ws() - invalid web service method call: "'.$method.'" dues not exist.', WATCHDOG_ERROR);

  return false;

}

// -------- whatis

function cdm_ws_whatis_url($uuid){

  return cdm_compose_url("whatis", array('uuid'=>$uuid));

}

/**cdm_ws_whatis

 * The whatis service returns the type 

 * i.e. DTO class name and simplename & cdm class name and simplename of the instance referenced by the $uuid parameter. 

 * 

 *

 * @param unknown_type $uuid

 * @return false if the cdm store contains no matching instance. 

 * An associative array with the following key-value pairs:

 *   - 'cdmName':       name of the cdm class as returned by Class.getName(), e.g. eu.etaxonomy.cdm.model.taxon.Taxon

 *   - 'cdmSimpleName': simple name of the cdm class as returned by Class.getSimpleName(), e.g. Taxon

 *   - 'dtoName':       name of the DTO class as returned by Class.getName(), e.g. eu.etaxonomy.cdm.dto.TaxonTO

 *   - 'dtoSimpleName': simple name of the TDO class as returned by Class.getSimpleName(), e.g. TaxonTO

 */

function cdm_ws_whatis($uuid){

  $url = cdm_ws_whatis_url($uuid);

  return cdm_ws_load($url);

}

// -------- get_name

function cdm_ws_get_name_url($uuid){

  return cdm_compose_url("name", array('uuid'=>$uuid));

}

/**

 * load a name from the CDM Webservice

 *

 * @param String $uuid

 * @return a NameTO instance or false 

 */

function cdm_ws_get_name($uuid){

  $uri = cdm_ws_get_name_url($uuid);

  $obj = cdm_ws_load($url);

  return $obj;

}

// -------- name_list

function cdm_ws_name_list_url($beginsWith, $page, $onlyAccepted = false, $pagesize = 20){

  //TODO: fully implement

  return cdm_compose_url('namelist', array(

                'beginswith' =>$beginsWith,

                'page'       =>$page,

              ) 

          );

}

/**

 * load a list of names from the CDM Webservice

 *

 * cdm_ws_name_list($beginsWith, $page, $onlyAccepted, $_SESSION['cdm']['namelist_pagesize']);

 */

function cdm_ws_name_list($beginsWith, $page, $onlyAccepted = false, $pagesize = 20){

    //TODO: fully implement

   $url = cdm_ws_name_list_url($beginsWith, $page, $onlyAccepted = false, $pagesize = 20);

   $obj = cdm_ws_load($url);

   return $obj;

}

// -------- get_reference

function cdm_ws_get_reference_url($uuid){

   return cdm_compose_url('reference', array('uuid'=>$uuid));

}

/**

 * Enter description here...

 *

 * @param String $uuid of the requested reference

 * @return unknown

 */

function cdm_ws_get_reference($uuid){

   $url = cdm_ws_get_reference_url($uuid);

   $obj = cdm_ws_load($url);

   return $obj;

}

// -------- get_taxon

function cdm_ws_get_taxon_url($uuid){

  return cdm_compose_url('taxon', array('uuid'=>$uuid));

}

/**

 * Enter description here...

 *

 * @param String $taxon_uuid UUID of the requested Taxon

 * @return a TaxonTO objetct

 */

function cdm_ws_get_taxon($taxon_uuid){

   $url = cdm_ws_get_taxon_url($taxon_uuid);

   return cdm_ws_load($url);

}

// -------- get_typedesignation

function cdm_ws_get_typedesignations_url($name_uuid){

  return cdm_compose_url('type', array('uuid'=>$name_uuid));

}

function cdm_ws_get_typedesignations($name_uuid){

  $url = cdm_ws_get_typedesignations_url($name_uuid);

  return cdm_ws_load($url);

}

// -------- get_accepted

function cdm_ws_get_accepted_url($taxon_uuid){

  return cdm_compose_url('accepted', array('uuid'=>$taxon_uuid));

}

function cdm_ws_get_accepted($taxon_uuid){

  $url = cdm_ws_get_accepted_url($taxon_uuid);

  return cdm_ws_load($url);

}

// -------- Taxon tree ws functions

/**

 * treenode_parents returns an array of the parent TreeNodes in descending order.

 * The TreeNode referenced by the parameter $taxon_uuid is included as last element

 *

 * @param String $taxon_uuid

 * @return array

 */

function cdm_ws_get_treenode_parents_url($taxon_uuid){

  return cdm_compose_url('treenode_parents', array('uuid'=>$taxon_uuid));

}

function cdm_ws_get_treenode_children_url($taxon_uuid = ''){

  return cdm_compose_url('treenode_children', array('uuid'=>$taxon_uuid));

}