Project

General

Profile

Download (91 KB) Statistics
| Branch: | Tag: | Revision:
1
<?php
2
  /**
3
   * @file
4
   * Required or useful functions for using CDM Data Store Webservices.
5
   *
6
   * Naming conventions:
7
   * ----------------------
8
   * - All webservice access methods are prefixed with cdm_ws.
9
   *
10
   * @copyright
11
   *   (C) 2007-2012 EDIT
12
   *   European Distributed Institute of Taxonomy
13
   *   http://www.e-taxonomy.eu
14
   *
15
   *   The contents of this module are subject to the Mozilla
16
   *   Public License Version 1.1.
17
   * @see http://www.mozilla.org/MPL/MPL-1.1.html
18
   *
19
   * @author
20
   *   - Andreas Kohlbecker <a.kohlbecker@BGBM.org>
21
   *   - Wouter Addink <w.addink@eti.uva.nl> (migration from Drupal 5 to Drupal7)
22
   */
23

    
24
  module_load_include('php', 'cdm_api', 'xml2json');
25
  module_load_include('php', 'cdm_api', 'commons');
26
  module_load_include('php', 'cdm_api', 'uuids');
27
  module_load_include('php', 'cdm_api', 'enums');
28
  module_load_include('php', 'cdm_api', 'webservice_uris');
29
  module_load_include('php', 'cdm_api', 'cdm_node');
30
  module_load_include('inc', 'cdm_api', 'tagged_text');
31

    
32
  /**
33
   * Timeout used to override the default of 30 seconds
34
   * in @see drupal_http_request()
35
   *
36
   * @var CDM_HTTP_REQUEST_TIMEOUT: A float representing the maximum number of seconds the function
37
   *     call may take
38
   */
39
  define('CDM_HTTP_REQUEST_TIMEOUT', 90.0);
40

    
41

    
42

    
43
/**
44
 * orderBy webservice query parameter value
45
 */
46
define('CDM_ORDER_BY_ID_ASC', 'BY_ID_ASC');
47

    
48
/**
49
 * orderBy webservice query parameter value
50
 */
51
define('CDM_ORDER_BY_ID_DESC', 'BY_ID_DESC');
52
/**
53
 * orderBy webservice query parameter value
54
 */
55
define('CDM_ORDER_BY_TITLE_CACHE_ASC', 'BY_TITLE_CACHE_ASC');
56
/**
57
 * orderBy webservice query parameter value
58
 */
59
define('CDM_ORDER_BY_TITLE_CACHE_DESC', 'BY_TITLE_CACHE_DESC');
60
/**
61
 * orderBy webservice query parameter value
62
 */
63
define('CDM_ORDER_BY_NOMENCLATURAL_ORDER_ASC', 'BY_NOMENCLATURAL_ORDER_ASC');
64
/**
65
 * orderBy webservice query parameter value
66
 */
67
define('CDM_ORDER_BY_NOMENCLATURAL_ORDER_DESC', 'BY_NOMENCLATURAL_ORDER_DESC');
68
/**
69
 * orderBy webservice query parameter value
70
 */
71
define('CDM_ORDER_BY_ORDER_INDEX_ASC', 'BY_ORDER_INDEX_ASC');
72
/**
73
 * orderBy webservice query parameter value
74
 */
75
define('CDM_ORDER_BY_ORDER_INDEX_DESC', 'BY_ORDER_INDEX_DESC');
76

    
77

    
78
/**
79
 * Implements hook_menu().
80
 */
81
function cdm_api_menu() {
82
  $items = array();
83

    
84
  // usage: url('cdm_api/proxy/'.urlencode($content_url)."/$theme");
85
  $items['cdm_api/proxy'] = array(
86
    'page callback' => 'proxy_content',
87
    'access arguments' => array(
88
      'access cdm content',
89
    ),
90
    'type' => MENU_CALLBACK,
91
  );
92

    
93
  $items['cdm_api/setvalue/session'] = array(
94
    'page callback' => 'setvalue_session',
95
    'access arguments' => array(
96
      'access cdm content',
97
    ),
98
    'type' => MENU_CALLBACK,
99
  );
100

    
101
  return $items;
102
}
103

    
104
/**
105
 * Implements hook_block_info().
106
 */
107
function cdm_api_block_info() {
108

    
109
  $block['cdm_ws_debug'] = array(
110
      "info" => t("CDM web service debug"),
111
      "cache" => DRUPAL_NO_CACHE
112
  );
113
  return $block;
114
}
115

    
116
/**
117
 * Implements hook_block_view().
118
 */
119
function cdm_api_block_view($delta) {
120
  switch ($delta) {
121
    case 'cdm_ws_debug':
122

    
123
    $cdm_ws_url = variable_get('cdm_webservice_url', '');
124

    
125
    $field_map = array(
126
        'ws_uri' => t('URI') . ' <code>(' . $cdm_ws_url .'...)</code>',
127
        'time' => t('Time'),
128
        'fetch_seconds' => t('Fetching [s]'),
129
        'parse_seconds' => t('Parsing [s]'),
130
        'size_kb' => t('Size [kb]'),
131
        'status' => t('Status'),
132
        'data_links' =>  t('Links'),
133
    );
134

    
135

    
136
    if (!isset($_SESSION['cdm']['ws_debug'])) {
137
      $_SESSION['cdm']['ws_debug'] = array();
138
    }
139

    
140
    $header = '<thead><tr><th>' . join('</th><th>' , array_values($field_map)) . '</th></thead>';
141
    $footer = '<tfoot><tr><th>' . join('</th><th>' , array_values($field_map)) . '</th></tfoot>';
142
    $rows = array();
143

    
144
    foreach ($_SESSION['cdm']['ws_debug'] as $data){
145

    
146
      $data = unserialize($data);
147

    
148
      // stip of webservice base url
149
      $data['ws_uri'] = str_replace($cdm_ws_url, '', $data['ws_uri']);
150
      if($data['method'] == 'POST'){
151
        $data['ws_uri'] = 'POST: ' . $data['ws_uri'] . '?' . $data['post_data'];
152
      }
153

    
154
      $cells = array();
155
      foreach ($field_map as $field => $label){
156
        $cells[] = '<td class="' . $field . '">' .  $data[$field] . '</td>';
157
      }
158
      $rows[] = '<tr class="' . $data['status']  . '">' . join('' , $cells). '</tr>';
159
    }
160
    // clear session again
161
    $_SESSION['cdm']['ws_debug'] = array();
162

    
163
    _add_js_ws_debug();
164

    
165
    $block['subject'] = ''; // no subject, title in content for having a defined element id
166
    // otherwise it would depend on the theme
167
    $block['content'] = array(
168
      '#markup' => '<h4 id="cdm-ws-debug-button">' . t('CDM Debug') . '</h4>'
169
        // cannot use theme_table() since table footer is not jet supported in D7
170
        . '<div id="cdm-ws-debug-table-container"><table id="cdm-ws-debug-table">'
171
        . $header
172
        . '<tbody>' . join('', $rows) . '</tbody>'
173
        . $footer
174
        . '</table></div>',
175
      '#attached' => array(
176
        'css' => array(
177
          drupal_get_path('module', 'cdm_dataportal') . '/cdm_dataportal_ws_debug.css'
178
        )
179
      )
180
    );
181
    return $block;
182
  }
183
}
184

    
185
/**
186
 * Implements hook_cron().
187
 *
188
 * Expire outdated cache entries.
189
 */
190
function cdm_api_cron() {
191
  cache_clear_all(NULL, 'cache_cdm_ws');
192
}
193

    
194
/**
195
 * Lists the classifications a taxon belongs to
196
 *
197
 * @param CDM type Taxon $taxon
198
 *   the taxon
199
 *
200
 * @return array
201
 *   aray of CDM instances of Type Classification
202
 */
203
function get_classifications_for_taxon($taxon) {
204

    
205
  return cdm_ws_get(CDM_WS_TAXON_CLASSIFICATIONS, $taxon->uuid);
206
}
207

    
208
/**
209
 * Returns the chosen FeatureTree to be used as FeatureTree for the taxon profile.
210
 *
211
 * The FeatureTree returned is the term tree one that has been set in the
212
 * dataportal settings (layout->taxon:profile).
213
 * When the chosen FeatureTree is not found in the database,
214
 * the standard feature tree (UUID_DEFAULT_FEATURETREE) will be returned.
215
 *
216
 * @return object
217
 *   A cdm TermTree object.
218
 */
219
function get_profile_feature_tree() {
220
  static $profile_featureTree;
221

    
222
  if($profile_featureTree == NULL) {
223
    $profile_featureTree = cdm_ws_get(
224
      CDM_WS_TERMTREE,
225
      variable_get(CDM_PROFILE_FEATURETREE_UUID, UUID_DEFAULT_FEATURETREE)
226
    );
227
    if (!$profile_featureTree) {
228
      $profile_featureTree = cdm_ws_get(CDM_WS_TERMTREE, UUID_DEFAULT_FEATURETREE);
229
    }
230
  }
231

    
232
  return $profile_featureTree;
233
}
234

    
235
/**
236
 * Returns the chosen TermTree to be used as FeatureTree for SpecimenDescriptions.
237
 *
238
 * The TermTree returned is the one that has been set in the
239
 * dataportal settings (layout->taxon:specimen).
240
 * When the chosen TermTree is not found in the database,
241
 * the standard term tree (UUID_DEFAULT_TERMTREE) will be returned.
242
 *
243
 * @return object
244
 *   A cdm TermTree object.
245
 */
246
function cdm_get_occurrence_featureTree() {
247
  static $occurrence_featureTree;
248

    
249
  if($occurrence_featureTree == NULL) {
250
    $occurrence_featureTree = cdm_ws_get(
251
      CDM_WS_TERMTREE,
252
      variable_get(CDM_OCCURRENCE_FEATURETREE_UUID, UUID_DEFAULT_FEATURETREE)
253
    );
254
    if (!$occurrence_featureTree) {
255
      $occurrence_featureTree = cdm_ws_get(CDM_WS_TERMTREE, UUID_DEFAULT_FEATURETREE);
256
    }
257
  }
258
  return $occurrence_featureTree;
259
}
260

    
261
/**
262
 * Returns the FeatureTree for structured descriptions
263
 *
264
 * The FeatureTree returned is the one that has been set in the
265
 * dataportal settings (layout->taxon:profile).
266
 * When the chosen FeatureTree is not found in the database,
267
 * the standard feature tree (UUID_DEFAULT_FEATURETREE) will be returned.
268
 *
269
 * @return mixed
270
 *   A cdm FeatureTree object.
271
 */
272
function get_structured_description_featureTree() {
273
  static $structured_description_featureTree;
274

    
275
  if($structured_description_featureTree == NULL) {
276
    $structured_description_featureTree = cdm_ws_get(
277
        CDM_WS_TERMTREE,
278
        variable_get(CDM_DATAPORTAL_STRUCTURED_DESCRIPTION_FEATURETREE_UUID, UUID_DEFAULT_FEATURETREE)
279
    );
280
    if (!$structured_description_featureTree) {
281
      $structured_description_featureTree = cdm_ws_get(
282
          CDM_WS_TERMTREE,
283
          UUID_DEFAULT_FEATURETREE
284
      );
285
    }
286
  }
287
  return $structured_description_featureTree;
288
}
289

    
290

    
291
/**
292
 * @todo Please document this function.
293
 * @see http://drupal.org/node/1354
294
 */
295
function set_last_taxon_page_tab($taxonPageTab) {
296
  $_SESSION['cdm']['taxon_page_tab'] = $taxonPageTab;
297
}
298

    
299
/**
300
 * @todo Please document this function.
301
 * @see http://drupal.org/node/1354
302
 */
303
function get_last_taxon_page_tab() {
304
  if (isset($_SESSION['cdm']['taxon_page_tab'])) {
305
    return $_SESSION['cdm']['taxon_page_tab'];
306
  }
307
  else {
308
    return FALSE;
309
  }
310
}
311

    
312
/**
313
 * NOTE: The cdm-library provides a very similar server side function. See
314
 * eu.etaxonomy.cdm.model.media.MediaUtils.filterAndOrderMediaRepresentations()
315
 *
316
 * @param object $media
317
 * @param array $mimeTypes
318
 *    an array of mimetypes in their order of preference. e.g:
319
 *    array('application/pdf', 'image/png', 'image/jpeg', 'image/gif', 'text/html')
320
 * @param int $width
321
 *    The width of the optimal image. If null, the method will return the representation with the biggest expansion
322
 * @param int $height
323
 *    The height of the optimal image. If null, the method will return the representation with the biggest expansion
324
 *
325
 * @return array
326
 *   An array with preferred media representations or else an empty array.
327
 */
328
function cdm_preferred_media_representations($media, array $mimeTypes, $width = NULL, $height = NULL) {
329
  $prefRepr = array();
330
  if (!isset($media->representations[0])) {
331
    return $prefRepr;
332
  }
333

    
334
  while (count($mimeTypes) > 0) {
335
    // getRepresentationByMimeType
336
    $mimeType = array_shift($mimeTypes);
337

    
338
    foreach ($media->representations as &$representation) {
339
      // If the mimetype is not known, try inferring it.
340
      if (!$representation->mimeType) {
341
        if (isset($representation->parts[0])) {
342
          $representation->mimeType = infer_mime_type($representation->parts[0]->uri);
343
        }
344
      }
345

    
346
      if ($representation->mimeType == $mimeType) {
347
        // Preferred mimetype found -> erase all remaining mimetypes
348
        // to end loop.
349
        $mimeTypes = array();
350
        $expansionDeltaSum = 0;
351
        $valid_parts_cnt = 0;
352
        // Look for part with the best matching size.
353
        foreach ($representation->parts as $part) {
354
          if (empty($part->uri)) {
355
            // skip part if URI is missing
356
            continue;
357
          }
358
          $valid_parts_cnt++;
359
          $expansionDelta = PHP_INT_MAX; // biggest delta for unknown sizes
360

    
361
          // determine the optimal size
362
          if (isset($part->width) && isset($part->height)) {
363
            $expansion = $part->width * $part->height;
364
            if ($width != null && $height != null) {
365
              $optimalExpansion = $height * $width;
366
            } else {
367
              $optimalExpansion = PHP_INT_MAX;
368
            }
369
            // determine the difference
370
            $expansionDelta = $expansion > $optimalExpansion ? $expansion - $optimalExpansion : $optimalExpansion - $expansion;
371
          }
372
          // sum up the expansionDeltas of all parts contained in the representation
373
          $expansionDeltaSum += $expansionDelta;
374
        }
375
        if($valid_parts_cnt > 0){
376
          $expansionDeltaSum = $expansionDeltaSum / $valid_parts_cnt;
377
          $prefRepr[$expansionDeltaSum] = $representation;
378
        }
379
      }
380
    }
381
  }
382
  // Sort the array so that the smallest key value is the first in the array
383
  ksort($prefRepr);
384
  return $prefRepr;
385
}
386

    
387
/**
388
 * Infers the mime type of a file using the filename extension.
389
 *
390
 * The filename extension is used to infer the mime type.
391
 *
392
 * @param string $filepath
393
 *   The path to the respective file.
394
 *
395
 * @return string
396
 *   The mimetype for the file or FALSE if the according mime type could
397
 *   not be found.
398
 */
399
function infer_mime_type($filepath) {
400
  static $mimemap = NULL;
401
  if (!$mimemap) {
402
    $mimemap = array(
403
      'jpg' => 'image/jpeg',
404
      'jpeg' => 'image/jpeg',
405
      'png' => 'image/png',
406
      'gif' => 'image/gif',
407
      'giff' => 'image/gif',
408
      'tif' => 'image/tif',
409
      'tiff' => 'image/tif',
410
      'pdf' => 'application/pdf',
411
      'html' => 'text/html',
412
      'htm' => 'text/html',
413
    );
414
  }
415
  $extension = substr($filepath, strrpos($filepath, '.') + 1);
416
  if (isset($mimemap[$extension])) {
417
    return $mimemap[$extension];
418
  }
419
  else {
420
    // FIXME remove this hack just return FALSE;
421
    return 'text/html';
422
  }
423
}
424

    
425
/**
426
 * Formats a mysql datatime as string
427
 *
428
 * @param $datetime
429
 * @param string $format
430
 *
431
 * @return
432
 *  the formatted string representation of the $datetime
433
 */
434
function format_datetime($datetime, $format = 'Y-m-d H:i:s', $strip_zeros = true){
435
  return date($format, strtotime($datetime));
436
}
437

    
438
/**
439
 * Converts an ISO 8601 org.joda.time.Partial to a year.
440
 *
441
 * The function expects an ISO 8601 time representation of a
442
 * org.joda.time.Partial of the form yyyy-MM-dd.
443
 *
444
 * @param string $partial
445
 *   ISO 8601 time representation of a org.joda.time.Partial.
446
 *
447
 * @return string
448
 *   Returns the year. In case the year is unknown (= ????), it returns NULL.
449
 */
450
function partialToYear($partial) {
451
  if (is_string($partial)) {
452
    $year = drupal_substr($partial, 0, 4);
453
    if (preg_match("/[0-9][0-9][0-9][0-9]/", $year)) {
454
      return $year;
455
    }
456
  }
457
  return '';
458
}
459

    
460
/**
461
 * Converts an ISO 8601 org.joda.time.Partial to a month.
462
 *
463
 * This function expects an ISO 8601 time representation of a
464
 * org.joda.time.Partial of the form yyyy-MM-dd.
465
 * In case the month is unknown (= ???) NULL is returned.
466
 *
467
 * @param string $partial
468
 *   ISO 8601 time representation of a org.joda.time.Partial.
469
 *
470
 * @return string
471
 *   A month.
472
 */
473
function partialToMonth($partial) {
474
  if (is_string($partial)) {
475
    $month = drupal_substr($partial, 5, 2);
476
    if (preg_match("/[0-9][0-9]/", $month)) {
477
      return $month;
478
    }
479
  }
480
  return '';
481
}
482

    
483
/**
484
 * Converts an ISO 8601 org.joda.time.Partial to a day.
485
 *
486
 * This function expects an ISO 8601 time representation of a
487
 * org.joda.time.Partial of the form yyyy-MM-dd and returns the day as string.
488
 * In case the day is unknown (= ???) NULL is returned.
489
 *
490
 * @param string $partial
491
 *   ISO 8601 time representation of a org.joda.time.Partial.
492
 *
493
 * @return string
494
 *   A day.
495
 */
496
function partialToDay($partial) {
497
  if (is_string($partial)) {
498
    $day = drupal_substr($partial, 8, 2);
499
    if (preg_match("/[0-9][0-9]/", $day)) {
500
      return $day;
501
    }
502
  }
503
  return '';
504
}
505

    
506
/**
507
 * Converts an ISO 8601 org.joda.time.Partial to YYYY-MM-DD.
508
 *
509
 * This function expects an ISO 8601 time representations of a
510
 * org.joda.time.Partial of the form yyyy-MM-dd and returns
511
 * four digit year, month and day with dashes:
512
 * YYYY-MM-DD eg: "2012-06-30", "1956-00-00"
513
 *
514
 * The partial may contain question marks eg: "1973-??-??",
515
 * these are turned in to '00' or are stripped depending of the $stripZeros
516
 * parameter.
517
 *
518
 * @param string $partial
519
 *   org.joda.time.Partial.
520
 * @param bool $stripZeros
521
 *   If set to TRUE the zero (00) month and days will be hidden:
522
 *   eg 1956-00-00 becomes 1956. The default is TRUE.
523
 * @param string @format
524
 * 	 Can ve used to specify the format of the date string, currently the following format strings are supported
525
 *    - "YYYY": Year only
526
 *    - "YYYY-MM-DD": this is the default
527
 *
528
 * @return string
529
 *   YYYY-MM-DD formatted year, month, day.
530
 */
531
function partialToDate($partial, $stripZeros = TRUE, $format= "YYYY-MM-DD") {
532

    
533
  $y = NULL; $m = NULL; $d = NULL;
534

    
535
  if(strpos($format, 'YY') !== FALSE){
536
    $y = partialToYear($partial);
537
  }
538
  if(strpos($format, 'MM') !== FALSE){
539
    $m = partialToMonth($partial);
540
  }
541
  if(strpos($format, 'DD') !== FALSE){
542
    $d = partialToDay($partial);
543
  }
544

    
545
  $y = $y ? $y : '0000';
546
  $m = $m ? $m : '00';
547
  $d = $d ? $d : '00';
548

    
549
  $date = '';
550

    
551
  if ($y == '0000' && $stripZeros && $m == '00' && $d == '00') {
552
    return '';
553
  }
554
  else {
555
    $date = $y;
556
  }
557

    
558
  if ($m == '00' && $stripZeros && $d == '00') {
559
    return $date;
560
  }
561
  else {
562
    $date .= "-" . $m;
563
  }
564

    
565
  if ($d == '00' && $stripZeros) {
566
    return $date;
567
  }
568
  else {
569
    $date .= "-" . $d;
570
  }
571
  return $date;
572
}
573

    
574
/**
575
 * Converts a time period to a string.
576
 *
577
 * See also partialToDate($partial, $stripZeros).
578
 *
579
 * @param object $period
580
 *   An JodaTime org.joda.time.Period object.
581
 * @param bool $stripZeros
582
 *   If set to True, the zero (00) month and days will be hidden:
583
 *   eg 1956-00-00 becomes 1956. The default is TRUE.
584
 * @param string @format
585
 * 	 Can ve used to specify the format of the date string, currently the following format strings are supported
586
 *    - "YYYY": Year only
587
 *    - "YYYY-MM-DD": this is the default
588
 *
589
 * @return string
590
 *   Returns a date in the form of a string.
591
 */
592
function timePeriodToString($period, $stripZeros = TRUE, $format = "YYYY-MM-DD") {
593
  $dateString = '';
594
  if($period->freeText){
595
    $dateString = $period->freeText;
596
  } else {
597
    if ($period->start) {
598
      $dateString = partialToDate($period->start, $stripZeros, $format);
599
    }
600
    if ($period->end) {
601
      $end_str = partialToDate($period->end, $stripZeros, $format);
602
      $dateString .= ($dateString && $end_str ? ' ' . t('to') . ' ' : '') . $end_str;
603
    }
604
  }
605
  return $dateString;
606
}
607

    
608
/**
609
 * returns the earliest date available in the $period in a normalized
610
 * form suitable for sorting, e.g.:
611
 *
612
 *  - 1956-00-00
613
 *  - 0000-00-00
614
 *  - 1957-03-00
615
 *
616
 * that is either the start date is returned if set otherwise the
617
 * end date
618
 *
619
 * @param  $period
620
 *    An JodaTime org.joda.time.Period object.
621
 * @return string normalized form of the date
622
 *   suitable for sorting
623
 */
624
function timePeriodAsOrderKey($period) {
625
  $dateString = '';
626
  if ($period->start) {
627
    $dateString = partialToDate($period->start, false);
628
  }
629
  if ($period->end) {
630
    $dateString .= partialToDate($period->end, false);
631
  }
632
  return $dateString;
633
}
634

    
635
/**
636
 * Composes a absolute CDM web service URI with parameters and querystring.
637
 *
638
 * @param string $uri_pattern
639
 *   String with place holders ($0, $1, ..) that should be replaced by the
640
 *   according element of the $pathParameters array.
641
 * @param array $pathParameters
642
 *   An array of path elements, or a single element.
643
 * @param string $query
644
 *   A query string to append to the URL.
645
 *
646
 * @return string
647
 *   A complete URL with parameters to a CDM webservice.
648
 */
649
function cdm_compose_ws_url($uri_pattern, $pathParameters = array(), $query = NULL) {
650
  if (empty($pathParameters)) {
651
    $pathParameters = array();
652
  }
653
  $path = cdm_compose_url($uri_pattern, $pathParameters, $query);
654

    
655
  $uri = variable_get('cdm_webservice_url', '') . $path;
656
  return $uri;
657
}
658

    
659
/**
660
 * Composes a relative Url with parameters and querystring.
661
 *
662
 * @param string $uri_pattern
663
 *   String with place holders ($0, $1, ..) that should be replaced by the
664
 *   according element of the $pathParameters array.
665
 * @param array $pathParameters
666
 *   An array of path elements, or a single element.
667
 * @param string $query
668
 *   A query string to append to the URL.
669
 *
670
 * @return string
671
 *   A relative URL with query parameters.
672
 */
673
function cdm_compose_url($uri_pattern, $pathParameters, $query = NULL) {
674

    
675
  // (1)
676
  // Substitute all place holders ($0, $1, ..) in the $uri_pattern by the
677
  // according element of the $pathParameters array.
678
  static $helperArray = [];
679
  if (isset($pathParameters) && !is_array($pathParameters)) {
680
    $helperArray[0] = $pathParameters;
681
    $pathParameters = $helperArray;
682
  }
683

    
684
  $i = 0;
685
  while (strpos($uri_pattern, "$" . $i) !== FALSE) {
686
    if (count($pathParameters) <= $i) {
687
      drupal_set_message('cdm_compose_url(): missing pathParameter ' . $i .' for ' . $uri_pattern, 'error');
688
      break;
689
    }
690
    $uri_pattern = str_replace("$" . $i, rawurlencode($pathParameters[$i]), $uri_pattern);
691
    ++$i;
692
  }
693

    
694
  // (2)
695
  // Append all remaining element of the $pathParameters array as path
696
  // elements.
697
  if (count($pathParameters) > $i) {
698
    // Strip trailing slashes.
699
    if (strrchr($uri_pattern, '/') == strlen($uri_pattern)) {
700
      $uri_pattern = substr($uri_pattern, 0, strlen($uri_pattern) - 1);
701
    }
702
    while (count($pathParameters) > $i) {
703
      $uri_pattern .= '/' . rawurlencode($pathParameters[$i]);
704
      ++$i;
705
    }
706
  }
707

    
708
  // (3)
709
  // Append the query string supplied by $query.
710
  $uri_pattern = append_query_parameters($uri_pattern, $query);
711

    
712
  $path = $uri_pattern;
713
  return $path;
714
}
715

    
716
/**
717
 * @param string $uri
718
 *
719
 * @param $query_string
720
 *
721
 * @return string
722
 */
723
function append_query_parameters($uri, $query_string) {
724

    
725
  if (isset($query_string)) {
726
    $uri .= (strpos($uri, '?') !== FALSE ? '&' : '?') . $query_string;
727
  }
728

    
729
  return $uri;
730
}
731

    
732
/**
733
 * @todo wouldn't it more elegant and secure to only pass a uuid and additional function parameters
734
 *     together with a theme name to such a proxy function?
735
 *     Well this would not be covering all use cases but maybe all which involve AHAH.
736
 *     Maybe we want to have two different proxy functions, one with theming and one without?
737
 *
738
 * @param string $uri
739
 *     A URI to a CDM Rest service from which to retrieve an object
740
 * @param string|null $hook
741
 *     (optional) The hook name to which the retrieved object should be passed.
742
 *     Hooks can either be a theme_hook() or compose_hook() implementation
743
 *     'theme' hook functions return a string whereas 'compose' hooks are returning render arrays
744
 *     suitable for drupal_render()
745
 *
746
 * @todo Please document this function.
747
 * @see http://drupal.org/node/1354
748
 */
749
function proxy_content($uri, $hook = NULL) {
750

    
751
  $args = func_get_args();
752
  $do_gzip = function_exists('gzencode');
753
  $uriEncoded = array_shift($args);
754
  $uri = urldecode($uriEncoded);
755
  $hook = array_shift($args);
756
  $request_method = strtoupper($_SERVER["REQUEST_METHOD"]);
757

    
758
  $post_data = null;
759

    
760
  if ($request_method == "POST" || $request_method == "PUT") {
761
    // read response body via inputstream module
762
    $post_data = file_get_contents("php://input");
763
  }
764

    
765
  // Find and deserialize arrays.
766
  foreach ($args as &$arg) {
767
    // FIXME use regex to find serialized arrays.
768
    //       or should we accept json instead of php serializations?
769
    if (strpos($arg, "a:") === 0) {
770
      $arg = unserialize($arg);
771
    }
772
  }
773

    
774
  // In all these cases perform a simple get request.
775
  // TODO reconsider caching logic in this function.
776

    
777
  if (empty($hook)) {
778
    // simply return the webservice response
779
    // Print out JSON, the cache cannot be used since it contains objects.
780
    $http_response = cdm_http_request($uri, $request_method, $post_data);
781
    if (isset($http_response->headers)) {
782
      foreach ($http_response->headers as $hname => $hvalue) {
783
        drupal_add_http_header($hname, $hvalue);
784
      }
785
    }
786
    if (isset($http_response->data)) {
787
      print $http_response->data;
788
      flush();
789
    }
790
    exit(); // leave drupal here
791
  } else {
792
    // $hook has been supplied
793
    // handle $hook either as compose or theme hook
794
    // pass through theme or compose hook
795
    // compose hooks can be called without data, therefore
796
    // passing the $uri in this case is not always a requirement
797

    
798
    if($uri && $uri != 'NULL') {
799
    // do a security check since the $uri will be passed
800
    // as absolute URI to cdm_ws_get()
801
      if (!_is_cdm_ws_uri($uri)) {
802
        drupal_set_message(
803
          'Invalid call of proxy_content() with callback parameter \'' . $hook . '\' and URI:' . $uri,
804
          'error'
805
        );
806
        return '';
807
      }
808

    
809
      $obj = cdm_ws_get($uri, NULL, $post_data, $request_method, TRUE);
810
    } else {
811
      $obj = NULL;
812
    }
813

    
814
    $reponse_data = NULL;
815

    
816
    if (function_exists('compose_' . $hook)){
817
      // call compose hook
818

    
819
      $elements =  call_user_func('compose_' . $hook, $obj);
820
      // pass the render array to drupal_render()
821
      $reponse_data = drupal_render($elements);
822
    } else {
823
      // call theme hook
824

    
825
      // TODO use theme registry to get the registered hook info and
826
      //    use these defaults
827
      switch($hook) {
828
        case 'cdm_taxontree':
829
          $variables = array(
830
            'tree' => $obj,
831
            'filterIncludes' => isset($args[0]) ? $args[0] : NULL,
832
            'show_filter_switch' => isset($args[1]) ? $args[1] : FALSE,
833
            'tree_node_callback' => isset($args[2]) ? $args[2] : FALSE,
834
            'element_name'=> isset($args[3]) ? $args[3] : FALSE,
835
            );
836
          $reponse_data = theme($hook, $variables);
837
          break;
838

    
839
        case 'cdm_list_of_taxa':
840
            $variables = array(
841
              'records' => $obj,
842
              'freetextSearchResults' => isset($args[0]) ? $args[0] : array(),
843
              'show_classification' => isset($args[1]) ? $args[1] : FALSE);
844
            $reponse_data = theme($hook, $variables);
845
            break;
846

    
847
        case 'cdm_media_caption':
848
          $variables = $arg;
849
          $variables['media'] = $obj;
850

    
851
          $reponse_data = theme($hook, $variables);
852
          break;
853

    
854
        default:
855
          drupal_set_message(t(
856
          'Theme !theme is not yet supported by the function !function.', array(
857
          '!theme' => $hook,
858
          '!function' => __FUNCTION__,
859
          )), 'error');
860
          break;
861
      } // END of theme hook switch
862
    } // END of tread as theme hook
863

    
864

    
865
    if($do_gzip){
866
      $reponse_data = gzencode($reponse_data, 2, FORCE_GZIP);
867
      drupal_add_http_header('Content-Encoding', 'gzip');
868
    }
869
    drupal_add_http_header('Content-Type', 'text/html; charset=utf-8');
870
    drupal_add_http_header('Content-Length', strlen($reponse_data));
871

    
872
    print $reponse_data;
873
  } // END of handle $hook either as compose ot theme hook
874

    
875
}
876

    
877
/**
878
 * @todo Please document this function.
879
 * @see http://drupal.org/node/1354
880
 */
881
function setvalue_session() {
882
  if ($_REQUEST['var'] && strlen($_REQUEST['var']) > 4) {
883
    $var_keys = substr($_REQUEST['var'], 1, strlen($_REQUEST['var']) - 2);
884
    $var_keys = explode('][', $var_keys);
885
  }
886
  else {
887
    return;
888
  }
889
  $val = isset($_REQUEST['val']) ? $_REQUEST['val'] : NULL;
890

    
891
  // Prevent from malicous tags.
892
  $val = strip_tags($val);
893

    
894
  $session_var = &$_SESSION;
895
  //$i = 0;
896
  foreach ($var_keys as $key) {
897
    // $hasMoreKeys = ++$i < count($session);
898
    if (!isset($session_var[$key]) || !is_array($session_var[$key])) {
899
      $session_var[$key] = array();
900
    }
901
    $session_var = &$session_var[$key];
902
  }
903
  $session_var = $val;
904
  if (isset($_REQUEST['destination'])) {
905
    drupal_goto($_REQUEST['destination']);
906
  }
907
}
908

    
909
/**
910
 * @todo Please document this function.
911
 * @see http://drupal.org/node/1354
912
 */
913
function uri_uriByProxy($uri, $theme = FALSE) {
914
  // usage: url('cdm_api/proxy/'.urlencode($content_url)."/$theme");)
915
  return url('cdm_api/proxy/' . urlencode($uri) . (isset($theme) ? "/$theme" : ''));
916
}
917

    
918
/**
919
 * Composes the the absolute REST service URI to the annotations pager
920
 * for the given CDM entity.
921
 *
922
 * NOTE: Not all CDM Base types are yet supported.
923
 *
924
 * @param $cdm_entity
925
 *   The CDM entity to construct the annotations pager uri for
926
 */
927
function cdm_compose_annotations_uri($cdm_entity) {
928

    
929
  $cdm_entity_type = $cdm_entity->class;
930

    
931
  if($cdm_entity_type == 'DerivedUnitFacade'){
932
    // TODO with the below code we may miss annotations.
933
    //  Better implement a derivedUnitFacade/{uuid}/annotations service and use that instead
934
    if(isset($cdm_entity->fieldUnitEntityReference)){
935
      $cdm_entity_type = $cdm_entity->fieldUnitEntityReference->type;
936
      $cdm_entity_uuid = $cdm_entity->fieldUnitEntityReference->uuid;
937
    } elseif(isset($cdm_entity->baseUnitEntityReference)){
938
      $cdm_entity_type = $cdm_entity->baseUnitEntityReference->type;
939
      $cdm_entity_uuid = $cdm_entity->baseUnitEntityReference->uuid;
940
    }
941
  } elseif ($cdm_entity_type == 'TypedEntityReference'){
942
    $cdm_entity_type = $cdm_entity->type;
943
    $cdm_entity_uuid = $cdm_entity->uuid;
944
  } else {
945
    if (isset($cdm_entity->uuid)) {
946
      $cdm_entity_uuid = $cdm_entity->uuid;
947
    }
948
  }
949

    
950
  if(!isset($cdm_entity_uuid) || !isset($cdm_entity_type) || !$cdm_entity_type ){
951
    // silently give up
952
    return;
953
  }
954

    
955
  $ws_base_uri = cdm_ws_base_uri($cdm_entity_type);
956

    
957
  if($ws_base_uri === null){
958
      trigger_error(check_plain('Unsupported CDM Class - no annotations available for ' . $cdm_entity_type), E_USER_ERROR);
959
  }
960
  return cdm_compose_ws_url($ws_base_uri, array(
961
    $cdm_entity_uuid,
962
    'annotations',
963
  ));
964
}
965

    
966
/**
967
 * Provides the base URI of the cdm REST service responsible for the passed simple name
968
 * of a CDM java class. For example 'TaxonName' is the simple name of 'eu.etaxonomy.cdm.model.name.TaxonName'
969
 *
970
 * @param $cdm_type_simple
971
 *    simple name of a CDM java class
972
 * @return null|string
973
 */
974
function cdm_ws_base_uri($cdm_type_simple)
975
{
976
  $ws_base_uri = NULL;
977
  switch ($cdm_type_simple) {
978

    
979
    case 'TaxonNode':
980
    case 'TaxonNodeDto':
981
      $ws_base_uri = CDM_WS_TAXONNODE;
982
    case 'TaxonBase':
983
    case 'Taxon':
984
    case 'Synonym':
985
      $ws_base_uri = CDM_WS_TAXON;
986
      break;
987

    
988
    case 'TaxonName':
989
      $ws_base_uri = CDM_WS_NAME;
990
      break;
991

    
992
    case 'Media':
993
      $ws_base_uri = CDM_WS_MEDIA;
994
      break;
995

    
996
    case 'Reference':
997
      $ws_base_uri = CDM_WS_REFERENCE;
998
      break;
999

    
1000
    case 'Registration':
1001
      $ws_base_uri = CDM_WS_REFERENCE;
1002
      break;
1003

    
1004
    case 'FieldUnit':
1005
    case 'DerivedUnit':
1006
    case 'DnaSample':
1007
    case 'MediaSpecimen':
1008
    case 'DerivedUnitDTO':
1009
    case 'FieldUnitDTO':
1010
    case 'DNASampleDTO':
1011
      $ws_base_uri = CDM_WS_OCCURRENCE;
1012
      break;
1013

    
1014
    case 'Amplification':
1015
    case 'DerivationEvent':
1016
    case 'DeterminationEvent':
1017
    case 'GatheringEvent':
1018
    case 'MaterialOrMethodEvent':
1019
    case 'SingleRead':
1020
      $ws_base_uri = CDM_WS_EVENTBASE;
1021
      break;
1022

    
1023
    case 'Distribution':
1024
    case 'TextData':
1025
    case 'TaxonInteraction':
1026
    case 'QuantitativeData':
1027
    case 'IndividualsAssociation':
1028
    case 'CommonTaxonName':
1029
    case 'CategoricalData':
1030
      $ws_base_uri = CDM_WS_DESCRIPTIONELEMENT;
1031
      break;
1032

    
1033
    case 'Person':
1034
    case 'Team':
1035
    case 'AgentBase':
1036
      $ws_base_uri = CDM_WS_AGENT;
1037
      break;
1038

    
1039
    case 'PolytomousKey':
1040
    case 'MediaKey':
1041
    case 'MultiAccessKey':
1042
      $ws_base_uri = $cdm_type_simple;
1043
      $ws_base_uri[0] = strtolower($ws_base_uri[0]);
1044
      break;
1045

    
1046
    case 'TextualTypeDesignation':
1047
    case 'SpecimenTypeDesignation':
1048
    case 'NameTypeDesignation':
1049
    case 'TypeDesignationDTO':
1050
      $ws_base_uri = CDM_WS_TYPEDESIGNATION;
1051
      break;
1052
    default:
1053
      $ws_base_uri = null;
1054
      drupal_set_message(
1055
        t('cdm_ws_base_uri()  - cdm type name "@cdm_type_simple" unsupported',
1056
          array('@cdm_type_simple' => $cdm_type_simple )),
1057
        'error');
1058
  }
1059
  return $ws_base_uri;
1060
}
1061

    
1062
/**
1063
 * Enter description here...
1064
 *
1065
 * @param string $resource_uri
1066
 * @param int $page_size
1067
 *   The maximum number of entities returned per page.
1068
 *   The default page size as configured in the cdm server
1069
 *   will be used if set to NULL
1070
 *   to return all entities in a single page).
1071
 * @param int $page_index
1072
 *   The number of the page to be returned, the first page has the
1073
 *   page_index = 0
1074
 * @param array $query
1075
 *   A array holding the HTTP request query parameters for the request
1076
 * @param string $method
1077
 *   The HTTP method to use, valid values are "GET" or "POST"
1078
 * @param bool $absolute_uri
1079
 *   TRUE when the URL should be treated as absolute URL.
1080
 *
1081
 * @return object
1082
 *   A CDM Pager object
1083
 *
1084
 */
1085
function cdm_ws_page($resource_uri, $page_size, $page_index, array $query = array(), $method = 'GET', $absolute_uri = FALSE) {
1086

    
1087
  $query['pageNumber'] = $page_index;
1088
  $query['pageSize'] = $page_size;
1089

    
1090
  $pager = cdm_ws_get($resource_uri, NULL, queryString($query), $method, $absolute_uri);
1091
  if(is_array($pager)){
1092
    trigger_error("Expecting web service to return pager objects but received an array:<br/>" . $resource_uri . '?' . queryString($query) . '<br/>Wrapping response in pager to recover from error.', E_USER_WARNING);
1093
    $records = $pager;
1094
    $pager = new stdClass();
1095
    $pager->records = $records;
1096
    $pager->count = count($records);
1097
    $pager->pageSize = $pager->count;
1098
    $pager->nextIndex = null;
1099
  }
1100
  return $pager;
1101
}
1102

    
1103

    
1104
/**
1105
 * Sends a http GET request to the generic page method which allows for filtering entities by Restrictions.
1106
 *
1107
 * @param $cdm_entity_type
1108
 * @param $class_restriction
1109
 *   Optional param to narrow down polymorph types to a specific type.
1110
 * @param array $restrictions
1111
 *   An array of Restriction objects
1112
 * @param array $init_strategy
1113
 *   The init strategy to initialize the entity beans while being loaded from the
1114
 *   persistent storage by the cdm
1115
 * @param int $page_size
1116
 *   The maximum number of entities returned per page.
1117
 *   The default page size as configured in the cdm server
1118
 *   will be used if set to NULL
1119
 *   to return all entities in a single page).
1120
 * @param int $page_index
1121
 *   The number of the page to be returned, the first page has the
1122
 *   pageNumber = 0
1123
 *
1124
 * @return object
1125
 *   A CDM Pager object
1126
 */
1127
function cdm_ws_page_by_restriction($cdm_entity_type, $class_restriction, array $restrictions, array $init_strategy, $page_size, $page_index) {
1128

    
1129
  $restrictions_json = array(); // json_encode($restrictions);
1130
  foreach ($restrictions as $restr){
1131
    $restrictions_json[] = json_encode($restr);
1132
  }
1133
  $filter_parameters = [
1134
    'restriction' => $restrictions_json,
1135
    'initStrategy' => $init_strategy
1136
  ];
1137
  if($class_restriction){
1138
    $filter_parameters['class'] = $class_restriction;
1139
  }
1140

    
1141
  return cdm_ws_page(
1142
      'portal/' . cdm_ws_base_uri($cdm_entity_type),
1143
      $page_size,
1144
      $page_index,
1145
    $filter_parameters,
1146
    "GET"
1147
    );
1148
}
1149

    
1150
/**
1151
 * Fetches all entities returned by the the generic page method for the Restrictions applied as filter.
1152
 *
1153
 * @param $cdm_entity_type
1154
 * @param $class_restriction
1155
 *   Optional param to narrow down polymorph types to a specific type.
1156
 * @param array $restrictions
1157
 *   An array of Restriction objects
1158
 * @param array $init_strategy
1159
 *   The init strategy to initialize the entity beans while being loaded from the
1160
 *   persistent storage by the cdm
1161
 *
1162
 * @return array
1163
 *   A array of CDM entities
1164
 */
1165
function cdm_ws_fetch_all_by_restriction($cdm_entity_type, $class_restriction, array $restrictions, array $init_strategy){
1166
  $page_index = 0;
1167
  // using a bigger page size to avoid to many multiple requests
1168
  $page_size = 500;
1169
  $entities = array();
1170

    
1171
  while ($page_index !== FALSE && $page_index < 1){
1172
    $pager =  cdm_ws_page_by_restriction($cdm_entity_type, $class_restriction, $restrictions, $init_strategy, $page_size, $page_index);
1173
    if(isset($pager->records) && is_array($pager->records)) {
1174
      $entities = array_merge($entities, $pager->records);
1175
      if(!empty($pager->nextIndex)){
1176
        $page_index = $pager->nextIndex;
1177
      } else {
1178
        $page_index = FALSE;
1179
      }
1180
    } else {
1181
      $page_index = FALSE;
1182
    }
1183
  }
1184
  return $entities;
1185
}
1186

    
1187

    
1188
  /**
1189
 * Fetches all entities from the given REST endpoint using the pager mechanism.
1190
 *
1191
 * @param string $resourceURI
1192
 * @param array $query
1193
 *   A array holding the HTTP request query parameters for the request
1194
 * @param string $method
1195
 *   The HTTP method to use, valid values are "GET" or "POST";
1196
 * @param bool $absoluteURI
1197
 *   TRUE when the URL should be treated as absolute URL.
1198
 *
1199
 * @return array
1200
 *     A list of CDM entitites
1201
 *
1202
 */
1203
function cdm_ws_fetch_all($resourceURI, array $query = array(), $method = 'GET', $absoluteURI = FALSE) {
1204
  $page_index = 0;
1205
  // using a bigger page size to avoid too many multiple requests
1206
  $page_size = 500;
1207
  $entities = [];
1208

    
1209
  while ($page_index !== FALSE){
1210
    $pager =  cdm_ws_page($resourceURI, $page_size, $page_index, $query,  $method, $absoluteURI);
1211
    if(isset($pager->records) && is_array($pager->records)) {
1212
      $entities = array_merge($entities, $pager->records);
1213
      if(!empty($pager->nextIndex)){
1214
        $page_index = $pager->nextIndex;
1215
      } else {
1216
        $page_index = FALSE;
1217
      }
1218
    } else {
1219
      $page_index = FALSE;
1220
    }
1221
  }
1222
  return $entities;
1223
}
1224

    
1225
/*
1226
function cdm_ws_taxonomy_compose_resourcePath($path = NULL){
1227
  $viewrank = _cdm_taxonomy_compose_viewrank();
1228
  return CDM_WS_PORTAL_TAXONOMY . '/' . ($viewrank ? $viewrank : '' ) . ($path
1229
  ? '/' . $path : '') ;
1230
}
1231
*/
1232

    
1233
/**
1234
 * @todo Enter description here...
1235
 *
1236
 * @param string $taxon_uuid
1237
 *  The UUID of a cdm taxon instance
1238
 * @param string $ignore_rank_limit
1239
 *   Whether to ignore the variable 'taxontree_ranklimit' set by admin in the settings
1240
 *
1241
 * @return string
1242
 *   A cdm REST service URL path to a Classification
1243
 */
1244
function cdm_compose_taxonomy_root_level_path($taxon_uuid = FALSE, $ignore_rank_limit = FALSE) {
1245

    
1246
  $view_uuid = get_current_classification_uuid();
1247
  $rank_uuid = NULL;
1248
  if (!$ignore_rank_limit) {
1249
    $rank_uuid = variable_get(TAXONTREE_RANKLIMIT, TAXONTREE_RANKLIMIT_DEFAULT);
1250
  }
1251

    
1252
  if (!empty($taxon_uuid)) {
1253
    return cdm_compose_ws_url(CDM_WS_PORTAL_TAXONOMY_CHILDNODES_OF_TAXON, array(
1254
      $view_uuid,
1255
      $taxon_uuid,
1256
    ));
1257
  }
1258
  else {
1259
    if (is_uuid($rank_uuid)) {
1260
      return cdm_compose_ws_url(CDM_WS_PORTAL_TAXONOMY_CHILDNODES_AT_RANK, array(
1261
        $view_uuid,
1262
        $rank_uuid,
1263
      ));
1264
    }
1265
    else {
1266
      return cdm_compose_ws_url(CDM_WS_PORTAL_TAXONOMY_CHILDNODES, array(
1267
        $view_uuid,
1268
      ));
1269
    }
1270
  }
1271
}
1272

    
1273
/**
1274
 * Retrieves from the cdm web service with the first level of childnodes of a classification.
1275
 *
1276
 * The level is either the real root level ot it is a lover level if a rank limit has been set.
1277
 * (@see  cdm_compose_taxonomy_root_level_path() for more on the rank limit).
1278
 *
1279
 * Operates in two modes depending on whether the parameter
1280
 * $taxon_uuid is set or NULL.
1281
 *
1282
 * A) $taxon_uuid = NULL:
1283
 *  1. retrieve the Classification for the uuid set in the $_SESSION['cdm']['taxonomictree_uuid']
1284
 *  2. otherwise return the default classification as defined by the admin via the settings
1285
 *
1286
 * b) $taxon_uuid is set:
1287
 *   return the classification to whcih the taxon belongs to.
1288
 *
1289
 * @param UUID $taxon_uuid
1290
 *   The UUID of a cdm taxon instance
1291
 */
1292
function cdm_ws_taxonomy_root_level($taxon_uuid = NULL) {
1293

    
1294
    $response = NULL;
1295

    
1296
    // 1st try
1297
    $response = cdm_ws_get(cdm_compose_taxonomy_root_level_path($taxon_uuid), NULL, NULL, 'GET', TRUE);
1298

    
1299
    if ($response == NULL) {
1300
      // 2dn try by ignoring the rank limit
1301
      $response = cdm_ws_get(cdm_compose_taxonomy_root_level_path($taxon_uuid, TRUE), NULL, NULL, 'GET', TRUE);
1302
    }
1303

    
1304
    if ($response == NULL) {
1305
      // 3rd try, last fallback:
1306
      //    return the default classification
1307
      if (isset($_SESSION['cdm']['taxonomictree_uuid']) && is_uuid($_SESSION['cdm']['taxonomictree_uuid'])) {
1308
        // Delete the session value and try again with the default.
1309
        unset($_SESSION['cdm']['taxonomictree_uuid']);
1310
        drupal_set_message("Could not find a valid classification, falling back to the default classification.", 'warning');
1311
        return cdm_ws_taxonomy_root_level($taxon_uuid);
1312
      }
1313
      else {
1314
        // Check if taxonomictree_uuid is valid.
1315
        // expecting an array of taxonNodes,
1316
        // empty classifications are ok so no warning in this case!
1317
        $test = cdm_ws_get(cdm_compose_taxonomy_root_level_path(), NULL, NULL, 'GET', TRUE);
1318
        if (!is_array($test)) {
1319
          // The default set by the admin seems to be invalid or is not even set.
1320
          drupal_set_message(_no_classfication_uuid_message(), 'warning');
1321
        }
1322
        if (count($test) == 0) {
1323
          // The default set by the admin seems to be invalid or is not even set.
1324
          drupal_set_message("The chosen classification is empty.", 'status');
1325
        }
1326
      }
1327
    }
1328

    
1329
  return $response;
1330
}
1331

    
1332
/**
1333
 * Determines the tree path of the taxon given as uuid to the root of the classification tree.
1334
 * 
1335
 * The root either is the absolute root of the tree or a rank specific root if the TAXONTREE_RANKLIMIT
1336
 * variable is set.
1337
 *
1338
 * @param string $taxon_uuid
1339
 *
1340
 * @return array
1341
 *   An array of CDM TaxonNodeDTO objects
1342
 */
1343
function cdm_ws_taxonomy_pathFromRoot($taxon_uuid) {
1344
  $view_uuid = get_current_classification_uuid();
1345
  $rank_uuid = variable_get(TAXONTREE_RANKLIMIT, TAXONTREE_RANKLIMIT_DEFAULT);
1346

    
1347
  $response = NULL;
1348
  if (is_uuid($rank_uuid)) {
1349
    $response = cdm_ws_get(CDM_WS_PORTAL_TAXONOMY_PATH_FROM_TO_RANK, array(
1350
      $view_uuid,
1351
      $taxon_uuid,
1352
      $rank_uuid,
1353
    ));
1354
  }
1355
  else {
1356
    $response = cdm_ws_get(CDM_WS_PORTAL_TAXONOMY_PATH_FROM, array(
1357
      $view_uuid,
1358
      $taxon_uuid,
1359
    ));
1360
  }
1361

    
1362
  if ($response == NULL) {
1363
    // Error handing.
1364
//    if (is_uuid($_SESSION['cdm']['taxonomictree_uuid'])) {
1365
//      // Delete the session value and try again with the default.
1366
//      unset($_SESSION['cdm']['taxonomictree_uuid']);
1367
//      return cdm_ws_taxonomy_pathFromRoot($taxon_uuid);
1368
//    }
1369
//    else {
1370
      // Check if taxonomictree_uuid is valid.
1371
      $test = cdm_ws_get(cdm_compose_taxonomy_root_level_path(), NULL, NULL, 'GET', TRUE);
1372
      if ($test == NULL) {
1373
        // The default set by the admin seems to be invalid or is not even set.
1374
        drupal_set_message(_no_classfication_uuid_message(), 'warning');
1375
      }
1376
//    }
1377
  }
1378

    
1379
  return $response;
1380
}
1381

    
1382

    
1383
// =============================Terms and Vocabularies ========================================= //
1384

    
1385
/**
1386
 * Returns the localized representation for the given term.
1387
 *
1388
 * @param Object $definedTermBase
1389
 * 	  of cdm type DefinedTermBase
1390
 * @return string
1391
 * 	  the localized representation_L10n of the term,
1392
 *    otherwise the titleCache as fall back,
1393
 *    otherwise the default_representation which defaults to an empty string
1394
 */
1395
function cdm_term_representation($definedTermBase, $default_representation = '') {
1396
  if ( isset($definedTermBase->representation_L10n) ) {
1397
    return $definedTermBase->representation_L10n;
1398
  } elseif ( isset($definedTermBase->titleCache)) {
1399
    return $definedTermBase->titleCache;
1400
  }
1401
  return $default_representation;
1402
}
1403

    
1404
/**
1405
 * Returns the abbreviated localized representation for the given term.
1406
 *
1407
 * @param Object $definedTermBase
1408
 * 	  of cdm type DefinedTermBase
1409
 * @return string
1410
 * 	  the localized representation_L10n_abbreviatedLabel of the term,
1411
 *    if this representation is not available the function delegates the
1412
 *    call to cdm_term_representation()
1413
 */
1414
function cdm_term_representation_abbreviated($definedTermBase, $default_representation = '') {
1415
  if ( isset($definedTermBase->representation_L10n_abbreviatedLabel) ) {
1416
    return $definedTermBase->representation_L10n_abbreviatedLabel;
1417
  } else {
1418
    cdm_term_representation($definedTermBase, $default_representation);
1419
  }
1420
}
1421

    
1422
/**
1423
 * Transforms the list of the given term base instances to a alphabetical ordered options array.
1424
 *
1425
 * The options array is suitable for drupal form API elements that allow multiple choices.
1426
 * @see http://api.drupal.org/api/drupal/developer!topics!forms_api_reference.html/7#options
1427
 *
1428
 * @param array $terms
1429
 *   a list of CDM DefinedTermBase instances
1430
 *
1431
 * @param $term_label_callback
1432
 *   A callback function to override the term representations
1433
 *
1434
 * @param bool $empty_option
1435
 *   An additional element do be placed at the beginning og the list. This element will be the default option.
1436
 *
1437
 * @return array
1438
 *   the terms in an array (key: uuid => value: label) as options for a form element that allows multiple choices.
1439

    
1440
 */
1441
function cdm_terms_as_options($terms, $term_label_callback = NULL, $empty_option = FALSE){
1442
  $options = array();
1443
  if(isset($terms) && is_array($terms)) {
1444
    foreach ($terms as $term) {
1445
      if ($term_label_callback && function_exists($term_label_callback)) {
1446
        $options[$term->uuid] = call_user_func($term_label_callback, $term);
1447
      } else {
1448
        //TODO use cdm_term_representation() here?
1449
        $options[$term->uuid] = t('@term', array('@term' => $term->representation_L10n));
1450
      }
1451
    }
1452
  }
1453

    
1454
  if($empty_option !== FALSE){
1455
    array_unshift ($options, "");
1456
  }
1457

    
1458
  return $options;
1459
}
1460

    
1461
/**
1462
 * Creates and array of options for drupal select form elements.
1463
 *
1464
 * @param $vocabulary_uuid
1465
 *   The UUID of the CDM Term Vocabulary
1466
 * @param $term_label_callback
1467
 *   An optional call back function which can be used to modify the term label
1468
 * @param bool $empty_option
1469
 *   An additional element do be placed at the beginning og the list. This element will be the default option.
1470
 * @param array $include_filter
1471
 *   An associative array consisting of a field name an regular expression. All term matching
1472
 *   these filter are included. The value of the field is converted to a String by var_export()
1473
 *   so a boolean 'true' can be matched by '/true/'
1474
 * @param string $order_by
1475
 *   One of the order by constants defined in this file
1476
 * @return array
1477
 *   the terms in an array (key: uuid => value: label) as options for a form element that allows multiple choices.
1478
 */
1479
function cdm_vocabulary_as_option($vocabulary_uuid, $term_label_callback = NULL, $empty_option = FALSE,
1480
                                  array $include_filter = null, $order_by = CDM_ORDER_BY_ORDER_INDEX_ASC) {
1481

    
1482
  static $vocabularyOptions = array();
1483

    
1484
  if (!isset($vocabularyOptions[$vocabulary_uuid])) {
1485
    $terms = cdm_ws_fetch_all('termVocabulary/' . $vocabulary_uuid . '/terms',
1486
      array(
1487
        'orderBy' => $order_by
1488
      )
1489
    );
1490

    
1491
    // apply the include filter
1492
    if($include_filter != null){
1493
      $included_terms = array();
1494

    
1495
      foreach ($terms as $term){
1496
        $include = true;
1497
        foreach ($include_filter as $field=>$regex){
1498
          $include =  preg_match($regex, var_export($term->$field, true)) === 1;
1499
          if(!$include){
1500
            break;
1501
          }
1502
        }
1503
        if($include){
1504
          $included_terms[] = $term;
1505
        }
1506
      }
1507

    
1508
      $terms = $included_terms;
1509
    }
1510

    
1511
    // make options list
1512
    $vocabularyOptions[$vocabulary_uuid] = cdm_terms_as_options($terms, $term_label_callback, $empty_option);
1513
  }
1514

    
1515
  $options = $vocabularyOptions[$vocabulary_uuid];
1516

    
1517
  return $options;
1518
}
1519

    
1520
/**
1521
 * Creates and array of defaults for drupal select form elements.
1522
 *
1523
 * @param $vocabulary_uuid
1524
 *   The UUID of the CDM Term Vocabulary
1525
 * @param $term_label_callback
1526
 *   An optional call back function which can be used to modify the term label
1527
 * @param bool $empty_option
1528
 *   An additional element do be placed at the beginning og the list. This element will be the default option.
1529
 * @param array $include_filter
1530
 *   An associative array consisting of a field name an regular expression. All term matching
1531
 *   these filter are included. The value of the field is converted to a String by var_export()
1532
 *   so a boolean 'true' can be matched by '/true/'
1533
 * @param string $order_by
1534
 *   One of the order by constants defined in this file
1535
 * @return array
1536
 *   the terms in an array (key: uuid => value: uuid) as defaults for a form element that allows multiple choices.
1537
 */
1538
function cdm_vocabulary_as_defaults($vocabulary_uuid, array $include_filter = null) {
1539

    
1540
  $options = cdm_vocabulary_as_option($vocabulary_uuid, null, null, $include_filter);
1541
  $defaults = array();
1542
  foreach ($options as $uuid => $value){
1543
    $defaults[$uuid] = $uuid;
1544
  }
1545

    
1546
  return $defaults;
1547
}
1548

    
1549
/**
1550
 * @param $term_type string one of
1551
 *  - Unknown
1552
 *  - Language
1553
 *  - NamedArea
1554
 *  - Rank
1555
 *  - Feature
1556
 *  - AnnotationType
1557
 *  - MarkerType
1558
 *  - ExtensionType
1559
 *  - DerivationEventType
1560
 *  - PresenceAbsenceTerm
1561
 *  - NomenclaturalStatusType
1562
 *  - NameRelationshipType
1563
 *  - HybridRelationshipType
1564
 *  - SynonymRelationshipType
1565
 *  - TaxonRelationshipType
1566
 *  - NameTypeDesignationStatus
1567
 *  - SpecimenTypeDesignationStatus
1568
 *  - InstitutionType
1569
 *  - NamedAreaType
1570
 *  - NamedAreaLevel
1571
 *  - RightsType
1572
 *  - MeasurementUnit
1573
 *  - StatisticalMeasure
1574
 *  - MaterialOrMethod
1575
 *  - Material
1576
 *  - Method
1577
 *  - Modifier
1578
 *  - Scope
1579
 *  - Stage
1580
 *  - KindOfUnit
1581
 *  - Sex
1582
 *  - ReferenceSystem
1583
 *  - State
1584
 *  - NaturalLanguageTerm
1585
 *  - TextFormat
1586
 *  - DeterminationModifier
1587
 *  - DnaMarker
1588
 *
1589
 * @param  $order_by
1590
 *  Optionally sort option (default: CDM_ORDER_BY_TITLE_CACHE_ASC)
1591
 *  possible values:
1592
 *    - CDM_ORDER_BY_ID_ASC
1593
 *    - CDM_ORDER_BY_ID_DESC
1594
 *    - CDM_ORDER_BY_TITLE_CACHE_ASC
1595
 *    - CDM_ORDER_BY_TITLE_CACHE_DESC
1596
 *    - CDM_ORDER_BY_ORDER_INDEX_ASC (can only be used with OrderedTerms!!)
1597
 *    - CDM_ORDER_BY_ORDER_INDEX_DESC (can only be used with OrderedTerms!!)
1598
 * @param bool $empty_option
1599
 *   An additional element do be placed at the beginning og the list. This element will be the default option.
1600
 * @return array
1601
 *    the terms in an array (key: uuid => value: label) as options for a form element that allows multiple choices.
1602
 */
1603
function cdm_terms_by_type_as_option($term_type, $order_by = CDM_ORDER_BY_TITLE_CACHE_ASC, $term_label_callback = NULL, $empty_option = FALSE){
1604
  $terms = cdm_ws_fetch_all(
1605
    CDM_WS_TERM,
1606
    array(
1607
      'class' => $term_type,
1608
      'orderBy' => $order_by
1609
    )
1610
  );
1611
  return cdm_terms_as_options($terms, $term_label_callback, $empty_option);
1612
}
1613

    
1614
/**
1615
 * @param array $none_option
1616
 *    Will add a filter option to search for NULL values
1617
 * @param $with_empty_option
1618
 *    Will add an empty option to the beginning. Choosing this option will disable the filtering.
1619
 * @return array
1620
 *   An array of options with uuids as key and the localized term representation as value
1621
 */
1622
function cdm_type_designation_status_filter_terms_as_options($none_option_label, $with_empty_option = false){
1623
  $filter_terms = cdm_ws_get(CDM_WS_TYPE_DESIGNATION_STATUS_FILTER_TERMS);
1624

    
1625
  if(isset($filter_terms) && is_array($filter_terms)) {
1626
    foreach ($filter_terms as $filter_term) {
1627
      $options[join(',', $filter_term->uuids)] = $filter_term->label;
1628
    }
1629
  }
1630

    
1631
  if(is_string($none_option_label)){
1632
    $options = array_merge(array('NULL' => $none_option_label), $options);
1633
  }
1634

    
1635
  if($with_empty_option !== FALSE){
1636
    array_unshift ($options, "");
1637
  }
1638

    
1639

    
1640
  return $options;
1641
}
1642

    
1643

    
1644

    
1645
/**
1646
 * Callback function which provides the localized representation of a cdm term.
1647
 *
1648
 * The representation is build by concatenating the abbreviated label with the label
1649
 * and thus is especially useful for relationship terms
1650
 * The localized representation provided by the cdm can be overwritten by
1651
 * providing a drupal translation.
1652
 *
1653
 */
1654
function _cdm_relationship_type_term_label_callback($term) {
1655
  if (isset($term->representation_L10n_abbreviatedLabel)) {
1656
    return $term->representation_L10n_abbreviatedLabel . ' : '
1657
    . t('@term', array('@term' => $term->representation_L10n));
1658
  }
1659
else {
1660
    return t('@term', array('@term' => $term->representation_L10n));
1661
  }
1662
}
1663

    
1664
/**
1665
 * Callback function which provides the localized inverse representation of a cdm term.
1666
 *
1667
 * The representation is build by concatenating the abbreviated label with the label
1668
 * and thus is especially useful for relationship terms
1669
 * The localized representation provided by the cdm can be overwritten by
1670
 * providing a drupal translation.
1671
 *
1672
 */
1673
function _cdm_relationship_type_term_inverse_label_callback($term) {
1674
  if (isset($term->inverseRepresentation_L10n_abbreviatedLabel)) {
1675
    return $term->inverseRepresentation_L10n_abbreviatedLabel . ' : '
1676
      . t('@term', array('@term' => $term->inverseRepresentation_L10n));
1677
  }
1678
  else {
1679
    return t('@term', array('@term' => $term->inverseRepresentation_L10n));
1680
  }
1681
}
1682

    
1683
/**
1684
 * Returns the localized abbreviated label of the relationship term.
1685
 *
1686
 * In case the abbreviated label is not set the normal representation is returned.
1687
 *
1688
 * @param $term
1689
 * @param bool $is_inverse_relation
1690
 * @return string
1691
 *   The abbreviated label
1692
 */
1693
function cdm_relationship_type_term_abbreviated_label($term, $is_inverse_relation = false){
1694

    
1695
  if($is_inverse_relation) {
1696
    if (isset($term->inverseRepresentation_L10n_abbreviatedLabel) && $term->inverseRepresentation_L10n_abbreviatedLabel) {
1697
      $abbr_label = $term->inverseResentation_L10n_abbreviatedLabel;
1698
    } else {
1699
      $abbr_label = $term->inverseRepresentation_L10n;
1700
    }
1701
  } else {
1702
    if (isset($term->representation_L10n_abbreviatedLabel) && $term->representation_L10n_abbreviatedLabel) {
1703
      $abbr_label = $term->representation_L10n_abbreviatedLabel;
1704
    } else {
1705
      $abbr_label = $term->representation_L10n;
1706
    }
1707
  }
1708
  return $abbr_label;
1709
}
1710

    
1711
/**
1712
 * Returns the symbol of the relationship term.
1713
 *
1714
 * In case the symbol is not set the function falls back to use the abbreviated label or
1715
 * the normal representation..
1716
 *
1717
 * @param $term
1718
 * @param bool $is_inverse_relation
1719
 * @return string
1720
 *   The abbreviated label
1721
 */
1722
function cdm_relationship_type_term_symbol($term, $is_inverse_relation = false){
1723

    
1724
  if($is_inverse_relation) {
1725
    if (isset($term->inverseSymbol) && $term->inverseSymbol) {
1726
      $symbol = $term->inverseSymbol;
1727
    } else if (isset($term->inverseRepresentation_L10n_abbreviatedLabel) && $term->inverseRepresentation_L10n_abbreviatedLabel) {
1728
      $symbol = $term->inverseResentation_L10n_abbreviatedLabel;
1729
    } else {
1730
      $symbol = $term->inverseRepresentation_L10n;
1731
    }
1732
  } else {
1733
    if (isset($term->symbol) && $term->symbol) {
1734
      $symbol = $term->symbol;
1735
    } else if (isset($term->representation_L10n_abbreviatedLabel) && $term->representation_L10n_abbreviatedLabel) {
1736
      $symbol = $term->representation_L10n_abbreviatedLabel;
1737
    } else {
1738
      $symbol = $term->representation_L10n;
1739
    }
1740
  }
1741
  return $symbol;
1742
}
1743

    
1744
// ========================================================================================== //
1745
/**
1746
 * @todo Improve documentation of this function.
1747
 *
1748
 * eu.etaxonomy.cdm.model.description.
1749
 * CategoricalData
1750
 * CommonTaxonName
1751
 * Distribution
1752
 * IndividualsAssociation
1753
 * QuantitativeData
1754
 * TaxonInteraction
1755
 * TextData
1756
 */
1757
function cdm_descriptionElementTypes_as_option($prependEmptyElement = FALSE) {
1758
  static $types = array(
1759
    "CategoricalData",
1760
    "CommonTaxonName",
1761
    "Distribution",
1762
    "IndividualsAssociation",
1763
    "QuantitativeData",
1764
    "TaxonInteraction",
1765
    "TextData",
1766
  );
1767

    
1768
  static $options = NULL;
1769
  if ($options == NULL) {
1770
    $options = array();
1771
    if ($prependEmptyElement) {
1772
      $options[' '] = '';
1773
    }
1774
    foreach ($types as $type) {
1775
      // No internatianalization here since these are purely technical terms.
1776
      $options["eu.etaxonomy.cdm.model.description." . $type] = $type;
1777
    }
1778
  }
1779
  return $options;
1780
}
1781

    
1782

    
1783
/**
1784
 * Fetches all TaxonDescription descriptions elements which are associated to the
1785
 * Taxon specified by the $taxon_uuid and merges the elements into the given
1786
 * feature tree.
1787
 * @param $feature_tree
1788
 *     The CDM FeatureTree to be used as template
1789
 * @param $taxon_uuid
1790
 *     The UUID of the taxon
1791
 * @param $excludes
1792
 *     UUIDs of features to be excluded
1793
 * @return object
1794
 *     The CDM FeatureTree which was given as parameter merged tree whereas the
1795
 *     CDM FeatureNodes are extended by an additional field 'descriptionElements'
1796
 *     witch will hold the according $descriptionElements.
1797
 */
1798
function cdm_ws_descriptions_by_featuretree($feature_tree, $taxon_uuid, $exclude_uuids = array()) {
1799

    
1800
  if (!$feature_tree) {
1801
    drupal_set_message(check_plain(t("No 'FeatureTree' has been set so far.
1802
      In order to see the species profiles of your taxa, please select a
1803
      'FeatureTree' in the !settings"), array('!settings' => l(t('CDM Dataportal Settings'), 'admin/config/cdm_dataportal/layout'))), 'warning');
1804
    return FALSE;
1805
  }
1806

    
1807
  $description_elements = cdm_ws_fetch_all(CDM_WS_DESCRIPTIONELEMENT_BY_TAXON,
1808
      array(
1809
      'taxon' => $taxon_uuid,
1810
      'features' => cdm_featureTree_elements_toString($feature_tree->root, ',', 'uuid', $exclude_uuids)
1811
      ),
1812
      'POST'
1813
  );
1814

    
1815
  // Combine all descriptions into one feature tree.
1816
  $merged_nodes = _mergeFeatureTreeDescriptions($feature_tree->root->childNodes, $description_elements);
1817
  $feature_tree->root->childNodes = $merged_nodes;
1818

    
1819
  return $feature_tree;
1820
}
1821

    
1822
/**
1823
 * Returns a filtered a list of annotations for the cdm entity given as parameter $cdm_entity.
1824
 * If the annotations are not yet already loded with the cdm entity the cdm REST service will
1825
 * be requested for the annotations.
1826
 *
1827
 * @param string $cdm_entity
1828
 *   An annotatable cdm entity.
1829
 * @param array $include_types
1830
 *   If an array of annotation type uuids is supplied by this parameter the
1831
 *   list of annotations is resticted to those which belong to this type.
1832
 *
1833
 * @return array
1834
 *   An array of Annotation objects or an empty array.
1835
 */
1836
function cdm_ws_fetch_annotations(&$cdm_entity, $include_types = FALSE) {
1837

    
1838
  if(!isset($cdm_entity->annotations)){
1839
    $annotation_url = cdm_compose_annotations_uri($cdm_entity);
1840
    $cdm_entity->annotations = cdm_ws_fetch_all($annotation_url, array(), 'GET', TRUE);
1841
  }
1842

    
1843
  $annotations = array();
1844
  foreach ($cdm_entity->annotations as $annotation) {
1845
    if ($include_types) {
1846
      if (
1847
        ( isset($annotation->annotationType->uuid) && in_array($annotation->annotationType->uuid, $include_types, TRUE) )
1848
        || ($annotation->annotationType === NULL && in_array('NULL_VALUE', $include_types, TRUE))
1849
      ) {
1850
        $annotations[] = $annotation;
1851
      }
1852
    }
1853
    else {
1854
      $annotations[] = $annotation;
1855
    }
1856
  }
1857
  return $annotations;
1858

    
1859
}
1860

    
1861
/**
1862
 * Provides the list of visible annotations for the $cdm_entity.
1863
 *
1864
 * @param $cdm_entity
1865
 *     The annotatable CDM entity
1866
 *
1867
 * @return array of the annotations which are visible according to the settings as stored in ANNOTATION_TYPES_VISIBLE
1868
 */
1869
function cdm_fetch_visible_annotations($cdm_entity){
1870

    
1871
  static $annotations_types_filter = null;
1872
  if(!$annotations_types_filter) {
1873
    $annotations_types_filter = unserialize(EXTENSION_TYPES_VISIBLE_DEFAULT);
1874
  }
1875
  return cdm_ws_fetch_annotations($cdm_entity, variable_get(ANNOTATION_TYPES_VISIBLE, $annotations_types_filter));
1876
}
1877

    
1878
/**
1879
 * Loads the annotations from the REST service an adds them as field to the given $annotatable_entity.
1880
 *
1881
 * NOTE: The annotations are not filtered by the ANNOTATION_TYPES_VISIBLE settings since this method is meant to act
1882
 * like the annotations have been fetched in the ORM-framework in the service.
1883
 *
1884
 * @param object $annotatable_entity
1885
 *   The CDM AnnotatableEntity to load annotations for
1886
 */
1887
function cdm_load_annotations(&$annotatable_entity) {
1888
  if (isset($annotatable_entity) && !isset($annotatable_entity->annotations)) {
1889
    $annotations = cdm_ws_fetch_annotations($annotatable_entity);
1890
    if (is_array($annotations)) {
1891
      $annotatable_entity->annotations = $annotations;
1892
    }
1893
  }
1894
}
1895

    
1896
function cdm_load_tagged_full_title($taxon_name){
1897
  if(isset($taxon_name) && !isset($taxon_name->taggedFullTitle)){
1898
    $tagged_full_title = cdm_ws_get(CDM_WS_NAME, array($taxon_name->uuid, 'taggedFullTitle'));
1899
    if(is_array($tagged_full_title)){
1900
      $taxon_name->taggedFullTitle = $tagged_full_title;
1901

    
1902
    }
1903
  }
1904
}
1905

    
1906
/**
1907
 * Extends the $cdm_entity object by the field if it is not already existing.
1908
 *
1909
 * This function can only be used for fields with 1 to many relations.
1910
  *
1911
 * @param $cdm_base_type
1912
 * @param $field_name
1913
 * @param $cdm_entity
1914
 */
1915
function cdm_lazyload_array_field($cdm_base_type, $field_name, &$cdm_entity)
1916
{
1917
  if (!isset($cdm_entity->$field_name)) {
1918
    $items = cdm_ws_fetch_all('portal/' . $cdm_base_type . '/' . $cdm_entity->uuid . '/' . $field_name);
1919
    $cdm_entity->$field_name = $items;
1920
  }
1921
}
1922

    
1923

    
1924
/**
1925
 * Get a NomenclaturalReference string.
1926
 *
1927
 * Returns the NomenclaturalReference string with correctly placed
1928
 * microreference (= reference detail) e.g.
1929
 * in Phytotaxa 43: 1-48. 2012.
1930
 *
1931
 * @param string $referenceUuid
1932
 *   UUID of the reference.
1933
 * @param string $microreference
1934
 *   Reference detail.
1935
 *
1936
 * @return string
1937
 *   a NomenclaturalReference.
1938
 */
1939
function cdm_ws_getNomenclaturalReference($referenceUuid, $microreference) {
1940

    
1941
  // TODO the below statement avoids error boxes due to #4644 remove it once this ticket is solved
1942
  if(is_array($microreference) || is_object($microreference)) {
1943
    return '';
1944
  }
1945

    
1946
  $obj = cdm_ws_get(CDM_WS_NOMENCLATURAL_REFERENCE_CITATION, array(
1947
    $referenceUuid,
1948
  ), "microReference=" . urlencode($microreference));
1949

    
1950
  if ($obj) {
1951
    return $obj->String;
1952
  }
1953
  else {
1954
    return NULL;
1955
  }
1956
}
1957

    
1958
/**
1959
 * finds and returns the FeatureNode denoted by the given $feature_uuid
1960
 *
1961
 * @param $feature_tree_nodes
1962
 *    The nodes contained in CDM FeatureTree entitiy: $feature->root->childNodes
1963
 * @param $feature_uuid
1964
 *    The UUID of the Feature
1965
 * @return object
1966
 *    the FeatureNode or null
1967
 */
1968
function &cdm_feature_tree_find_node($feature_tree_nodes, $feature_uuid){
1969

    
1970
  // 1. scan this level
1971
  foreach ($feature_tree_nodes as $node){
1972
    if($node->term->uuid == $feature_uuid){
1973
      return $node;
1974
    }
1975
  }
1976

    
1977
  // 2. descend into childen
1978
  foreach ($feature_tree_nodes as $node){
1979
    if(is_array($node->childNodes)){
1980
      $node = cdm_feature_tree_find_node($node->childNodes, $feature_uuid);
1981
      if($node) {
1982
        return $node;
1983
      }
1984
    }
1985
  }
1986
  $null_var = null; // kludgy workaround to avoid "PHP Notice: Only variable references should be returned by reference"
1987
  return $null_var;
1988
}
1989

    
1990
/**
1991
 * Merges the given featureNodes structure with the descriptionElements.
1992
 *
1993
 * This method is used in preparation for rendering the descriptionElements.
1994
 * The descriptionElements which belong to a specific feature node are appended
1995
 * to a the feature node by creating a new field:
1996
 *  - descriptionElements: the CDM DescriptionElements which belong to this feature
1997
 * The descriptionElements will be cleared in advance in order to allow reusing the
1998
 * same feature tree without the risk of mixing sets of description elements.
1999
 *
2000
 * which originally is not existing in the cdm.
2001
 *
2002
 *
2003
 *
2004
 * @param array $featureNodes
2005
 *    An array of cdm FeatureNodes which may be hierarchical since feature nodes
2006
 *    may have children.
2007
 * @param array $descriptionElements
2008
 *    An flat array of cdm DescriptionElements
2009
 * @return array
2010
 *    The $featureNodes structure enriched with the according $descriptionElements
2011
 */
2012
function _mergeFeatureTreeDescriptions($featureNodes, $descriptionElements) {
2013

    
2014
  foreach ($featureNodes as &$feature_node) {
2015
    // since the $featureNodes array is reused for each description
2016
    // it is necessary to clear the custom node fields in advance
2017
    if(isset($feature_node->descriptionElements)){
2018
      unset($feature_node->descriptionElements);
2019
    }
2020

    
2021
    // Append corresponding elements to an additional node field:
2022
    // $node->descriptionElements.
2023
    foreach ($descriptionElements as $element) {
2024
      if ($element->feature->uuid == $feature_node->term->uuid) {
2025
        if (!isset($feature_node->descriptionElements)) {
2026
          $feature_node->descriptionElements = array();
2027
        }
2028
        $feature_node->descriptionElements[] = $element;
2029
      }
2030
    }
2031

    
2032
    // Recurse into node children.
2033
    if (isset($feature_node->childNodes[0])) {
2034
      $mergedChildNodes = _mergeFeatureTreeDescriptions($feature_node->childNodes, $descriptionElements);
2035
      $feature_node->childNodes = $mergedChildNodes;
2036
    }
2037

    
2038
    if(!isset($feature_node->descriptionElements) && !isset($feature_node->childNodes[0])){
2039
      unset($feature_node);
2040
    }
2041

    
2042
  }
2043

    
2044
  return $featureNodes;
2045
}
2046

    
2047
/**
2048
 * Sends a GET or POST request to a CDM RESTService and returns a de-serialized object.
2049
 *
2050
 * The response from the HTTP GET request is returned as object.
2051
 * The response objects coming from the webservice configured in the
2052
 * 'cdm_webservice_url' variable are being cached in a level 1 (L1) and / or
2053
 *  in a level 2 (L2) cache.
2054
 *
2055
 * Since the L1 cache is implemented as static variable of the cdm_ws_get()
2056
 * function, this cache persists only per each single page execution.
2057
 * Any object coming from the webservice is stored into it by default.
2058
 * In contrast to this default caching mechanism the L2 cache only is used if
2059
 * the 'cdm_webservice_cache' variable is set to TRUE,
2060
 * which can be set using the modules administrative settings section.
2061
 * Objects stored in this L2 cache are serialized and stored
2062
 * using the drupal cache in the '{prefix}cache_cdm_ws' cache table. So the
2063
 * objects that are stored in the database will persist as
2064
 * long as the drupal cache is not being cleared and are available across
2065
 * multiple script executions.
2066
 *
2067
 * @param string $uri
2068
 *   URL to the webservice.
2069
 * @param array $pathParameters
2070
 *   An array of path parameters.
2071
 * @param string $query_string
2072
 *   A query_string string to be appended to the URL.
2073
 * @param string $method
2074
 *   The HTTP method to use, valid values are "GET" or "POST";
2075
 * @param bool $absoluteURI
2076
 *   TRUE when the URL should be treated as absolute URL.
2077
 *
2078
 * @return object| array
2079
 *   The de-serialized webservice response object.
2080
 */
2081
function cdm_ws_get($uri, $pathParameters = array(), $query_string = NULL, $method = "GET", $absoluteURI = FALSE) {
2082

    
2083
  static $cacheL1 = array();
2084

    
2085
  $data = NULL;
2086
  // store query_string string in $data and clear the query_string, $data will be set as HTTP request body
2087
  if($method == 'POST'){
2088
    $data = $query_string;
2089
    $query_string = NULL;
2090
  }
2091

    
2092
  // Transform the given uri path or pattern into a proper webservice uri.
2093
  if (!$absoluteURI) {
2094
    $uri = cdm_compose_ws_url($uri, $pathParameters, $query_string);
2095
  } else {
2096
    if($query_string){
2097
      $uri = append_query_parameters($uri, $query_string);
2098
    }
2099
  }
2100
  cdm_ws_apply_classification_subtree_filter($uri);
2101

    
2102
  // read request parameter 'cacheL2_refresh'
2103
  // which allows refreshing the level 2 cache
2104
  $do_cacheL2_refresh = isset($_REQUEST['cacheL2_refresh']) && $_REQUEST['cacheL2_refresh'] == 1;
2105

    
2106
  $is_cdm_ws_uri = _is_cdm_ws_uri($uri);
2107
  $use_cacheL2 = variable_get('cdm_webservice_cache', 1);
2108

    
2109
  if($method == 'GET'){
2110
    $cache_key = $uri;
2111
  } else {
2112
    // sha1 creates longer hashes and thus will cause fewer collisions than md5.
2113
    // crc32 is faster but creates much shorter hashes
2114
    $cache_key = $uri . '[' . $method . ':' . sha1($data) .']';
2115
  }
2116

    
2117
  if (array_key_exists($cache_key, $cacheL1)) {
2118
    $cacheL1_obj = $cacheL1[$uri];
2119
  }
2120

    
2121
  $set_cacheL1 = FALSE;
2122
  if ($is_cdm_ws_uri && !isset($cacheL1_obj)) {
2123
    $set_cacheL1 = TRUE;
2124
  }
2125

    
2126
  // Only cache cdm webservice URIs.
2127
  $set_cacheL2 = $use_cacheL2 && $is_cdm_ws_uri && $set_cacheL1;
2128
  $cacheL2_entry = FALSE;
2129

    
2130
  if ($use_cacheL2 && !$do_cacheL2_refresh) {
2131
    // Try to get object from cacheL2.
2132
    $cacheL2_entry = cache_get($cache_key, 'cache_cdm_ws');
2133
  }
2134

    
2135
  if (isset($cacheL1_obj)) {
2136
    //
2137
    // The object has been found in the L1 cache.
2138
    //
2139
    $obj = $cacheL1_obj;
2140
    if (cdm_debug_block_visible()) {
2141
      cdm_ws_debug_add($uri, $method, $data, 0, 0, NULL, 'cacheL1');
2142
    }
2143
  }
2144
  elseif ($cacheL2_entry) {
2145
    //
2146
    // The object has been found in the L2 cache.
2147
    //
2148
    $duration_parse_start = microtime(TRUE);
2149
    $obj = unserialize($cacheL2_entry->data);
2150
    $duration_parse = microtime(TRUE) - $duration_parse_start;
2151

    
2152
    if (cdm_debug_block_visible()) {
2153
      cdm_ws_debug_add($uri, $method, $data, 0, $duration_parse, NULL, 'cacheL2');
2154
    }
2155
  }
2156
  else {
2157
    //
2158
    // Get the object from the webservice and cache it.
2159
    //
2160
    $duration_fetch_start = microtime(TRUE);
2161
    // Request data from webservice JSON or XML.
2162
    $response = cdm_http_request($uri, $method, $data);
2163
    $response_body = NULL;
2164
    if (isset($response->data)) {
2165
      $response_body = $response->data;
2166
    }
2167
    $duration_fetch = microtime(TRUE) - $duration_fetch_start;
2168
    $duration_parse_start = microtime(TRUE);
2169

    
2170
    // Parse data and create object.
2171
    $obj = cdm_load_obj($response_body);
2172

    
2173
    if(isset($obj->servlet) && isset($obj->status) && is_numeric($obj->status)){
2174
      // this is json error message returned by jetty #8914
2175
      // wee need to replace it by null to avoid breaking existing assumptions in the code here
2176
      // this is also related to #2711
2177
      $obj = null;
2178
    }
2179

    
2180
    $duration_parse = microtime(TRUE) - $duration_parse_start;
2181

    
2182
    if (cdm_debug_block_visible()) {
2183
      if ($obj || $response_body == "[]") {
2184
        $status = 'valid';
2185
      }
2186
      else {
2187
        $status = 'invalid';
2188
      }
2189
      cdm_ws_debug_add($uri, $method, $data, $duration_fetch, $duration_parse, strlen($response_body), $status);
2190
    }
2191
    if ($set_cacheL2) {
2192
      // Store the object in cache L2.
2193
      // Comment @WA perhaps better if Drupal serializedatas here? Then the
2194
      // flag serialized is set properly in the cache table.
2195
      cache_set($cache_key, serialize($obj), 'cache_cdm_ws', CACHE_TEMPORARY);
2196
    }
2197
  }
2198
  if ($obj) {
2199
    // Store the object in cache L1.
2200
    if ($set_cacheL1) {
2201
      $cacheL1[$cache_key] = $obj;
2202
    }
2203
  }
2204
  return $obj;
2205
}
2206

    
2207
function cdm_ws_apply_classification_subtree_filter(&$uri){
2208

    
2209
  $classification_subtree_filter_patterns = &drupal_static('classification_subtree_filter_patterns', array(
2210
    "#/classification/[0-9a-f\-]{36}/childNodes#",
2211
    /* covered by above pattern:
2212
    "#/classification/[0-9a-f\-]{36}/childNodesAt/[0-9a-f\-]{36}#",
2213
    '#/classification/[0-9a-f\-]{36}/childNodesOf/[0-9a-f\-]{36}#',
2214
    */
2215
    "#/portal/classification/[0-9a-f\-]{36}/childNodes#",
2216
    /* covered by above pattern:
2217
    "#/portal/classification/[0-9a-f\-]{36}/childNodesAt/[0-9a-f\-]{36}#",
2218
    '#/portal/classification/[0-9a-f\-]{36}/childNodesOf/[0-9a-f\-]{36}#',
2219
    */
2220
    '#/portal/classification/[0-9a-f\-]{36}/pathFrom/[0-9a-f\-]{36}#',
2221
    "#/portal/taxon/search#",
2222
    "#/portal/taxon/find#",
2223
    /* covered by above pattern:
2224
    "#/portal/taxon/findByDescriptionElementFullText#",
2225
    "#/portal/taxon/findByFullText#",
2226
    "#/portal/taxon/findByEverythingFullText#",
2227
    "#/portal/taxon/findByIdentifier#",
2228
    "#/portal/taxon/findByMarker#",
2229
    "#/portal/taxon/findByMarker#",
2230
    "#/portal/taxon/findByMarker#",
2231
    */
2232
    "#/portal/taxon/[0-9a-f\-]{36}#"
2233
    /* covered by above pattern:
2234
    "#/portal/taxon/[0-9a-f\-]{36}/taxonNodes#",
2235
    */
2236
  ));
2237

    
2238
  $sub_tree_filter_uuid_value = variable_get(CDM_SUB_TREE_FILTER_UUID, FALSE);
2239
  if(is_uuid($sub_tree_filter_uuid_value)){
2240
    foreach($classification_subtree_filter_patterns as $preg_pattern){
2241
      if(preg_match($preg_pattern, $uri)){
2242
        // no need to take care for uri fragments with ws uris!
2243
        if(strpos( $uri, '?')){
2244
          $uri .= '&subtree=' . $sub_tree_filter_uuid_value;
2245
        } else {
2246
          $uri .= '?subtree='. $sub_tree_filter_uuid_value;
2247
        }
2248
        break;
2249
      }
2250
    }
2251
  }
2252

    
2253
}
2254
/**
2255
 * Processes and stores the given information in $_SESSION['cdm']['ws_debug'] as table row.
2256
 *
2257
 * The cdm_ws_debug block will display the debug information.
2258
 *
2259
 * @param $uri
2260
 *    The CDM REST URI to which the request has been send
2261
 * @param string $method
2262
 *    The HTTP request method, either 'GET' or 'POST'
2263
 * @param string $post_data
2264
 *    The datastring send with a post request
2265
 * @param $duration_fetch
2266
 *    The time in seconds it took to fetch the data from the web service
2267
 * @param $duration_parse
2268
 *    Time in seconds which was needed to parse the json response
2269
 * @param $datasize
2270
 *    Size of the data received from the server
2271
 * @param $status
2272
 *    A status string, possible values are: 'valid', 'invalid', 'cacheL1', 'cacheL2'
2273
 * @return bool
2274
 *    TRUE if adding the debug information was successful
2275
 */
2276
function cdm_ws_debug_add($uri, $method, $post_data, $duration_fetch, $duration_parse, $datasize, $status) {
2277

    
2278
  static $initial_time = NULL;
2279
  if(!$initial_time) {
2280
    $initial_time = microtime(TRUE);
2281
  }
2282
  $time = microtime(TRUE) - $initial_time;
2283

    
2284
  // Decompose uri into path and query element.
2285
  $uri_parts = explode("?", $uri);
2286
  $query = array();
2287
  if (count($uri_parts) == 2) {
2288
    $path = $uri_parts[0];
2289
  }
2290
  else {
2291
    $path = $uri;
2292
  }
2293

    
2294
  if(strpos($uri, '?') > 0){
2295
    $json_uri = str_replace('?', '.json?', $uri);
2296
    $xml_uri = str_replace('?', '.xml?', $uri);
2297
  } else {
2298
    $json_uri = $uri . '.json';
2299
    $xml_uri = $json_uri . '.xml';
2300
  }
2301

    
2302
  // data links to make data accecsible as json and xml
2303
  $data_links = '';
2304
  if (_is_cdm_ws_uri($path)) {
2305

    
2306
    // see ./js/http-method-link.js
2307

    
2308
    if($method == 'GET'){
2309
      $data_links .= '<a href="' . $xml_uri . '" target="data">xml</a>-';
2310
      $data_links .= '<a href="' . url('cdm_api/proxy/' . urlencode($xml_uri)) . '" target="data">proxied</a>';
2311
      $data_links .= '<br/>';
2312
      $data_links .= '<a href="' . $json_uri . '" target="data">json</a>-';
2313
      $data_links .= '<a href="' . url('cdm_api/proxy/' . urlencode($json_uri)) . '" target="data">proxied</a>';
2314
    } else {
2315
      $js_link_activation = 'class="http-' . $method . '-link" data-cdm-http-post="' . $post_data . '" type="application/x-www-form-urlencoded"';
2316
      $data_links .= '<a ' . $js_link_activation . ' href="' . url('cdm_api/proxy/' . urlencode($xml_uri)) . '" target="data">xml-proxied</a>';
2317
      $data_links .= '<br/>';
2318
      $data_links .= '<a ' . $js_link_activation . ' href="' . url('cdm_api/proxy/' . urlencode($json_uri)) . '" target="data">json-proxied</a>';
2319
    }
2320
  }
2321
  else {
2322
    $data_links .= '<a href="' . $uri . '" target="data">open</a>';
2323
  }
2324

    
2325
  //
2326
  $data = array(
2327
      'ws_uri' => $uri,
2328
      'method' => $method,
2329
      'post_data' => $post_data,
2330
      'time' => sprintf('%3.3f', $time),
2331
      'fetch_seconds' => sprintf('%3.3f', $duration_fetch),
2332
      'parse_seconds' => sprintf('%3.3f', $duration_parse),
2333
      'size_kb' => sprintf('%3.1f', ($datasize / 1024)) ,
2334
      'status' => $status,
2335
      'data_links' => $data_links
2336
  );
2337
  if (!isset($_SESSION['cdm']['ws_debug'])) {
2338
    $_SESSION['cdm']['ws_debug'] = array();
2339
  }
2340
  $_SESSION['cdm']['ws_debug'][] = serialize($data);
2341

    
2342
  // Mark this page as being uncacheable.
2343
  // taken over from drupal_get_messages() but it is unsure if we really need this here
2344
  drupal_page_is_cacheable(FALSE);
2345

    
2346
  // Messages not set when DB connection fails.
2347
  return isset($_SESSION['cdm']['ws_debug']) ? $_SESSION['cdm']['ws_debug'] : NULL;
2348
}
2349

    
2350
/**
2351
 * helper function to dtermine if the cdm_debug_block should be displayed or not
2352
 * the visibility depends on whether
2353
 *  - the block is enabled
2354
 *  - the visibility restrictions in the block settings are satisfied
2355
 */
2356
function cdm_debug_block_visible() {
2357
  static $is_visible = null;
2358

    
2359
  if($is_visible === null){
2360
      $block = block_load('cdm_api', 'cdm_ws_debug');
2361
      $is_visible = isset($block->status) && $block->status == 1;
2362
      if($is_visible){
2363
        $blocks = array($block);
2364
        // Checks the page, user role, and user-specific visibilty settings.
2365
        block_block_list_alter($blocks);
2366
        $is_visible = count($blocks) > 0;
2367
      }
2368
  }
2369
  return $is_visible;
2370
}
2371

    
2372
/**
2373
 * @todo Please document this function.
2374
 * @see http://drupal.org/node/1354
2375
 */
2376
function cdm_load_obj($response_body) {
2377
  $obj = json_decode($response_body);
2378

    
2379
  if (!(is_object($obj) || is_array($obj))) {
2380
    ob_start();
2381
    $obj_dump = ob_get_contents();
2382
    ob_clean();
2383
    return FALSE;
2384
  }
2385

    
2386
  return $obj;
2387
}
2388

    
2389
/**
2390
 * Do a http request to a CDM RESTful web service.
2391
 *
2392
 * @param string $uri
2393
 *   The webservice url.
2394
 * @param string $method
2395
 *   The HTTP method to use, valid values are "GET" or "POST"; defaults to
2396
 *   "GET" even if NULL, FALSE or any invalid value is supplied.
2397
 * @param $data: A string containing the request body, formatted as
2398
 *     'param=value&param=value&...'. Defaults to NULL.
2399
 *
2400
 * @return object
2401
 *   The object as returned by drupal_http_request():
2402
 *   An object that can have one or more of the following components:
2403
 *   - request: A string containing the request body that was sent.
2404
 *   - code: An integer containing the response status code, or the error code
2405
 *     if an error occurred.
2406
 *   - protocol: The response protocol (e.g. HTTP/1.1 or HTTP/1.0).
2407
 *   - status_message: The status message from the response, if a response was
2408
 *     received.
2409
 *   - redirect_code: If redirected, an integer containing the initial response
2410
 *     status code.
2411
 *   - redirect_url: If redirected, a string containing the URL of the redirect
2412
 *     target.
2413
 *   - error: If an error occurred, the error message. Otherwise not set.
2414
 *   - headers: An array containing the response headers as name/value pairs.
2415
 *     HTTP header names are case-insensitive (RFC 2616, section 4.2), so for
2416
 *     easy access the array keys are returned in lower case.
2417
 *   - data: A string containing the response body that was received.
2418
 */
2419
function cdm_http_request($uri, $method = "GET", $data = NULL) {
2420
  static $acceptLanguage = NULL;
2421
  $header = array();
2422
  
2423
  if(!$acceptLanguage && module_exists('i18n')){
2424
    $acceptLanguage = i18n_language_content()->language;
2425
  }
2426

    
2427
  if (!$acceptLanguage) {
2428
    if (function_exists('apache_request_headers')) {
2429
      $headers = apache_request_headers();
2430
      if (isset($headers['Accept-Language'])) {
2431
        $acceptLanguage = $headers['Accept-Language'];
2432
      }
2433
    }
2434
  }
2435

    
2436
  if ($method != "GET" && $method != "POST") {
2437
    drupal_set_message('cdm_api.module#cdm_http_request() : unsupported HTTP request method ', 'error');
2438
  }
2439

    
2440
  if (_is_cdm_ws_uri($uri)) {
2441
    $header['Accept'] = 'application/json';
2442
    $header['Accept-Language'] = $acceptLanguage;
2443
    $header['Accept-Charset'] = 'UTF-8';
2444
  }
2445

    
2446
  if($method == "POST") {
2447
    // content type is application/x-www-form-urlencoded, so the request body uses the same format as the query string
2448
    $header['Content-Type'] = 'application/x-www-form-urlencoded';
2449
  }
2450

    
2451

    
2452
  cdm_dd($uri);
2453
  return drupal_http_request($uri, array(
2454
      'headers' => $header,
2455
      'method' => $method,
2456
      'data' => $data,
2457
      'timeout' => CDM_HTTP_REQUEST_TIMEOUT
2458
      )
2459
   );
2460
}
2461

    
2462
/**
2463
 * Concatenates recursively the fields of all features contained in the given
2464
 * CDM FeatureTree root node.
2465
 *
2466
 * @param $rootNode
2467
 *     A CDM FeatureTree node
2468
 * @param
2469
 *     The character to be used as glue for concatenation, default is ', '
2470
 * @param $field_name
2471
 *     The field name of the CDM Features
2472
 * @param $excludes
2473
 *     Allows defining a set of values to be excluded. This refers to the values
2474
 *     in the field denoted by the $field_name parameter
2475
 *
2476
 */
2477
function cdm_featureTree_elements_toString($root_node, $separator = ', ', $field_name = 'representation_L10n', $excludes = array()) {
2478
  $out = '';
2479

    
2480
  $pre_child_separator = $separator;
2481
  $post_child_separator = '';
2482

    
2483
  foreach ($root_node->childNodes as $feature_node) {
2484
    $out .= ($out ? $separator : '');
2485
    if(!in_array($feature_node->term->$field_name, $excludes)) {
2486
      $out .= $feature_node->term->$field_name;
2487
      if (is_array($feature_node->childNodes) && count($feature_node->childNodes) > 0) {
2488
        $childlabels = cdm_featureTree_elements_toString($feature_node, $separator, $field_name);
2489
        if (strlen($childlabels)) {
2490
            $out .=  $pre_child_separator . $childlabels . $post_child_separator;
2491
        }
2492
      }
2493
    }
2494
  }
2495
  return $out;
2496
}
2497

    
2498
/**
2499
 * Create a one-dimensional form options array.
2500
 *
2501
 * Creates an array of all features in the feature tree of feature nodes,
2502
 * the node labels are indented by $node_char and $childIndent depending on the
2503
 * hierachy level.
2504
 *
2505
 * @param - $rootNode
2506
 * @param - $node_char
2507
 * @param - $childIndentStr
2508
 * @param - $childIndent
2509
 *   ONLY USED INTERNALLY!
2510
 *
2511
 * @return array
2512
 *   A one dimensional Drupal form options array.
2513
 */
2514
function _featureTree_nodes_as_feature_options($rootNode, $node_char = "&#9500;&#9472; ", $childIndentStr = '&nbsp;', $childIndent = '') {
2515
  $options = array();
2516
  foreach ($rootNode->childNodes as $featureNode) {
2517
    $indent_prefix = '';
2518
    if ($childIndent) {
2519
      $indent_prefix = $childIndent . $node_char . " ";
2520
    }
2521
    $options[$featureNode->term->uuid] = $indent_prefix . $featureNode->term->representation_L10n;
2522
    if (isset($featureNode->childNodes) && is_array($featureNode->childNodes)) {
2523
      // Foreach ($featureNode->childNodes as $childNode){
2524
      $childList = _featureTree_nodes_as_feature_options($featureNode, $node_char, $childIndentStr, $childIndent . $childIndentStr);
2525
      $options = array_merge_recursive($options, $childList);
2526
      // }
2527
    }
2528
  }
2529
  return $options;
2530
}
2531

    
2532
/**
2533
 * Returns an array with all available FeatureTrees and the representations of the selected
2534
 * FeatureTree as a detail view.
2535
 *
2536
 * @param boolean $add_default_feature_free
2537
 * @param boolean $show_weight
2538
 *     Show the weight which will be applied to the according feature block
2539
 * @return array
2540
 *  associative array with following keys:
2541
 *  -options: Returns an array with all available Feature Trees
2542
 *  -treeRepresentations: Returns representations of the selected Feature Tree as a detail view
2543
 *
2544
 */
2545
function cdm_get_featureTrees_as_options($add_default_feature_free = FALSE, $show_weight = FALSE) {
2546

    
2547
  $options = array();
2548
  $tree_representations = array();
2549
  $feature_trees = array();
2550

    
2551
  // Set tree that contains all features.
2552
  if ($add_default_feature_free) {
2553
    $options[UUID_DEFAULT_FEATURETREE] = t('Default Featuretree (contains all features)');
2554
    $feature_trees[] = cdm_ws_get(CDM_WS_TERMTREE, UUID_DEFAULT_FEATURETREE);
2555
  }
2556

    
2557
  // Get feature trees from database.
2558
  $persited_trees = cdm_ws_fetch_all(CDM_WS_TERMTREES, array("termType" => "Feature"));
2559
  if (is_array($persited_trees)) {
2560
    $feature_trees = array_merge($feature_trees, $persited_trees);
2561
  }
2562

    
2563
  foreach ($feature_trees as $featureTree) {
2564

    
2565
    if(!is_object($featureTree)){
2566
      continue;
2567
    }
2568
    // Do not add the DEFAULT_FEATURETREE again,
2569
    if ($featureTree->uuid != UUID_DEFAULT_FEATURETREE) {
2570
      $options[$featureTree->uuid] = $featureTree->representation_L10n;
2571
    }
2572

    
2573
    // Render the hierarchic tree structure
2574
    if (is_array( $featureTree->root->childNodes) && count( $featureTree->root->childNodes) > 0) {
2575

    
2576
      // Render the hierarchic tree structure.
2577
      $treeDetails = '<div class="featuretree_structure">'
2578
        . render_feature_tree_hierarchy($featureTree->uuid, $show_weight)
2579
        . '</div>';
2580

    
2581
      $form = array();
2582
      $form['featureTree-' .  $featureTree->uuid] = array(
2583
        '#type' => 'fieldset',
2584
        '#title' => 'Show details',
2585
        '#attributes' => array('class' => array('collapsible collapsed')),
2586
        // '#collapsible' => TRUE,
2587
        // '#collapsed' => TRUE,
2588
      );
2589
      $form['featureTree-' .  $featureTree->uuid]['details'] = array(
2590
        '#markup' => $treeDetails,
2591
      );
2592

    
2593
      $tree_representations[$featureTree->uuid] = drupal_render($form);
2594
    }
2595

    
2596
  } // END loop over feature trees
2597

    
2598
  // return $options;
2599
  return array('options' => $options, 'treeRepresentations' => $tree_representations);
2600
}
2601

    
2602
/**
2603
 * Provides the list of available classifications in form of an options array.
2604
 *
2605
 * The options array is suitable for drupal form API elements that allow multiple choices.
2606
 * @see http://api.drupal.org/api/drupal/developer!topics!forms_api_reference.html/7#options
2607
 *
2608
 * The classifications are ordered alphabetically whereas the classification
2609
 * chosen as default will always appear on top of the array, followed by a
2610
 * blank line below.
2611
 *
2612
 * @param bool $add_none_option
2613
 *   is true an additional 'none' option will be added if and only if there are
2614
 *   more than one options. Defaults to FALSE
2615
 *
2616
 * @param $include_uuids
2617
 *   The taxon tree uuids to be included, other taxon trees will be filtered out.
2618
 *   You may want to use here:
2619
 *   variable_get(CDM_TAXONTREE_INCLUDES, [])
2620
 *
2621
 *
2622
 * @return array
2623
 *   classifications in an array as options for a form element that allows multiple choices.
2624
 */
2625
function cdm_get_taxontrees_as_options($add_none_option = FALSE, $include_uuids = []) {
2626

    
2627
  $taxonTrees = cdm_ws_fetch_all(CDM_WS_PORTAL_TAXONOMY);
2628

    
2629
  $default_classification_uuid = variable_get(CDM_TAXONOMICTREE_UUID, FALSE);
2630
  $default_classification_label = '';
2631

    
2632
  // add all classifications
2633
  $taxonomic_tree_options = array();
2634
  if ($add_none_option) {
2635
    $taxonomic_tree_options['NONE'] = ' '; // one Space character at beginning to force on top;
2636
  }
2637
  if ($taxonTrees) {
2638
    foreach ($taxonTrees as $tree) {
2639
      if(is_array($include_uuids) && count($include_uuids) > 0 && array_search($tree->uuid, $include_uuids) === FALSE){
2640
        continue;
2641
      }
2642
      if (!$default_classification_uuid || $default_classification_uuid != $tree->uuid) {
2643
        $taxonomic_tree_options[$tree->uuid] = $tree->titleCache;
2644
      } else {
2645
        $taxonomic_tree_options[$tree->uuid] = '  '; // two Space characters to force on top but below 'none' option , will be replaced below by titleCache
2646
        $default_classification_label = $tree->titleCache;
2647
      }
2648
    }
2649
  }
2650
  // oder alphabetically the space
2651
  asort($taxonomic_tree_options);
2652

    
2653
  // now set the labels for none
2654
  if ($add_none_option && count($taxonomic_tree_options) > 2) {
2655
    $taxonomic_tree_options['NONE'] =t('--- ALL ---');
2656
  } else {
2657
    unset($taxonomic_tree_options['NONE']);
2658
  }
2659

    
2660
  //   for default_classification
2661
  if (is_uuid($default_classification_uuid)) {
2662
    $taxonomic_tree_options[$default_classification_uuid] =
2663
      $default_classification_label ? $default_classification_label : '--- INVALID CHOICE ---'
2664
      . (count($taxonTrees) > 1 ? ' [' . t('DEFAULT CLASSIFICATION') . ']': '');
2665
  }
2666

    
2667
  return $taxonomic_tree_options;
2668
}
2669

    
2670
/**
2671
 * @todo Please document this function.
2672
 * @see http://drupal.org/node/1354
2673
 */
2674
function cdm_api_secref_cache_prefetch(&$secUuids) {
2675
  // Comment @WA: global variables should start with a single underscore
2676
  // followed by the module and another underscore.
2677
  global $_cdm_api_secref_cache;
2678
  if (!is_array($_cdm_api_secref_cache)) {
2679
    $_cdm_api_secref_cache = array();
2680
  }
2681
  $uniqueUuids = array_unique($secUuids);
2682
  $i = 0;
2683
  $param = '';
2684
  while ($i++ < count($uniqueUuids)) {
2685
    $param .= $secUuids[$i] . ',';
2686
    if (strlen($param) + 37 > 2000) {
2687
      _cdm_api_secref_cache_add($param);
2688
      $param = '';
2689
    }
2690
  }
2691
  if ($param) {
2692
    _cdm_api_secref_cache_add($param);
2693
  }
2694
}
2695

    
2696
/**
2697
 * @todo Please document this function.
2698
 * @see http://drupal.org/node/1354
2699
 */
2700
function cdm_api_secref_cache_get($secUuid) {
2701
  global $_cdm_api_secref_cache;
2702
  if (!is_array($_cdm_api_secref_cache)) {
2703
    $_cdm_api_secref_cache = array();
2704
  }
2705
  if (!array_key_exists($secUuid, $_cdm_api_secref_cache)) {
2706
    _cdm_api_secref_cache_add($secUuid);
2707
  }
2708
  return $_cdm_api_secref_cache[$secUuid];
2709
}
2710

    
2711
/**
2712
 * @todo Please document this function.
2713
 * @see http://drupal.org/node/1354
2714
 */
2715
function cdm_api_secref_cache_clear() {
2716
  global $_cdm_api_secref_cache;
2717
  $_cdm_api_secref_cache = array();
2718
}
2719

    
2720

    
2721
/**
2722
 * @todo Please document this function.
2723
 * @see http://drupal.org/node/1354
2724
 */
2725
function _cdm_api_secref_cache_add($secUuidsStr) {
2726
  global $_cdm_api_secref_cache;
2727
  $ref = cdm_ws_get(CDM_WS_REFERENCE, $secUuidsStr);
2728
  // Batch fetching not jet reimplemented thus:
2729
  /*
2730
  $assocRefSTOs = array(); if($refSTOs) { foreach($refSTOs as $ref){
2731
  $assocRefSTOs[$ref->uuid] = $ref; } $_cdm_api_secref_cache =
2732
  array_merge($_cdm_api_secref_cache, $assocRefSTOs); }
2733
  */
2734
  $_cdm_api_secref_cache[$ref->uuid] = $ref;
2735
}
2736

    
2737
/**
2738
 * Checks if the given uri starts with a cdm webservice url.
2739
 *
2740
 * Checks if the uri starts with the cdm webservice url stored in the
2741
 * Drupal variable 'cdm_webservice_url'.
2742
 * The 'cdm_webservice_url' can be set in the admins section of the portal.
2743
 *
2744
 * @param string $uri
2745
 *   The URI to test.
2746
 *
2747
 * @return bool
2748
 *   True if the uri starts with a cdm webservice url.
2749
 */
2750
function _is_cdm_ws_uri($uri) {
2751
  return str_beginsWith($uri, variable_get('cdm_webservice_url', '#EMPTY#'));
2752
}
2753

    
2754
/**
2755
 * @todo Please document this function.
2756
 * @see http://drupal.org/node/1354
2757
 */
2758
function queryString($elements) {
2759
  $query = '';
2760
  foreach ($elements as $key => $value) {
2761
    if (is_array($value)) {
2762
      foreach ($value as $v) {
2763
        $query .= (strlen($query) > 0 ? '&' : '') . $key . '=' . urlencode($v);
2764
      }
2765
    }
2766
    else {
2767
      $query .= (strlen($query) > 0 ? '&' : '') . $key . '=' . urlencode($value);
2768
    }
2769
  }
2770
  return $query;
2771
}
2772

    
2773
/**
2774
 * Compares the given CDM Term instances by the  representationL10n.
2775
 *
2776
 * Can also be used with TermDTOs. To be used in usort()
2777
 *
2778
 * @see http://php.net/manual/en/function.usort.php
2779
 *
2780
 * @param $term1
2781
 *   The first CDM Term instance
2782
 * @param $term2
2783
 *   The second CDM Term instance
2784
 * @return int
2785
 *   The result of the comparison
2786
 */
2787
function compare_terms_by_representationL10n($term1, $term2) {
2788

    
2789
  if (!isset($term1->representation_L10n)) {
2790
    $term1->representationL10n = '';
2791
  }
2792
  if (!isset($term2->representation_L10n)) {
2793
    $term2->representationL10n = '';
2794
  }
2795

    
2796
  return strcmp($term1->representation_L10n, $term2->representation_L10n);
2797
}
2798

    
2799
function compare_terms_by_order_index($term1, $term2) {
2800

    
2801

    
2802
  if (!isset($term1->orderIndex)) {
2803
    $a = 0;
2804
  } else {
2805
    $a = $term1->orderIndex;
2806
  }
2807
  if (!isset($term2->orderIndex)) {
2808
    $b = 0;
2809
  } else {
2810
    $b = $term2->orderIndex;
2811
  }
2812

    
2813
  if ($a == $b) {
2814
    return 0;
2815
  }
2816
  return ($a < $b) ? -1 : 1;
2817

    
2818
}
2819

    
2820

    
2821
/**
2822
 * Make a 'deep copy' of an array.
2823
 *
2824
 * Make a complete deep copy of an array replacing
2825
 * references with deep copies until a certain depth is reached
2826
 * ($maxdepth) whereupon references are copied as-is...
2827
 *
2828
 * @see http://us3.php.net/manual/en/ref.array.php
2829
 *
2830
 * @param array $array
2831
 * @param array $copy passed by reference
2832
 * @param int $maxdepth
2833
 * @param int $depth
2834
 */
2835
function array_deep_copy(&$array, &$copy, $maxdepth = 50, $depth = 0) {
2836
  if ($depth > $maxdepth) {
2837
    $copy = $array;
2838
    return;
2839
  }
2840
  if (!is_array($copy)) {
2841
    $copy = array();
2842
  }
2843
  foreach ($array as $k => &$v) {
2844
    if (is_array($v)) {
2845
      array_deep_copy($v, $copy[$k], $maxdepth, ++$depth);
2846
    }
2847
    else {
2848
      $copy[$k] = $v;
2849
    }
2850
  }
2851
}
2852

    
2853
/**
2854
 * Concatenated the uuids of the passed cdm entity with `,` as glue.
2855
 * The returned string is suitable for cdm webservices consuming UUIDList as
2856
 * parameter
2857
 *
2858
 * @param array $cdm_entities
2859
 *
2860
 * @return string
2861
 */
2862
function cdm_uuid_list_parameter_value(array $cdm_entities){
2863
  $uuids = [];
2864
  foreach ($cdm_entities as $entity){
2865
    if(isset($entity) && is_uuid($entity->uuid) ){
2866
      $uuids[] = $entity->uuid;
2867
    }
2868
  }
2869
  return  join(',', $uuids);
2870
}
2871

    
2872
/**
2873
 * Adds java script to create and enable a toggler for the cdm webservice debug block content.
2874
 *
2875
 */
2876
function _add_js_ws_debug() {
2877

    
2878
  $data_tables_js = '/js/DataTables-1.9.4/media/js/jquery.dataTables.min.js';
2879
  $colorbox_js = '/js/colorbox/jquery.colorbox-min.js';
2880
  if (variable_get('cdm_js_devel_mode', FALSE)) {
2881
    // use the developer versions of js libs
2882
    $data_tables_js = '/js/DataTables-1.9.4/media/js/jquery.dataTables.js';
2883
    $colorbox_js = '/js/colorbox/jquery.colorbox.js';
2884
  }
2885
  drupal_add_js(drupal_get_path('module', 'cdm_dataportal') . $data_tables_js,
2886
    array(
2887
      'type' => 'file',
2888
      'weight' => JS_LIBRARY,
2889
      'cache' => TRUE)
2890
    );
2891

    
2892
  drupal_add_js(drupal_get_path('module', 'cdm_dataportal') . $colorbox_js,
2893
    array(
2894
      'type' => 'file',
2895
      'weight' => JS_LIBRARY,
2896
      'cache' => TRUE)
2897
    );
2898
  drupal_add_css(drupal_get_path('module', 'cdm_dataportal') . '/js/colorbox/colorbox.css');
2899
  drupal_add_css(drupal_get_path('module', 'cdm_dataportal') . '/js/DataTables-1.9.4/media/css/cdm_debug_table.css');
2900

    
2901
  drupal_add_js(drupal_get_path('module', 'cdm_dataportal') . '/js/ws_debug_block.js',
2902
    array(
2903
      'type' => 'file',
2904
      'weight' => JS_LIBRARY,
2905
      'cache' => TRUE)
2906
    );
2907
  drupal_add_js(drupal_get_path('module', 'cdm_dataportal') . '/js/http-method-link.js',
2908
    array(
2909
    'type' => 'file',
2910
    'weight' => JS_LIBRARY,
2911
    'cache' => TRUE)
2912
    );
2913

    
2914
}
2915

    
2916
/**
2917
 * @todo Please document this function.
2918
 * @see http://drupal.org/node/1354
2919
 */
2920
function _no_classfication_uuid_message() {
2921
  if (!cdm_ws_get(CDM_WS_PORTAL_TAXONOMY)) {
2922
    return t('This DataPortal is not configured properly or the CDM-Server may be absent.') . ' Please check the ' . l(t('CDM web service URL'), 'admin/config/cdm_dataportal/settings/general') . t(', or contact the maintainer of this DataPortal.');
2923
  }
2924
  return t('This DataPortal is not configured properly.') . l(t('Please choose a valid classification'), 'admin/config/cdm_dataportal/settings/general') . t(', or contact the maintainer of this DataPortal.');
2925
}
2926

    
2927
/**
2928
 * Implementation of hook flush_caches
2929
 *
2930
 * Add custom cache tables to the list of cache tables that
2931
 * will be cleared by the Clear button on the Performance page or whenever
2932
 * drupal_flush_all_caches is invoked.
2933
 *
2934
 * @author W.Addink <waddink@eti.uva.nl>
2935
 *
2936
 * @return array
2937
 *   An array with custom cache tables to include.
2938
 */
2939
function cdm_api_flush_caches() {
2940
  return array('cache_cdm_ws');
2941
}
2942

    
2943
/**
2944
 * Logs if the drupal variable 'cdm_debug_mode' ist set true to drupal_debug.txt in the site's temp directory.
2945
 *
2946
 * @param $data
2947
 *   The variable to log to the drupal_debug.txt log file.
2948
 * @param $label
2949
 *   (optional) If set, a label to output before $data in the log file.
2950
 *
2951
 * @return
2952
 *   No return value if successful, FALSE if the log file could not be written
2953
 *   to.
2954
 *
2955
 * @see cdm_dataportal_init() where the log file is reset on each requests
2956
 * @see dd()
2957
 * @see http://drupal.org/node/314112
2958
 *
2959
 */
2960
function cdm_dd($data, $label = NULL) {
2961
  if(module_exists('devel') && variable_get('cdm_debug_mode', FALSE) && file_stream_wrapper_get_class('temporary') ){
2962
    return dd($data, $label);
2963
  }
2964
}
2965

    
(5-5/12)