1 /* @source ensexternaldatabase ************************************************
2 **
3 ** Ensembl External Database functions
4 **
5 ** @author Copyright (C) 1999 Ensembl Developers
6 ** @author Copyright (C) 2006 Michael K. Schuster
7 ** @version $Revision: 1.57 $
8 ** @modified 2009 by Alan Bleasby for incorporation into EMBOSS core
9 ** @modified $Date: 2013/02/17 13:02:10 $ by $Author: mks $
10 ** @@
11 **
12 ** This library is free software; you can redistribute it and/or
13 ** modify it under the terms of the GNU Lesser General Public
14 ** License as published by the Free Software Foundation; either
15 ** version 2.1 of the License, or (at your option) any later version.
16 **
17 ** This library is distributed in the hope that it will be useful,
18 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 ** Lesser General Public License for more details.
21 **
22 ** You should have received a copy of the GNU Lesser General Public
23 ** License along with this library; if not, write to the Free Software
24 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
25 ** MA 02110-1301, USA.
26 **
27 ******************************************************************************/
28
29 /* ========================================================================= */
30 /* ============================= include files ============================= */
31 /* ========================================================================= */
32
33 #include "ensbaseadaptor.h"
34 #include "ensexternaldatabase.h"
35 #include "enstable.h"
36
37
38
39
40 /* ========================================================================= */
41 /* =============================== constants =============================== */
42 /* ========================================================================= */
43
44
45
46
47 /* ========================================================================= */
48 /* =========================== global variables ============================ */
49 /* ========================================================================= */
50
51
52
53
54 /* ========================================================================= */
55 /* ============================= private data ============================== */
56 /* ========================================================================= */
57
58
59
60
61 /* ========================================================================= */
62 /* =========================== private constants =========================== */
63 /* ========================================================================= */
64
65 /* @conststatic externaldatabaseKStatus ***************************************
66 **
67 ** The Ensembl External Database status is enumerated in both, the SQL table
68 ** definition and the data structure. The following strings are used for
69 ** conversion in database operations and correspond to
70 ** EnsEExternaldatabaseStatus.
71 **
72 ** KNOWNXREF:
73 ** KNOWN:
74 ** XREF:
75 ** PRED:
76 ** ORTH:
77 ** PSEUDO:
78 **
79 ******************************************************************************/
80
81 static const char *externaldatabaseKStatus[] =
82 {
83 "",
84 "KNOWNXREF",
85 "KNOWN",
86 "XREF",
87 "PRED",
88 "ORTH",
89 "PSEUDO",
90 (const char *) NULL
91 };
92
93
94
95
96 /* @conststatic externaldatabaseKType *****************************************
97 **
98 ** The Ensembl External Database type is enumerated in both, the SQL table
99 ** definition and the data structure. The following strings are used for
100 ** conversion in database operations and correspond to
101 ** EnsEExternaldatabaseType.
102 **
103 ** ARRAY:
104 ** ALT_TRANS:
105 ** MISC:
106 ** LIT:
107 ** PRIMARY_DB_SYNONYM:
108 ** ENSEMBL:
109 ** IGNORE: This is in the Ensembl Genomes schema only.
110 **
111 ******************************************************************************/
112
113 static const char *externaldatabaseKType[] =
114 {
115 "",
116 "ARRAY",
117 "ALT_TRANS",
118 "ALT_GENE",
119 "MISC",
120 "LIT",
121 "PRIMARY_DB_SYNONYM",
122 "ENSEMBL",
123 "IGNORE",
124 (const char *) NULL
125 };
126
127
128
129
130 /* @conststatic externaldatabaseadaptorKTablenames ****************************
131 **
132 ** Array of Ensembl External Database Adaptor SQL table names
133 **
134 ******************************************************************************/
135
136 static const char *externaldatabaseadaptorKTablenames[] =
137 {
138 "external_db",
139 (const char *) NULL
140 };
141
142
143
144
145 /* @conststatic externaldatabaseadaptorKColumnnames ***************************
146 **
147 ** Array of Ensembl External Database Adaptor SQL column names
148 **
149 ******************************************************************************/
150
151 static const char *externaldatabaseadaptorKColumnnames[] =
152 {
153 "external_db.external_db_id",
154 "external_db.db_name",
155 "external_db.db_release",
156 "external_db.db_display_name",
157 "external_db.secondary_db_name",
158 "external_db.secondary_db_table",
159 "external_db.description",
160 "external_db.priority",
161 "external_db.status",
162 "external_db.type",
163 (const char *) NULL
164 };
165
166
167
168
169 /* ========================================================================= */
170 /* =========================== private variables =========================== */
171 /* ========================================================================= */
172
173
174
175
176 /* ========================================================================= */
177 /* =========================== private functions =========================== */
178 /* ========================================================================= */
179
180 static AjBool externaldatabaseadaptorFetchAllbyStatement(
181 EnsPBaseadaptor ba,
182 const AjPStr statement,
183 EnsPAssemblymapper am,
184 EnsPSlice slice,
185 AjPList edbs);
186
187 static AjBool externaldatabaseadaptorCacheInsert(
188 EnsPExternaldatabaseadaptor edba,
189 EnsPExternaldatabase *Pedb);
190
191 static void externaldatabaseadaptorCacheByNameValdel(void **Pvalue);
192
193 static AjBool externaldatabaseadaptorCacheInit(
194 EnsPExternaldatabaseadaptor edba);
195
196 static void externaldatabaseadaptorFetchAll(const void *key,
197 void **Pvalue,
198 void *cl);
199
200
201
202
203 /* ========================================================================= */
204 /* ======================= All functions by section ======================== */
205 /* ========================================================================= */
206
207
208
209
210 /* @filesection ensexternaldatabase *******************************************
211 **
212 ** @nam1rule ens Function belongs to the Ensembl library
213 **
214 ******************************************************************************/
215
216
217
218
219 /* @datasection [EnsPExternaldatabase] Ensembl External Database **************
220 **
221 ** @nam2rule Externaldatabase Functions for manipulating
222 ** Ensembl External Database objects
223 **
224 ** @cc Bio::EnsEMBL::DBEntry
225 ** @cc CVS Revision: 1.53
226 ** @cc CVS Tag: branch-ensembl-68
227 **
228 ******************************************************************************/
229
230
231
232
233 /* @section constructors ******************************************************
234 **
235 ** All constructors return a new Ensembl External Database by pointer.
236 ** It is the responsibility of the user to first destroy any previous
237 ** External Database. The target pointer does not need to be initialised to
238 ** NULL, but it is good programming practice to do so anyway.
239 **
240 ** @fdata [EnsPExternaldatabase]
241 **
242 ** @nam3rule New Constructor
243 ** @nam4rule Cpy Constructor with existing object
244 ** @nam4rule Ini Constructor with initial values
245 ** @nam4rule Ref Constructor by incrementing the reference counter
246 **
247 ** @argrule Cpy edb [const EnsPExternaldatabase] Ensembl External Database
248 ** @argrule Ini edba [EnsPExternaldatabaseadaptor] External Database Adaptor
249 ** @argrule Ini identifier [ajuint] SQL database-internal identifier
250 ** @argrule Ini name [AjPStr] Database name
251 ** @argrule Ini release [AjPStr] Database release
252 ** @argrule Ini displayname [AjPStr] Database display name
253 ** @argrule Ini secondaryname [AjPStr] Secondary name
254 ** @argrule Ini secondarytable [AjPStr] Secondary table
255 ** @argrule Ini description [AjPStr] Description
256 ** @argrule Ini status [EnsEExternaldatabaseStatus] Status
257 ** @argrule Ini type [EnsEExternaldatabaseType] Type
258 ** @argrule Ini priority [ajint] Display priority
259 ** @argrule Ref edb [EnsPExternaldatabase] Ensembl External Database
260 **
261 ** @valrule * [EnsPExternaldatabase] Ensembl External Database or NULL
262 **
263 ** @fcategory new
264 ******************************************************************************/
265
266
267
268
269 /* @func ensExternaldatabaseNewCpy ********************************************
270 **
271 ** Object-based constructor function, which returns an independent object.
272 **
273 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
274 **
275 ** @return [EnsPExternaldatabase] Ensembl External Database or NULL
276 **
277 ** @release 6.4.0
278 ** @@
279 ******************************************************************************/
280
ensExternaldatabaseNewCpy(const EnsPExternaldatabase edb)281 EnsPExternaldatabase ensExternaldatabaseNewCpy(
282 const EnsPExternaldatabase edb)
283 {
284 EnsPExternaldatabase pthis = NULL;
285
286 if (!edb)
287 return NULL;
288
289 AJNEW0(pthis);
290
291 pthis->Use = 1U;
292 pthis->Identifier = edb->Identifier;
293 pthis->Adaptor = edb->Adaptor;
294
295 if (edb->Name)
296 pthis->Name = ajStrNewRef(edb->Name);
297
298 if (edb->Release)
299 pthis->Release = ajStrNewRef(edb->Release);
300
301 if (edb->Displayname)
302 pthis->Displayname = ajStrNewRef(edb->Displayname);
303
304 if (edb->Secondaryname)
305 pthis->Secondaryname = ajStrNewRef(edb->Secondaryname);
306
307 if (edb->Secondarytable)
308 pthis->Secondarytable = ajStrNewRef(edb->Secondarytable);
309
310 if (edb->Description)
311 pthis->Description = ajStrNewRef(edb->Description);
312
313 pthis->Status = edb->Status;
314 pthis->Type = edb->Type;
315
316 pthis->Priority = edb->Priority;
317
318 return pthis;
319 }
320
321
322
323
324 /* @func ensExternaldatabaseNewIni ********************************************
325 **
326 ** Constructor for an Ensembl External Database with initial values.
327 **
328 ** @cc Bio::EnsEMBL::Storable::new
329 ** @param [u] edba [EnsPExternaldatabaseadaptor] External Database Adaptor
330 ** @param [r] identifier [ajuint] SQL database-internal identifier
331 ** @cc Bio::EnsEMBL::DBEntry::new
332 ** @param [u] name [AjPStr] Database name
333 ** @param [u] release [AjPStr] Database release
334 ** @param [u] displayname [AjPStr] Database display name
335 ** @param [u] secondaryname [AjPStr] Secondary name
336 ** @param [u] secondarytable [AjPStr] Secondary table
337 ** @param [u] description [AjPStr] Description
338 ** @param [u] status [EnsEExternaldatabaseStatus] Status
339 ** @param [u] type [EnsEExternaldatabaseType] Type
340 ** @param [r] priority [ajint] Display priority
341 **
342 ** @return [EnsPExternaldatabase] Ensembl External Database or NULL
343 **
344 ** @release 6.4.0
345 ** @@
346 ******************************************************************************/
347
ensExternaldatabaseNewIni(EnsPExternaldatabaseadaptor edba,ajuint identifier,AjPStr name,AjPStr release,AjPStr displayname,AjPStr secondaryname,AjPStr secondarytable,AjPStr description,EnsEExternaldatabaseStatus status,EnsEExternaldatabaseType type,ajint priority)348 EnsPExternaldatabase ensExternaldatabaseNewIni(
349 EnsPExternaldatabaseadaptor edba,
350 ajuint identifier,
351 AjPStr name,
352 AjPStr release,
353 AjPStr displayname,
354 AjPStr secondaryname,
355 AjPStr secondarytable,
356 AjPStr description,
357 EnsEExternaldatabaseStatus status,
358 EnsEExternaldatabaseType type,
359 ajint priority)
360 {
361 EnsPExternaldatabase edb = NULL;
362
363 if (!name)
364 return NULL;
365
366 AJNEW0(edb);
367
368 edb->Use = 1U;
369 edb->Identifier = identifier;
370 edb->Adaptor = edba;
371
372 if (name)
373 edb->Name = ajStrNewRef(name);
374
375 if (release)
376 edb->Release = ajStrNewRef(release);
377
378 if (displayname)
379 edb->Displayname = ajStrNewRef(displayname);
380
381 if (secondaryname)
382 edb->Secondaryname = ajStrNewRef(secondaryname);
383
384 if (secondarytable)
385 edb->Secondarytable = ajStrNewRef(secondarytable);
386
387 if (description)
388 edb->Description = ajStrNewRef(description);
389
390 edb->Status = status;
391 edb->Type = type;
392 edb->Priority = priority;
393
394 return edb;
395 }
396
397
398
399
400 /* @func ensExternaldatabaseNewRef ********************************************
401 **
402 ** Ensembl Object referencing function, which returns a pointer to the
403 ** Ensembl Object passed in and increases its reference count.
404 **
405 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
406 **
407 ** @return [EnsPExternaldatabase] Ensembl External Database or NULL
408 **
409 ** @release 6.2.0
410 ** @@
411 ******************************************************************************/
412
ensExternaldatabaseNewRef(EnsPExternaldatabase edb)413 EnsPExternaldatabase ensExternaldatabaseNewRef(EnsPExternaldatabase edb)
414 {
415 if (!edb)
416 return NULL;
417
418 edb->Use++;
419
420 return edb;
421 }
422
423
424
425
426 /* @section destructors *******************************************************
427 **
428 ** Destruction destroys all internal data structures and frees the memory
429 ** allocated for an Ensembl External Database object.
430 **
431 ** @fdata [EnsPExternaldatabase]
432 **
433 ** @nam3rule Del Destroy (free) an Ensembl External Database
434 **
435 ** @argrule * Pedb [EnsPExternaldatabase*] Ensembl External Database address
436 **
437 ** @valrule * [void]
438 **
439 ** @fcategory delete
440 ******************************************************************************/
441
442
443
444
445 /* @func ensExternaldatabaseDel ***********************************************
446 **
447 ** Default destructor for an Ensembl External Database.
448 **
449 ** @param [d] Pedb [EnsPExternaldatabase*] Ensembl External Database address
450 **
451 ** @return [void]
452 **
453 ** @release 6.2.0
454 ** @@
455 ******************************************************************************/
456
ensExternaldatabaseDel(EnsPExternaldatabase * Pedb)457 void ensExternaldatabaseDel(EnsPExternaldatabase *Pedb)
458 {
459 EnsPExternaldatabase pthis = NULL;
460
461 if (!Pedb)
462 return;
463
464 #if defined(AJ_DEBUG) && AJ_DEBUG >= 1
465 if (ajDebugTest("ensExternaldatabaseDel"))
466 {
467 ajDebug("ensExternaldatabaseDel\n"
468 " *Pedb %p\n",
469 *Pedb);
470
471 ensExternaldatabaseTrace(*Pedb, 1);
472 }
473 #endif /* defined(AJ_DEBUG) && AJ_DEBUG >= 1 */
474
475 if (!(pthis = *Pedb) || --pthis->Use)
476 {
477 *Pedb = NULL;
478
479 return;
480 }
481
482 ajStrDel(&pthis->Name);
483 ajStrDel(&pthis->Release);
484 ajStrDel(&pthis->Displayname);
485 ajStrDel(&pthis->Secondaryname);
486 ajStrDel(&pthis->Secondarytable);
487 ajStrDel(&pthis->Description);
488
489 ajMemFree((void **) Pedb);
490
491 return;
492 }
493
494
495
496
497 /* @section member retrieval **************************************************
498 **
499 ** Functions for returning members of an Ensembl External Database object.
500 **
501 ** @fdata [EnsPExternaldatabase]
502 **
503 ** @nam3rule Get Return External Database attribute(s)
504 ** @nam4rule Adaptor Return the Ensembl External Database Adaptor
505 ** @nam4rule Description Return the description
506 ** @nam4rule Displayname Return the display name
507 ** @nam4rule Identifier Return the SQL database-internal identifier
508 ** @nam4rule Name Return the name
509 ** @nam4rule Priority Return the priority
510 ** @nam4rule Release Return the release
511 ** @nam4rule Secondaryname Return the secondary name
512 ** @nam4rule Secondarytable Return the secondary table
513 ** @nam4rule Status Return the status
514 ** @nam4rule Type Return the type
515 **
516 ** @argrule * edb [const EnsPExternaldatabase] External Database
517 **
518 ** @valrule Adaptor [EnsPExternaldatabaseadaptor]
519 ** Ensembl External Database Adaptor or NULL
520 ** @valrule Description [AjPStr] Description or NULL
521 ** @valrule Displayname [AjPStr] Display name or NULL
522 ** @valrule Identifier [ajuint] SQL database-internal identifier or 0U
523 ** @valrule Name [AjPStr] Name or NULL
524 ** @valrule Priority [ajint] Priority or 0
525 ** @valrule Release [AjPStr] Release or NULL
526 ** @valrule Secondaryname [AjPStr] Secondary name or NULL
527 ** @valrule Secondarytable [AjPStr] Secondary table or NULL
528 ** @valrule Status [EnsEExternaldatabaseStatus] Status or
529 ** ensEExternaldatabaseStatusNULL
530 ** @valrule Type [EnsEExternaldatabaseType] Type or
531 ** ensEExternaldatabaseTypeNULL
532 **
533 ** @fcategory use
534 ******************************************************************************/
535
536
537
538
539 /* @func ensExternaldatabaseGetAdaptor ****************************************
540 **
541 ** Get the Ensembl External Database Adaptor member of an
542 ** Ensembl External Database.
543 **
544 ** @cc Bio::EnsEMBL::Storable::adaptor
545 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
546 **
547 ** @return [EnsPExternaldatabaseadaptor] Ensembl External Database Adaptor
548 ** or NULL
549 **
550 ** @release 6.2.0
551 ** @@
552 ******************************************************************************/
553
ensExternaldatabaseGetAdaptor(const EnsPExternaldatabase edb)554 EnsPExternaldatabaseadaptor ensExternaldatabaseGetAdaptor(
555 const EnsPExternaldatabase edb)
556 {
557 return (edb) ? edb->Adaptor : NULL;
558 }
559
560
561
562
563 /* @func ensExternaldatabaseGetDescription ************************************
564 **
565 ** Get the description member of an Ensembl External Database.
566 **
567 ** @cc Bio::EnsEMBL::DBEntry::description
568 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
569 **
570 ** @return [AjPStr] Description or NULL
571 **
572 ** @release 6.2.0
573 ** @@
574 ******************************************************************************/
575
ensExternaldatabaseGetDescription(const EnsPExternaldatabase edb)576 AjPStr ensExternaldatabaseGetDescription(
577 const EnsPExternaldatabase edb)
578 {
579 return (edb) ? edb->Description : NULL;
580 }
581
582
583
584
585 /* @func ensExternaldatabaseGetDisplayname ************************************
586 **
587 ** Get the display name member of an Ensembl External Database.
588 **
589 ** @cc Bio::EnsEMBL::DBEntry::db_display_name
590 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
591 **
592 ** @return [AjPStr] Display name or NULL
593 **
594 ** @release 6.4.0
595 ** @@
596 ******************************************************************************/
597
ensExternaldatabaseGetDisplayname(const EnsPExternaldatabase edb)598 AjPStr ensExternaldatabaseGetDisplayname(
599 const EnsPExternaldatabase edb)
600 {
601 return (edb) ? edb->Displayname : NULL;
602 }
603
604
605
606
607 /* @func ensExternaldatabaseGetIdentifier *************************************
608 **
609 ** Get the SQL database-internal identifier member of an
610 ** Ensembl External Database.
611 **
612 ** @cc Bio::EnsEMBL::Storable::dbID
613 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
614 **
615 ** @return [ajuint] SQL database-internal identifier or 0U
616 **
617 ** @release 6.2.0
618 ** @@
619 ******************************************************************************/
620
ensExternaldatabaseGetIdentifier(const EnsPExternaldatabase edb)621 ajuint ensExternaldatabaseGetIdentifier(
622 const EnsPExternaldatabase edb)
623 {
624 return (edb) ? edb->Identifier : 0U;
625 }
626
627
628
629
630 /* @func ensExternaldatabaseGetName *******************************************
631 **
632 ** Get the name member of an Ensembl External Database.
633 **
634 ** @cc Bio::EnsEMBL::DBEntry::dbname
635 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
636 **
637 ** @return [AjPStr] Name or NULL
638 **
639 ** @release 6.2.0
640 ** @@
641 ******************************************************************************/
642
ensExternaldatabaseGetName(const EnsPExternaldatabase edb)643 AjPStr ensExternaldatabaseGetName(
644 const EnsPExternaldatabase edb)
645 {
646 return (edb) ? edb->Name : NULL;
647 }
648
649
650
651
652 /* @func ensExternaldatabaseGetPriority ***************************************
653 **
654 ** Get the priority member of an Ensembl External Database.
655 **
656 ** @cc Bio::EnsEMBL::DBEntry::priority
657 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
658 **
659 ** @return [ajint] Priority or 0
660 **
661 ** @release 6.2.0
662 ** @@
663 ******************************************************************************/
664
ensExternaldatabaseGetPriority(const EnsPExternaldatabase edb)665 ajint ensExternaldatabaseGetPriority(
666 const EnsPExternaldatabase edb)
667 {
668 return (edb) ? edb->Priority : 0;
669 }
670
671
672
673
674 /* @func ensExternaldatabaseGetRelease ****************************************
675 **
676 ** Get the release member of an Ensembl External Database.
677 **
678 ** @cc Bio::EnsEMBL::DBEntry::release
679 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
680 **
681 ** @return [AjPStr] Release or NULL
682 **
683 ** @release 6.2.0
684 ** @@
685 ******************************************************************************/
686
ensExternaldatabaseGetRelease(const EnsPExternaldatabase edb)687 AjPStr ensExternaldatabaseGetRelease(
688 const EnsPExternaldatabase edb)
689 {
690 return (edb) ? edb->Release : NULL;
691 }
692
693
694
695
696 /* @func ensExternaldatabaseGetSecondaryname **********************************
697 **
698 ** Get the secondary name member of an Ensembl External Database.
699 **
700 ** @cc Bio::EnsEMBL::DBEntry::secondary_db_name
701 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
702 **
703 ** @return [AjPStr] Secondary name or NULL
704 **
705 ** @release 6.4.0
706 ** @@
707 ******************************************************************************/
708
ensExternaldatabaseGetSecondaryname(const EnsPExternaldatabase edb)709 AjPStr ensExternaldatabaseGetSecondaryname(
710 const EnsPExternaldatabase edb)
711 {
712 return (edb) ? edb->Secondaryname : NULL;
713 }
714
715
716
717
718 /* @func ensExternaldatabaseGetSecondarytable *********************************
719 **
720 ** Get the secondary table member of an Ensembl External Database.
721 **
722 ** @cc Bio::EnsEMBL::DBEntry::secondary_db_table
723 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
724 **
725 ** @return [AjPStr] Secondary table or NULL
726 **
727 ** @release 6.4.0
728 ** @@
729 ******************************************************************************/
730
ensExternaldatabaseGetSecondarytable(const EnsPExternaldatabase edb)731 AjPStr ensExternaldatabaseGetSecondarytable(
732 const EnsPExternaldatabase edb)
733 {
734 return (edb) ? edb->Secondarytable : NULL;
735 }
736
737
738
739
740 /* @func ensExternaldatabaseGetStatus *****************************************
741 **
742 ** Get the status member of an Ensembl External Database.
743 **
744 ** @cc Bio::EnsEMBL::DBEntry::status
745 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
746 **
747 ** @return [EnsEExternaldatabaseStatus] Status or
748 ** ensEExternaldatabaseStatusNULL
749 **
750 ** @release 6.2.0
751 ** @@
752 ******************************************************************************/
753
ensExternaldatabaseGetStatus(const EnsPExternaldatabase edb)754 EnsEExternaldatabaseStatus ensExternaldatabaseGetStatus(
755 const EnsPExternaldatabase edb)
756 {
757 return (edb) ? edb->Status : ensEExternaldatabaseStatusNULL;
758 }
759
760
761
762
763 /* @func ensExternaldatabaseGetType *******************************************
764 **
765 ** Get the type member of an Ensembl External Database.
766 **
767 ** @cc Bio::EnsEMBL::DBEntry::type
768 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
769 **
770 ** @return [EnsEExternaldatabaseType] Type or ensEExternaldatabaseTypeNULL
771 **
772 ** @release 6.2.0
773 ** @@
774 ******************************************************************************/
775
ensExternaldatabaseGetType(const EnsPExternaldatabase edb)776 EnsEExternaldatabaseType ensExternaldatabaseGetType(
777 const EnsPExternaldatabase edb)
778 {
779 return (edb) ? edb->Type : ensEExternaldatabaseTypeNULL;
780 }
781
782
783
784
785 /* @section member assignment *************************************************
786 **
787 ** Functions for assigning members of an Ensembl External Database object.
788 **
789 ** @fdata [EnsPExternaldatabase]
790 **
791 ** @nam3rule Set Set one member of an Ensembl External Database
792 ** @nam4rule Adaptor Set the Ensembl External Database Adaptor
793 ** @nam4rule Description Set the description
794 ** @nam4rule Displayname Set the display name
795 ** @nam4rule Identifier Set the SQL database-internal identifier
796 ** @nam4rule Name Set the name
797 ** @nam4rule Priority Set the priority
798 ** @nam4rule Release Set the release
799 ** @nam4rule Secondaryname Set the secondary name
800 ** @nam4rule Secondarytable Set the secondary table
801 ** @nam4rule Status Set the status
802 ** @nam4rule Type Set the type
803 **
804 ** @argrule * edb [EnsPExternaldatabase] Ensembl External Database object
805 ** @argrule Adaptor edba [EnsPExternaldatabaseadaptor] Ensembl External
806 ** @argrule Description description [AjPStr] Description
807 ** @argrule Displayname displayname [AjPStr] Display name
808 ** @argrule Identifier identifier [ajuint] SQL database-internal identifier
809 ** @argrule Name name [AjPStr] Name
810 ** @argrule Priority priority [ajint] Priority
811 ** @argrule Release release [AjPStr] Release
812 ** @argrule Secondaryname secondaryname [AjPStr] Secondary name
813 ** @argrule Secondarytable secondarytable [AjPStr] Secondary table
814 ** @argrule Status status [EnsEExternaldatabaseStatus] Status
815 ** @argrule Type type [EnsEExternaldatabaseType] Type
816 **
817 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
818 **
819 ** @fcategory modify
820 ******************************************************************************/
821
822
823
824
825 /* @func ensExternaldatabaseSetAdaptor ****************************************
826 **
827 ** Set the Ensembl External Database Adaptor member of an
828 ** Ensembl External Database.
829 **
830 ** @cc Bio::EnsEMBL::Storable::adaptor
831 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
832 ** @param [u] edba [EnsPExternaldatabaseadaptor] Ensembl External
833 ** Database Adaptor
834 **
835 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
836 **
837 ** @release 6.2.0
838 ** @@
839 ******************************************************************************/
840
ensExternaldatabaseSetAdaptor(EnsPExternaldatabase edb,EnsPExternaldatabaseadaptor edba)841 AjBool ensExternaldatabaseSetAdaptor(EnsPExternaldatabase edb,
842 EnsPExternaldatabaseadaptor edba)
843 {
844 if (!edb)
845 return ajFalse;
846
847 edb->Adaptor = edba;
848
849 return ajTrue;
850 }
851
852
853
854
855 /* @func ensExternaldatabaseSetDescription ************************************
856 **
857 ** Set the description member of an Ensembl External Database.
858 **
859 ** @cc Bio::EnsEMBL::DBEntry::description
860 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
861 ** @param [u] description [AjPStr] Description
862 **
863 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
864 **
865 ** @release 6.2.0
866 ** @@
867 ******************************************************************************/
868
ensExternaldatabaseSetDescription(EnsPExternaldatabase edb,AjPStr description)869 AjBool ensExternaldatabaseSetDescription(EnsPExternaldatabase edb,
870 AjPStr description)
871 {
872 if (!edb)
873 return ajFalse;
874
875 ajStrDel(&edb->Description);
876
877 edb->Description = ajStrNewRef(description);
878
879 return ajTrue;
880 }
881
882
883
884
885 /* @func ensExternaldatabaseSetDisplayname ************************************
886 **
887 ** Set the display name member of an Ensembl External Database.
888 **
889 ** @cc Bio::EnsEMBL::DBEntry::db_display_name
890 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
891 ** @param [u] displayname [AjPStr] Display name
892 **
893 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
894 **
895 ** @release 6.4.0
896 ** @@
897 ******************************************************************************/
898
ensExternaldatabaseSetDisplayname(EnsPExternaldatabase edb,AjPStr displayname)899 AjBool ensExternaldatabaseSetDisplayname(EnsPExternaldatabase edb,
900 AjPStr displayname)
901 {
902 if (!edb)
903 return ajFalse;
904
905 ajStrDel(&edb->Displayname);
906
907 edb->Displayname = ajStrNewRef(displayname);
908
909 return ajTrue;
910 }
911
912
913
914
915 /* @func ensExternaldatabaseSetIdentifier *************************************
916 **
917 ** Set the SQL database-internal identifier member of an
918 ** Ensembl External Database.
919 **
920 ** @cc Bio::EnsEMBL::Storable::dbID
921 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
922 ** @param [r] identifier [ajuint] SQL database-internal identifier
923 **
924 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
925 **
926 ** @release 6.2.0
927 ** @@
928 ******************************************************************************/
929
ensExternaldatabaseSetIdentifier(EnsPExternaldatabase edb,ajuint identifier)930 AjBool ensExternaldatabaseSetIdentifier(EnsPExternaldatabase edb,
931 ajuint identifier)
932 {
933 if (!edb)
934 return ajFalse;
935
936 edb->Identifier = identifier;
937
938 return ajTrue;
939 }
940
941
942
943
944 /* @func ensExternaldatabaseSetName *******************************************
945 **
946 ** Set the name member of an Ensembl External Database.
947 **
948 ** @cc Bio::EnsEMBL::DBEntry::dbname
949 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
950 ** @param [u] name [AjPStr] Name
951 **
952 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
953 **
954 ** @release 6.2.0
955 ** @@
956 ******************************************************************************/
957
ensExternaldatabaseSetName(EnsPExternaldatabase edb,AjPStr name)958 AjBool ensExternaldatabaseSetName(EnsPExternaldatabase edb,
959 AjPStr name)
960 {
961 if (!edb)
962 return ajFalse;
963
964 ajStrDel(&edb->Name);
965
966 edb->Name = ajStrNewRef(name);
967
968 return ajTrue;
969 }
970
971
972
973
974 /* @func ensExternaldatabaseSetPriority ***************************************
975 **
976 ** Set the priority member of an Ensembl External Database.
977 **
978 ** @cc Bio::EnsEMBL::DBEntry::priority
979 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
980 ** @param [r] priority [ajint] Priority
981 **
982 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
983 **
984 ** @release 6.2.0
985 ** @@
986 ******************************************************************************/
987
ensExternaldatabaseSetPriority(EnsPExternaldatabase edb,ajint priority)988 AjBool ensExternaldatabaseSetPriority(EnsPExternaldatabase edb,
989 ajint priority)
990 {
991 if (!edb)
992 return ajFalse;
993
994 edb->Priority = priority;
995
996 return ajTrue;
997 }
998
999
1000
1001
1002 /* @func ensExternaldatabaseSetRelease ****************************************
1003 **
1004 ** Set the release member of an Ensembl External Database.
1005 **
1006 ** @cc Bio::EnsEMBL::DBEntry::release
1007 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
1008 ** @param [u] release [AjPStr] Release
1009 **
1010 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1011 **
1012 ** @release 6.2.0
1013 ** @@
1014 ******************************************************************************/
1015
ensExternaldatabaseSetRelease(EnsPExternaldatabase edb,AjPStr release)1016 AjBool ensExternaldatabaseSetRelease(EnsPExternaldatabase edb,
1017 AjPStr release)
1018 {
1019 if (!edb)
1020 return ajFalse;
1021
1022 ajStrDel(&edb->Release);
1023
1024 edb->Release = ajStrNewRef(release);
1025
1026 return ajTrue;
1027 }
1028
1029
1030
1031
1032 /* @func ensExternaldatabaseSetSecondaryname **********************************
1033 **
1034 ** Set the secondary name member of an Ensembl External Database.
1035 **
1036 ** @cc Bio::EnsEMBL::DBEntry::secondary_db_name
1037 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
1038 ** @param [u] secondaryname [AjPStr] Secondary name
1039 **
1040 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1041 **
1042 ** @release 6.4.0
1043 ** @@
1044 ******************************************************************************/
1045
ensExternaldatabaseSetSecondaryname(EnsPExternaldatabase edb,AjPStr secondaryname)1046 AjBool ensExternaldatabaseSetSecondaryname(EnsPExternaldatabase edb,
1047 AjPStr secondaryname)
1048 {
1049 if (!edb)
1050 return ajFalse;
1051
1052 ajStrDel(&edb->Secondaryname);
1053
1054 edb->Secondaryname = ajStrNewRef(secondaryname);
1055
1056 return ajTrue;
1057 }
1058
1059
1060
1061
1062 /* @func ensExternaldatabaseSetSecondarytable *********************************
1063 **
1064 ** Set the secondary table member of an Ensembl External Database.
1065 **
1066 ** @cc Bio::EnsEMBL::DBEntry::secondary_db_table
1067 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
1068 ** @param [u] secondarytable [AjPStr] Secondary table
1069 **
1070 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1071 **
1072 ** @release 6.4.0
1073 ** @@
1074 ******************************************************************************/
1075
ensExternaldatabaseSetSecondarytable(EnsPExternaldatabase edb,AjPStr secondarytable)1076 AjBool ensExternaldatabaseSetSecondarytable(EnsPExternaldatabase edb,
1077 AjPStr secondarytable)
1078 {
1079 if (!edb)
1080 return ajFalse;
1081
1082 ajStrDel(&edb->Secondarytable);
1083
1084 edb->Secondarytable = ajStrNewRef(secondarytable);
1085
1086 return ajTrue;
1087 }
1088
1089
1090
1091
1092 /* @func ensExternaldatabaseSetStatus *****************************************
1093 **
1094 ** Set the status member of an Ensembl External Database.
1095 **
1096 ** @cc Bio::EnsEMBL::DBEntry::status
1097 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
1098 ** @param [u] status [EnsEExternaldatabaseStatus] Status
1099 **
1100 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1101 **
1102 ** @release 6.2.0
1103 ** @@
1104 ******************************************************************************/
1105
ensExternaldatabaseSetStatus(EnsPExternaldatabase edb,EnsEExternaldatabaseStatus status)1106 AjBool ensExternaldatabaseSetStatus(EnsPExternaldatabase edb,
1107 EnsEExternaldatabaseStatus status)
1108 {
1109 if (!edb)
1110 return ajFalse;
1111
1112 edb->Status = status;
1113
1114 return ajTrue;
1115 }
1116
1117
1118
1119
1120 /* @func ensExternaldatabaseSetType *******************************************
1121 **
1122 ** Set the type member of an Ensembl External Database.
1123 **
1124 ** @cc Bio::EnsEMBL::DBEntry::type
1125 ** @param [u] edb [EnsPExternaldatabase] Ensembl External Database
1126 ** @param [u] type [EnsEExternaldatabaseType] Type
1127 **
1128 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1129 **
1130 ** @release 6.2.0
1131 ** @@
1132 ******************************************************************************/
1133
ensExternaldatabaseSetType(EnsPExternaldatabase edb,EnsEExternaldatabaseType type)1134 AjBool ensExternaldatabaseSetType(EnsPExternaldatabase edb,
1135 EnsEExternaldatabaseType type)
1136 {
1137 if (!edb)
1138 return ajFalse;
1139
1140 edb->Type = type;
1141
1142 return ajTrue;
1143 }
1144
1145
1146
1147
1148 /* @section debugging *********************************************************
1149 **
1150 ** Functions for reporting of an Ensembl External Database object.
1151 **
1152 ** @fdata [EnsPExternaldatabase]
1153 **
1154 ** @nam3rule Trace Report Ensembl External Database members to debug file
1155 **
1156 ** @argrule Trace edb [const EnsPExternaldatabase] Ensembl External Database
1157 ** @argrule Trace level [ajuint] Indentation level
1158 **
1159 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
1160 **
1161 ** @fcategory misc
1162 ******************************************************************************/
1163
1164
1165
1166
1167 /* @func ensExternaldatabaseTrace *********************************************
1168 **
1169 ** Trace an Ensembl External Database.
1170 **
1171 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
1172 ** @param [r] level [ajuint] Indentation level
1173 **
1174 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1175 **
1176 ** @release 6.2.0
1177 ** @@
1178 ******************************************************************************/
1179
ensExternaldatabaseTrace(const EnsPExternaldatabase edb,ajuint level)1180 AjBool ensExternaldatabaseTrace(const EnsPExternaldatabase edb, ajuint level)
1181 {
1182 AjPStr indent = NULL;
1183
1184 if (!edb)
1185 return ajFalse;
1186
1187 indent = ajStrNew();
1188
1189 ajStrAppendCountK(&indent, ' ', level * 2);
1190
1191 ajDebug("%SensExternaldatabaseTrace %p\n"
1192 "%S Use %u\n"
1193 "%S Identifier %u\n"
1194 "%S Adaptor %p\n"
1195 "%S Name '%S'\n"
1196 "%S Release '%S'\n"
1197 "%S Displayname '%S'\n"
1198 "%S Secondaryname '%S'\n"
1199 "%S Secondarytable '%S'\n"
1200 "%S Description '%S'\n"
1201 "%S Status '%s'\n"
1202 "%S Type '%s'\n"
1203 "%S Priority %d\n",
1204 indent, edb,
1205 indent, edb->Use,
1206 indent, edb->Identifier,
1207 indent, edb->Adaptor,
1208 indent, edb->Name,
1209 indent, edb->Release,
1210 indent, edb->Displayname,
1211 indent, edb->Secondaryname,
1212 indent, edb->Secondarytable,
1213 indent, edb->Description,
1214 indent, ensExternaldatabaseStatusToChar(edb->Status),
1215 indent, ensExternaldatabaseTypeToChar(edb->Type),
1216 indent, edb->Priority);
1217
1218 ajStrDel(&indent);
1219
1220 return ajTrue;
1221 }
1222
1223
1224
1225
1226 /* @section calculate *********************************************************
1227 **
1228 ** Functions for calculating information of an
1229 ** Ensembl External Database object.
1230 **
1231 ** @fdata [EnsPExternaldatabase]
1232 **
1233 ** @nam3rule Calculate Calculate Ensembl External Database information
1234 ** @nam4rule Memsize Calculate the memory size in bytes
1235 **
1236 ** @argrule * edb [const EnsPExternaldatabase] Ensembl External Database
1237 **
1238 ** @valrule Memsize [size_t] Memory size in bytes or 0
1239 **
1240 ** @fcategory misc
1241 ******************************************************************************/
1242
1243
1244
1245
1246 /* @func ensExternaldatabaseCalculateMemsize **********************************
1247 **
1248 ** Calculate the memory size in bytes of an Ensembl External Database.
1249 **
1250 ** @param [r] edb [const EnsPExternaldatabase] Ensembl External Database
1251 **
1252 ** @return [size_t] Memory size in bytes or 0
1253 **
1254 ** @release 6.4.0
1255 ** @@
1256 ******************************************************************************/
1257
ensExternaldatabaseCalculateMemsize(const EnsPExternaldatabase edb)1258 size_t ensExternaldatabaseCalculateMemsize(const EnsPExternaldatabase edb)
1259 {
1260 size_t size = 0;
1261
1262 if (!edb)
1263 return 0;
1264
1265 size += sizeof (EnsOExternaldatabase);
1266
1267 if (edb->Name)
1268 {
1269 size += sizeof (AjOStr);
1270
1271 size += ajStrGetRes(edb->Name);
1272 }
1273
1274 if (edb->Release)
1275 {
1276 size += sizeof (AjOStr);
1277
1278 size += ajStrGetRes(edb->Release);
1279 }
1280
1281 if (edb->Displayname)
1282 {
1283 size += sizeof (AjOStr);
1284
1285 size += ajStrGetRes(edb->Displayname);
1286 }
1287
1288 if (edb->Secondaryname)
1289 {
1290 size += sizeof (AjOStr);
1291
1292 size += ajStrGetRes(edb->Secondaryname);
1293 }
1294
1295 if (edb->Secondarytable)
1296 {
1297 size += sizeof (AjOStr);
1298
1299 size += ajStrGetRes(edb->Secondarytable);
1300 }
1301
1302 if (edb->Description)
1303 {
1304 size += sizeof (AjOStr);
1305
1306 size += ajStrGetRes(edb->Description);
1307 }
1308
1309 return size;
1310 }
1311
1312
1313
1314
1315 /* @datasection [EnsEExternaldatabaseStatus] Ensembl External Database Status *
1316 **
1317 ** @nam2rule Externaldatabase Functions for manipulating
1318 ** Ensembl External Database objects
1319 ** @nam3rule ExternaldatabaseStatus Functions for manipulating
1320 ** Ensembl External Database Status enumerations
1321 **
1322 ******************************************************************************/
1323
1324
1325
1326
1327 /* @section Misc **************************************************************
1328 **
1329 ** Functions for returning an Ensembl External Database Status enumeration.
1330 **
1331 ** @fdata [EnsEExternaldatabaseStatus]
1332 **
1333 ** @nam4rule From Ensembl External Database Status query
1334 ** @nam5rule Str AJAX String object query
1335 **
1336 ** @argrule Str status [const AjPStr] Status string
1337 **
1338 ** @valrule * [EnsEExternaldatabaseStatus]
1339 ** Ensembl External Database Status enumeration or
1340 ** ensEExternaldatabaseStatusNULL
1341 **
1342 ** @fcategory misc
1343 ******************************************************************************/
1344
1345
1346
1347
1348 /* @func ensExternaldatabaseStatusFromStr *************************************
1349 **
1350 ** Convert an AJAX String into an Ensembl External Database Status enumeration.
1351 **
1352 ** @param [r] status [const AjPStr] Status string
1353 **
1354 ** @return [EnsEExternaldatabaseStatus]
1355 ** Ensembl External Database Status enumeration or
1356 ** ensEExternaldatabaseStatusNULL
1357 **
1358 ** @release 6.2.0
1359 ** @@
1360 ******************************************************************************/
1361
ensExternaldatabaseStatusFromStr(const AjPStr status)1362 EnsEExternaldatabaseStatus ensExternaldatabaseStatusFromStr(
1363 const AjPStr status)
1364 {
1365 register EnsEExternaldatabaseStatus i = ensEExternaldatabaseStatusNULL;
1366
1367 EnsEExternaldatabaseStatus estatus = ensEExternaldatabaseStatusNULL;
1368
1369 for (i = ensEExternaldatabaseStatusNULL;
1370 externaldatabaseKStatus[i];
1371 i++)
1372 if (ajStrMatchC(status, externaldatabaseKStatus[i]))
1373 estatus = i;
1374
1375 if (!estatus)
1376 ajDebug("ensExternaldatabaseStatusFromStr encountered "
1377 "unexpected string '%S'.\n", status);
1378
1379 return estatus;
1380 }
1381
1382
1383
1384
1385 /* @section Cast **************************************************************
1386 **
1387 ** Functions for returning attributes of an
1388 ** Ensembl External Database Status enumeration.
1389 **
1390 ** @fdata [EnsEExternaldatabaseStatus]
1391 **
1392 ** @nam4rule To Cast an Ensembl External Database Status enumeration
1393 ** @nam5rule Char Return C character string value
1394 **
1395 ** @argrule To edbs [EnsEExternaldatabaseStatus]
1396 ** Ensembl External Database Status enumeration
1397 **
1398 ** @valrule Char [const char*] Ensembl External Database Status
1399 **
1400 ** @fcategory cast
1401 ******************************************************************************/
1402
1403
1404
1405
1406 /* @func ensExternaldatabaseStatusToChar **************************************
1407 **
1408 ** Convert an Ensembl External Database status member into a
1409 ** C-type (char *) string.
1410 **
1411 ** @param [u] edbs [EnsEExternaldatabaseStatus]
1412 ** Ensembl External Database Status enumeration
1413 **
1414 ** @return [const char*]
1415 ** Ensembl External Database Status C-type (char *) string
1416 **
1417 ** @release 6.2.0
1418 ** @@
1419 ******************************************************************************/
1420
ensExternaldatabaseStatusToChar(EnsEExternaldatabaseStatus edbs)1421 const char* ensExternaldatabaseStatusToChar(EnsEExternaldatabaseStatus edbs)
1422 {
1423 register EnsEExternaldatabaseStatus i = ensEExternaldatabaseStatusNULL;
1424
1425 for (i = ensEExternaldatabaseStatusNULL;
1426 externaldatabaseKStatus[i] && (i < edbs);
1427 i++);
1428
1429 if (!externaldatabaseKStatus[i])
1430 ajDebug("ensExternaldatabaseStatusToChar "
1431 "encountered an out of boundary error on "
1432 "Ensembl External Database Status "
1433 "enumeration %d.\n",
1434 edbs);
1435
1436 return externaldatabaseKStatus[i];
1437 }
1438
1439
1440
1441
1442 /* @datasection [EnsEExternaldatabaseType] Ensembl External Database Type *****
1443 **
1444 ** @nam2rule Externaldatabase Functions for manipulating
1445 ** Ensembl External Database objects
1446 ** @nam3rule ExternaldatabaseType Functions for manipulating
1447 ** Ensembl External Database Type enumerations
1448 **
1449 ******************************************************************************/
1450
1451
1452
1453
1454 /* @section Misc **************************************************************
1455 **
1456 ** Functions for returning an Ensembl External Database Type enumeration.
1457 **
1458 ** @fdata [EnsEExternaldatabaseType]
1459 **
1460 ** @nam4rule From Ensembl External Database Type query
1461 ** @nam5rule Str AJAX String object query
1462 **
1463 ** @argrule Str type [const AjPStr] Type string
1464 **
1465 ** @valrule * [EnsEExternaldatabaseType]
1466 ** Ensembl External Database Type enumeration or ensEExternaldatabaseTypeNULL
1467 **
1468 ** @fcategory misc
1469 ******************************************************************************/
1470
1471
1472
1473
1474 /* @func ensExternaldatabaseTypeFromStr ***************************************
1475 **
1476 ** Convert an AJAX String into an Ensembl External Database Type enumeration.
1477 **
1478 ** @param [r] type [const AjPStr] Type string
1479 **
1480 ** @return [EnsEExternaldatabaseType]
1481 ** Ensembl External Database Type enumeration or ensEExternaldatabaseTypeNULL
1482 **
1483 ** @release 6.2.0
1484 ** @@
1485 ******************************************************************************/
1486
ensExternaldatabaseTypeFromStr(const AjPStr type)1487 EnsEExternaldatabaseType ensExternaldatabaseTypeFromStr(
1488 const AjPStr type)
1489 {
1490 register EnsEExternaldatabaseType i = ensEExternaldatabaseTypeNULL;
1491
1492 EnsEExternaldatabaseType etype = ensEExternaldatabaseTypeNULL;
1493
1494 for (i = ensEExternaldatabaseTypeNULL;
1495 externaldatabaseKType[i];
1496 i++)
1497 if (ajStrMatchC(type, externaldatabaseKType[i]))
1498 etype = i;
1499
1500 if (!etype)
1501 ajDebug("ensExternaldatabaseTypeFromStr encountered "
1502 "unexpected string '%S'.\n", type);
1503
1504 return etype;
1505 }
1506
1507
1508
1509
1510 /* @section Cast **************************************************************
1511 **
1512 ** Functions for returning attributes of an
1513 ** Ensembl External Database Type enumeration.
1514 **
1515 ** @fdata [EnsEExternaldatabaseType]
1516 **
1517 ** @nam4rule To Cast an Ensembl External Database Type enumeration
1518 ** @nam5rule Char Return C character string value
1519 **
1520 ** @argrule To edbt [EnsEExternaldatabaseType]
1521 ** Ensembl External Database Type enumeration
1522 **
1523 ** @valrule Char [const char*] Ensembl External Database Type or NULL
1524 **
1525 ** @fcategory cast
1526 ******************************************************************************/
1527
1528
1529
1530
1531 /* @func ensExternaldatabaseTypeToChar ****************************************
1532 **
1533 ** Convert an Ensembl External Database type member into a
1534 ** C-type (char *) string.
1535 **
1536 ** @param [u] edbt [EnsEExternaldatabaseType]
1537 ** Ensembl External Database Type enumeration
1538 **
1539 ** @return [const char*]
1540 ** Ensembl External Database Type C-type (char *) string or NULL
1541 **
1542 ** @release 6.2.0
1543 ** @@
1544 ******************************************************************************/
1545
ensExternaldatabaseTypeToChar(EnsEExternaldatabaseType edbt)1546 const char* ensExternaldatabaseTypeToChar(EnsEExternaldatabaseType edbt)
1547 {
1548 register EnsEExternaldatabaseType i = ensEExternaldatabaseTypeNULL;
1549
1550 for (i = ensEExternaldatabaseTypeNULL;
1551 externaldatabaseKType[i] && (i < edbt);
1552 i++);
1553
1554 if (!externaldatabaseKType[i])
1555 ajDebug("ensExternaldatabaseTypeToChar "
1556 "encountered an out of boundary error on "
1557 "Ensembl External Database Type "
1558 "enumeration %d.\n",
1559 edbt);
1560
1561 return externaldatabaseKType[i];
1562 }
1563
1564
1565
1566
1567 /* @datasection [EnsPExternaldatabaseadaptor] Ensembl External Database Adaptor
1568 **
1569 ** @nam2rule Externaldatabaseadaptor Functions for manipulating
1570 ** Ensembl External Database Adaptor objects
1571 **
1572 ** @cc Bio::EnsEMBL::DBSQL::DBEntryAdaptor
1573 ** @cc CVS Revision: 1.175
1574 ** @cc CVS Tag: branch-ensembl-68
1575 **
1576 ******************************************************************************/
1577
1578
1579
1580
1581 /* @section constructors ******************************************************
1582 **
1583 ** All constructors return a new Ensembl External Database Adaptor by pointer.
1584 ** It is the responsibility of the user to first destroy any previous
1585 ** External Database Adaptor. The target pointer does not need to be
1586 ** initialised to NULL, but it is good programming practice to do so anyway.
1587 **
1588 ** @fdata [EnsPExternaldatabaseadaptor]
1589 **
1590 ** @nam3rule New Constructor
1591 **
1592 ** @argrule New dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
1593 **
1594 ** @valrule * [EnsPExternaldatabaseadaptor]
1595 ** Ensembl External Database Adaptor or NULL
1596 **
1597 ** @fcategory new
1598 ******************************************************************************/
1599
1600
1601
1602
1603 /* @funcstatic externaldatabaseadaptorFetchAllbyStatement *********************
1604 **
1605 ** Run a SQL statement against an Ensembl Database Adaptor and consolidate the
1606 ** results into an AJAX List of Ensembl External Database objects.
1607 **
1608 ** @param [u] ba [EnsPBaseadaptor] Ensembl Base Adaptor
1609 ** @param [r] statement [const AjPStr] SQL statement
1610 ** @param [uN] am [EnsPAssemblymapper] Ensembl Assembly Mapper
1611 ** @param [uN] slice [EnsPSlice] Ensembl Slice
1612 ** @param [u] edbs [AjPList] AJAX List of Ensembl External Databases
1613 **
1614 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1615 **
1616 ** @release 6.4.0
1617 ** @@
1618 ******************************************************************************/
1619
externaldatabaseadaptorFetchAllbyStatement(EnsPBaseadaptor ba,const AjPStr statement,EnsPAssemblymapper am,EnsPSlice slice,AjPList edbs)1620 static AjBool externaldatabaseadaptorFetchAllbyStatement(
1621 EnsPBaseadaptor ba,
1622 const AjPStr statement,
1623 EnsPAssemblymapper am,
1624 EnsPSlice slice,
1625 AjPList edbs)
1626 {
1627 ajint priority = 0;
1628 ajuint identifier = 0U;
1629
1630 EnsEExternaldatabaseStatus estatus = ensEExternaldatabaseStatusNULL;
1631 EnsEExternaldatabaseType etype = ensEExternaldatabaseTypeNULL;
1632
1633 AjPSqlstatement sqls = NULL;
1634 AjISqlrow sqli = NULL;
1635 AjPSqlrow sqlr = NULL;
1636
1637 AjPStr name = NULL;
1638 AjPStr release = NULL;
1639 AjPStr displayname = NULL;
1640 AjPStr secondaryname = NULL;
1641 AjPStr secondarytable = NULL;
1642 AjPStr description = NULL;
1643 AjPStr status = NULL;
1644 AjPStr type = NULL;
1645
1646 EnsPDatabaseadaptor dba = NULL;
1647
1648 EnsPExternaldatabase edb = NULL;
1649 EnsPExternaldatabaseadaptor edba = NULL;
1650
1651 if (ajDebugTest("externaldatabaseadaptorFetchAllbyStatement"))
1652 ajDebug("externaldatabaseadaptorFetchAllbyStatement\n"
1653 " ba %p\n"
1654 " statement '%S'\n"
1655 " am %p\n"
1656 " slice %p\n"
1657 " edbs %p\n",
1658 ba,
1659 statement,
1660 am,
1661 slice,
1662 edbs);
1663
1664 if (!ba)
1665 return ajFalse;
1666
1667 if (!statement)
1668 return ajFalse;
1669
1670 if (!edbs)
1671 return ajFalse;
1672
1673 dba = ensBaseadaptorGetDatabaseadaptor(ba);
1674
1675 edba = ensRegistryGetExternaldatabaseadaptor(dba);
1676
1677 sqls = ensDatabaseadaptorSqlstatementNew(dba, statement);
1678
1679 sqli = ajSqlrowiterNew(sqls);
1680
1681 while (!ajSqlrowiterDone(sqli))
1682 {
1683 identifier = 0;
1684 name = ajStrNew();
1685 release = ajStrNew();
1686 displayname = ajStrNew();
1687 secondaryname = ajStrNew();
1688 secondarytable = ajStrNew();
1689 description = ajStrNew();
1690 priority = 0;
1691 status = ajStrNew();
1692 type = ajStrNew();
1693 estatus = ensEExternaldatabaseStatusNULL;
1694 etype = ensEExternaldatabaseTypeNULL;
1695
1696 sqlr = ajSqlrowiterGet(sqli);
1697
1698 ajSqlcolumnToUint(sqlr, &identifier);
1699 ajSqlcolumnToStr(sqlr, &name);
1700 ajSqlcolumnToStr(sqlr, &release);
1701 ajSqlcolumnToStr(sqlr, &displayname);
1702 ajSqlcolumnToStr(sqlr, &secondaryname);
1703 ajSqlcolumnToStr(sqlr, &secondarytable);
1704 ajSqlcolumnToStr(sqlr, &description);
1705 ajSqlcolumnToInt(sqlr, &priority);
1706 ajSqlcolumnToStr(sqlr, &status);
1707 ajSqlcolumnToStr(sqlr, &type);
1708
1709 estatus = ensExternaldatabaseStatusFromStr(status);
1710
1711 if (!estatus)
1712 ajFatal("externaldatabaseadaptorFetchAllbyStatement encountered "
1713 "unexpected string '%S' in the "
1714 "'external_db.status' field.\n", status);
1715
1716 etype = ensExternaldatabaseTypeFromStr(type);
1717
1718 if (!etype)
1719 ajFatal("externaldatabaseadaptorFetchAllbyStatement encountered "
1720 "unexpected string '%S' in the "
1721 "'external_db.type' field.\n", type);
1722
1723 edb = ensExternaldatabaseNewIni(edba,
1724 identifier,
1725 name,
1726 release,
1727 displayname,
1728 secondaryname,
1729 secondarytable,
1730 description,
1731 estatus,
1732 etype,
1733 priority);
1734
1735 ajListPushAppend(edbs, (void *) edb);
1736
1737 ajStrDel(&name);
1738 ajStrDel(&release);
1739 ajStrDel(&displayname);
1740 ajStrDel(&secondaryname);
1741 ajStrDel(&secondarytable);
1742 ajStrDel(&description);
1743 ajStrDel(&status);
1744 ajStrDel(&type);
1745 }
1746
1747 ajSqlrowiterDel(&sqli);
1748
1749 ensDatabaseadaptorSqlstatementDel(dba, &sqls);
1750
1751 return ajTrue;
1752 }
1753
1754
1755
1756
1757 /* @funcstatic externaldatabaseadaptorCacheInsert *****************************
1758 **
1759 ** Insert an Ensembl External Database into the External Database
1760 ** Adaptor-internal cache.
1761 ** If an External Database with the same name member is already present in the
1762 ** adaptor cache, the External Database is deleted and a pointer to the
1763 ** cached External Database is returned.
1764 **
1765 ** @param [u] edba [EnsPExternaldatabaseadaptor]
1766 ** Ensembl External Database Adaptor
1767 ** @param [u] Pedb [EnsPExternaldatabase*] Ensembl External Database address
1768 **
1769 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1770 **
1771 ** @release 6.3.0
1772 ** @@
1773 ******************************************************************************/
1774
externaldatabaseadaptorCacheInsert(EnsPExternaldatabaseadaptor edba,EnsPExternaldatabase * Pedb)1775 static AjBool externaldatabaseadaptorCacheInsert(
1776 EnsPExternaldatabaseadaptor edba,
1777 EnsPExternaldatabase *Pedb)
1778 {
1779 ajuint *Pidentifier = NULL;
1780
1781 AjIList iter = NULL;
1782 AjPList list = NULL;
1783
1784 EnsPExternaldatabase edb0 = NULL;
1785 EnsPExternaldatabase edb1 = NULL;
1786 EnsPExternaldatabase edb2 = NULL;
1787
1788 if (!edba)
1789 return ajFalse;
1790
1791 if (!edba->CacheByIdentifier)
1792 return ajFalse;
1793
1794 if (!edba->CacheByName)
1795 return ajFalse;
1796
1797 if (!Pedb)
1798 return ajFalse;
1799
1800 if (!*Pedb)
1801 return ajFalse;
1802
1803 /* Search the identifer cache. */
1804
1805 edb1 = (EnsPExternaldatabase) ajTableFetchmodV(
1806 edba->CacheByIdentifier,
1807 (const void *) &((*Pedb)->Identifier));
1808
1809 /* Search the name cache. */
1810
1811 list = (AjPList) ajTableFetchmodS(edba->CacheByName, (*Pedb)->Name);
1812
1813 if (list)
1814 {
1815 iter = ajListIterNewread(list);
1816
1817 while (!ajListIterDone(iter))
1818 {
1819 edb0 = (EnsPExternaldatabase) ajListIterGet(iter);
1820
1821 if (ajStrMatchS(edb0->Release, (*Pedb)->Release))
1822 {
1823 edb2 = edb0;
1824
1825 break;
1826 }
1827 }
1828
1829 ajListIterDel(&iter);
1830 }
1831
1832 if ((!edb1) && (!edb2))
1833 {
1834 /* Insert into the identifier cache. */
1835
1836 AJNEW0(Pidentifier);
1837
1838 *Pidentifier = (*Pedb)->Identifier;
1839
1840 ajTablePut(edba->CacheByIdentifier,
1841 (void *) Pidentifier,
1842 (void *) ensExternaldatabaseNewRef(*Pedb));
1843
1844 /* Insert into the name cache. */
1845
1846 if (!list)
1847 {
1848 list = ajListNew();
1849
1850 ajTablePut(edba->CacheByName,
1851 (void *) ajStrNewS((*Pedb)->Name),
1852 (void *) list);
1853 }
1854
1855 ajListPushAppend(list,
1856 (void *) ensExternaldatabaseNewRef(*Pedb));
1857 }
1858
1859 if (edb1 && edb2 && (edb1 == edb2))
1860 {
1861 ajDebug("externaDatabaseadaptorCacheInsert replaced External Database "
1862 "%p with one already cached %p\n", *Pedb, edb1);
1863
1864 ensExternaldatabaseDel(Pedb);
1865
1866 Pedb = &edb1;
1867 }
1868
1869 if (edb1 && edb2 && (edb1 != edb2))
1870 ajDebug("externaldatabaseadaptorCacheInsert detected External "
1871 "Databases (%u and %u) in the identifier and name cache with "
1872 "identical names ('%S' and '%S') and releases ('%S' and '%S') "
1873 "but differnt addresses (%p and %p).\n",
1874 edb1->Identifier, edb2->Identifier,
1875 edb1->Name, edb2->Name,
1876 edb1->Release, edb2->Release,
1877 edb1, edb2);
1878
1879 if (edb1 && (!edb2))
1880 ajDebug("externaldatabaseadaptorCacheInsert detected "
1881 "Ensembl External Database %u name '%S' release '%S' "
1882 "in the identifier, but not in the name cache.\n",
1883 edb1->Identifier, edb1->Name, edb1->Release);
1884
1885 if ((!edb1) && edb2)
1886 ajDebug("externaldatabaseadaptorCacheInsert detected "
1887 "Ensembl External Database %u name '%S' release '%S' "
1888 "in the name, but not in the identifier cache.\n",
1889 edb2->Identifier, edb2->Name, edb2->Release);
1890
1891 return ajTrue;
1892 }
1893
1894
1895
1896
1897 #if AJFALSE
1898 /* @funcstatic externaldatabaseadaptorCacheRemove *****************************
1899 **
1900 ** Remove an Ensembl External database from an
1901 ** External Database Adaptor-internal cache.
1902 **
1903 ** @param [u] edba [EnsPExternaldatabaseadaptor]
1904 ** Ensembl External Database Adaptor
1905 ** @param [r] edb [const EnsPExternaldatabase]
1906 ** Ensembl External Database
1907 **
1908 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
1909 **
1910 ** @release 6.3.0
1911 ** @@
1912 ******************************************************************************/
1913
externaldatabaseadaptorCacheRemove(EnsPExternaldatabaseadaptor edba,const EnsPExternaldatabase edb)1914 static AjBool externaldatabaseadaptorCacheRemove(
1915 EnsPExternaldatabaseadaptor edba,
1916 const EnsPExternaldatabase edb)
1917 {
1918 AjIList iter = NULL;
1919 AjPList list = NULL;
1920
1921 EnsPExternaldatabase ebd0 = NULL;
1922 EnsPExternaldatabase edb1 = NULL;
1923 EnsPExternaldatabase edb2 = NULL;
1924
1925 if (!edba)
1926 return ajFalse;
1927
1928 if (!edb)
1929 return ajFalse;
1930
1931 edb1 = (EnsPExternaldatabase) ajTableRemove(
1932 edba->CacheByIdentifier,
1933 (const void *) &edb->Identifier);
1934
1935 list = (AjPList) ajTableFetchmodS(edba->CacheByName, edb->Name);
1936
1937 if (list)
1938 {
1939 iter = ajListIterNew(list);
1940
1941 while (!ajListIterDone(iter))
1942 {
1943 edb0 = (EnsPExternaldatabase) ajListIterGet(iter);
1944
1945 if (ajStrMatchS(edb0->Release, edb->Release))
1946 {
1947 edb2 = edb0;
1948
1949 ajListIterRemove(iter);
1950
1951 break;
1952 }
1953 }
1954
1955 ajListIterDel(&iter);
1956
1957 /* If the AJAX List is now empty, remove it from the AJAX Table. */
1958
1959 if (!ajListGetLength(list))
1960 {
1961 ajTableRemove(edba->CacheByName, edb->Name);
1962
1963 ajListFreeData(&list);
1964 }
1965
1966 }
1967
1968 if (edb1 && (!edb2))
1969 ajWarn("externaldatabaseadaptorCacheRemove could remove "
1970 "External Database with identifier %u '%S' "
1971 "only from the identifier cache.\n",
1972 edb->Identifier, edb->Name);
1973
1974 if ((!edb1) && edb2)
1975 ajWarn("externaldatabaseadaptorCacheRemove could remove "
1976 "External Database with identifier %u '%S' "
1977 "only from the name cache.\n",
1978 edb->Identifier, edb->Name);
1979
1980 ensExternaldatabaseDel(&edb1);
1981 ensExternaldatabaseDel(&edb2);
1982
1983 return ajTrue;
1984 }
1985
1986 #endif /* AJFALSE */
1987
1988
1989
1990
1991 /* @funcstatic externaldatabaseadaptorCacheByNameValdel ***********************
1992 **
1993 ** An ajTableSetDestroyvalue "valdel" function to clear AJAX Table value data.
1994 ** This function removes and deletes Ensembl External Database objects
1995 ** from an AJAX List object, before deleting the AJAX List object.
1996 **
1997 ** @param [d] Pvalue [void**] AJAX List address
1998 ** @see ajTableSetDestroyvalue
1999 **
2000 ** @return [void]
2001 **
2002 ** @release 6.3.0
2003 ** @@
2004 ******************************************************************************/
2005
externaldatabaseadaptorCacheByNameValdel(void ** Pvalue)2006 static void externaldatabaseadaptorCacheByNameValdel(void **Pvalue)
2007 {
2008 EnsPExternaldatabase edb = NULL;
2009
2010 if (!Pvalue)
2011 return;
2012
2013 if (!*Pvalue)
2014 return;
2015
2016 while (ajListPop(*((AjPList *) Pvalue), (void **) &edb))
2017 ensExternaldatabaseDel(&edb);
2018
2019 ajListFree((AjPList *) Pvalue);
2020
2021 return;
2022 }
2023
2024
2025
2026
2027 /* @funcstatic externaldatabaseadaptorCacheInit *******************************
2028 **
2029 ** Initialise the internal External Database cache of an
2030 ** Ensembl External Database Adaptor.
2031 **
2032 ** @param [u] edba [EnsPExternaldatabaseadaptor]
2033 ** Ensembl External Database Adaptor
2034 **
2035 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
2036 **
2037 ** @release 6.3.0
2038 ** @@
2039 ******************************************************************************/
2040
externaldatabaseadaptorCacheInit(EnsPExternaldatabaseadaptor edba)2041 static AjBool externaldatabaseadaptorCacheInit(
2042 EnsPExternaldatabaseadaptor edba)
2043 {
2044 AjBool result = AJFALSE;
2045
2046 AjPList edbs = NULL;
2047
2048 EnsPExternaldatabase edb = NULL;
2049
2050 if (!edba)
2051 return ajFalse;
2052
2053 if (edba->CacheByIdentifier)
2054 return ajFalse;
2055 else
2056 {
2057 edba->CacheByIdentifier = ajTableuintNew(0U);
2058
2059 ajTableSetDestroyvalue(
2060 edba->CacheByIdentifier,
2061 (void (*)(void **)) &ensExternaldatabaseDel);
2062 }
2063
2064 if (edba->CacheByName)
2065 return ajFalse;
2066 else
2067 {
2068 edba->CacheByName = ajTablestrNew(0U);
2069
2070 ajTableSetDestroyvalue(
2071 edba->CacheByName,
2072 (void (*)(void **)) &externaldatabaseadaptorCacheByNameValdel);
2073 }
2074
2075 edbs = ajListNew();
2076
2077 result = ensBaseadaptorFetchAll(
2078 ensExternaldatabaseadaptorGetBaseadaptor(edba),
2079 edbs);
2080
2081 while (ajListPop(edbs, (void **) &edb))
2082 {
2083 externaldatabaseadaptorCacheInsert(edba, &edb);
2084
2085 /*
2086 ** Both caches hold internal references to the
2087 ** External Database objects.
2088 */
2089
2090 ensExternaldatabaseDel(&edb);
2091 }
2092
2093 ajListFree(&edbs);
2094
2095 return result;
2096 }
2097
2098
2099
2100
2101 /* @func ensExternaldatabaseadaptorNew ****************************************
2102 **
2103 ** Default constructor for an Ensembl External Database Adaptor.
2104 **
2105 ** Ensembl Object Adaptors are singleton objects in the sense that a single
2106 ** instance of an Ensembl Object Adaptor connected to a particular database is
2107 ** sufficient to instantiate any number of Ensembl Objects from the database.
2108 ** Each Ensembl Object will have a weak reference to the Object Adaptor that
2109 ** instantiated it. Therefore, Ensembl Object Adaptors should not be
2110 ** instantiated directly, but rather obtained from the Ensembl Registry,
2111 ** which will in turn call this function if neccessary.
2112 **
2113 ** @see ensRegistryGetDatabaseadaptor
2114 ** @see ensRegistryGetExternaldatabaseadaptor
2115 **
2116 ** @param [u] dba [EnsPDatabaseadaptor] Ensembl Database Adaptor
2117 **
2118 ** @return [EnsPExternaldatabaseadaptor]
2119 ** Ensembl External Database Adaptor or NULL
2120 **
2121 ** @release 6.2.0
2122 ** @@
2123 ******************************************************************************/
2124
ensExternaldatabaseadaptorNew(EnsPDatabaseadaptor dba)2125 EnsPExternaldatabaseadaptor ensExternaldatabaseadaptorNew(
2126 EnsPDatabaseadaptor dba)
2127 {
2128 EnsPExternaldatabaseadaptor edba = NULL;
2129
2130 if (!dba)
2131 return NULL;
2132
2133 AJNEW0(edba);
2134
2135 edba->Adaptor = ensBaseadaptorNew(
2136 dba,
2137 externaldatabaseadaptorKTablenames,
2138 externaldatabaseadaptorKColumnnames,
2139 (const EnsPBaseadaptorLeftjoin) NULL,
2140 (const char *) NULL,
2141 (const char *) NULL,
2142 &externaldatabaseadaptorFetchAllbyStatement);
2143
2144 /*
2145 ** NOTE: The cache cannot be initialised here because the
2146 ** externaldatabaseadaptorCacheInit function calls
2147 ** ensBaseadaptorFetchAllbyConstraint, which calls
2148 ** externaldatabaseadaptorFetchAllbyStatement, which calls
2149 ** ensRegistryGetExternaldatabaseadaptor. At that point, however, the
2150 ** External Database Adaptor has not been stored in the Registry.
2151 ** Therefore, each ensExternaldatabaseadaptorFetch function has to test
2152 ** the presence of the adaptor-internal cache and eventually initialise
2153 ** before accessing it.
2154 **
2155 ** externaldatabaseadaptorCacheInit(edba);
2156 */
2157
2158 return edba;
2159 }
2160
2161
2162
2163
2164 /* @section destructors *******************************************************
2165 **
2166 ** Destruction destroys all internal data structures and frees the memory
2167 ** allocated for an Ensembl External Database Adaptor object.
2168 **
2169 ** @fdata [EnsPExternaldatabaseadaptor]
2170 **
2171 ** @nam3rule Del Destroy (free) an Ensembl External Database Adaptor
2172 **
2173 ** @argrule * Pedba [EnsPExternaldatabaseadaptor*]
2174 ** Ensembl External Database Adaptor address
2175 **
2176 ** @valrule * [void]
2177 **
2178 ** @fcategory delete
2179 ******************************************************************************/
2180
2181
2182
2183
2184 /* @func ensExternaldatabaseadaptorDel ****************************************
2185 **
2186 ** Default destructor for an Ensembl External Database Adaptor.
2187 **
2188 ** This function also clears the internal caches.
2189 **
2190 ** Ensembl Object Adaptors are singleton objects that are registered in the
2191 ** Ensembl Registry and weakly referenced by Ensembl Objects that have been
2192 ** instantiated by it. Therefore, Ensembl Object Adaptors should never be
2193 ** destroyed directly. Upon exit, the Ensembl Registry will call this function
2194 ** if required.
2195 **
2196 ** @param [d] Pedba [EnsPExternaldatabaseadaptor*] Ensembl External Database
2197 ** Adaptor object address
2198 **
2199 ** @return [void]
2200 **
2201 ** @release 6.2.0
2202 ** @@
2203 ******************************************************************************/
2204
ensExternaldatabaseadaptorDel(EnsPExternaldatabaseadaptor * Pedba)2205 void ensExternaldatabaseadaptorDel(
2206 EnsPExternaldatabaseadaptor *Pedba)
2207 {
2208 EnsPExternaldatabaseadaptor pthis = NULL;
2209
2210 if (!Pedba)
2211 return;
2212
2213 #if defined(AJ_DEBUG) && AJ_DEBUG >= 1
2214 if (ajDebugTest("ensExternaldatabaseadaptorDel"))
2215 ajDebug("ensExternaldatabaseadaptorDel\n"
2216 " *Pedba %p\n",
2217 *Pedba);
2218 #endif /* defined(AJ_DEBUG) && AJ_DEBUG >= 1 */
2219
2220 if (!(pthis = *Pedba))
2221 return;
2222
2223 ajTableDel(&pthis->CacheByIdentifier);
2224 ajTableDel(&pthis->CacheByName);
2225
2226 ensBaseadaptorDel(&pthis->Adaptor);
2227
2228 ajMemFree((void **) Pedba);
2229
2230 return;
2231 }
2232
2233
2234
2235
2236 /* @section member retrieval **************************************************
2237 **
2238 ** Functions for returning members of an Ensembl External Database Adaptor
2239 ** object.
2240 **
2241 ** @fdata [EnsPExternaldatabaseadaptor]
2242 **
2243 ** @nam3rule Get Return Ensembl External Database Adaptor attribute(s)
2244 ** @nam4rule Baseadaptor Return the Ensembl Base Adaptor
2245 ** @nam4rule Databaseadaptor Return the Ensembl Database Adaptor
2246 **
2247 ** @argrule * edba [EnsPExternaldatabaseadaptor]
2248 ** Ensembl External Database Adaptor
2249 **
2250 ** @valrule Baseadaptor [EnsPBaseadaptor]
2251 ** Ensembl Base Adaptor or NULL
2252 ** @valrule Databaseadaptor [EnsPDatabaseadaptor]
2253 ** Ensembl Database Adaptor or NULL
2254 **
2255 ** @fcategory use
2256 ******************************************************************************/
2257
2258
2259
2260
2261 /* @func ensExternaldatabaseadaptorGetBaseadaptor *****************************
2262 **
2263 ** Get the Ensembl Base Adaptor member of an
2264 ** Ensembl External Database Adaptor.
2265 **
2266 ** @param [u] edba [EnsPExternaldatabaseadaptor]
2267 ** Ensembl External Database Adaptor
2268 **
2269 ** @return [EnsPBaseadaptor] Ensembl Base Adaptor or NULL
2270 **
2271 ** @release 6.3.0
2272 ** @@
2273 ******************************************************************************/
2274
ensExternaldatabaseadaptorGetBaseadaptor(EnsPExternaldatabaseadaptor edba)2275 EnsPBaseadaptor ensExternaldatabaseadaptorGetBaseadaptor(
2276 EnsPExternaldatabaseadaptor edba)
2277 {
2278 return (edba) ? edba->Adaptor : NULL;
2279 }
2280
2281
2282
2283
2284 /* @func ensExternaldatabaseadaptorGetDatabaseadaptor *************************
2285 **
2286 ** Get the Ensembl Database Adaptor member of an
2287 ** Ensembl External Database Adaptor.
2288 **
2289 ** @param [u] edba [EnsPExternaldatabaseadaptor]
2290 ** Ensembl External Database Adaptor
2291 **
2292 ** @return [EnsPDatabaseadaptor] Ensembl Database Adaptor or NULL
2293 **
2294 ** @release 6.3.0
2295 ** @@
2296 ******************************************************************************/
2297
ensExternaldatabaseadaptorGetDatabaseadaptor(EnsPExternaldatabaseadaptor edba)2298 EnsPDatabaseadaptor ensExternaldatabaseadaptorGetDatabaseadaptor(
2299 EnsPExternaldatabaseadaptor edba)
2300 {
2301 return ensBaseadaptorGetDatabaseadaptor(
2302 ensExternaldatabaseadaptorGetBaseadaptor(edba));
2303 }
2304
2305
2306
2307
2308 /* @section object retrieval **************************************************
2309 **
2310 ** Functions for fetching Ensembl External Database objects from an
2311 ** Ensembl SQL database.
2312 **
2313 ** @fdata [EnsPExternaldatabaseadaptor]
2314 **
2315 ** @nam3rule Fetch Fetch Ensembl External Database object(s)
2316 ** @nam4rule All Fetch all Ensembl External Database objects
2317 ** @nam5rule Allby Fetch all Ensembl External Database objects
2318 ** matching a criterion
2319 ** @nam4rule By Fetch one Ensembl External Database object
2320 ** matching a criterion
2321 ** @nam5rule Identifier Fetch by an SQL database-internal identifier
2322 ** @nam5rule Name Fetch by a name
2323 **
2324 ** @argrule * edba [EnsPExternaldatabaseadaptor]
2325 ** Ensembl External Database Adaptor
2326 ** @argrule All edbs [AjPList] AJAX List of Ensembl External Database objects
2327 ** @argrule ByIdentifier identifier [ajuint] SQL database-internal identifier
2328 ** @argrule ByIdentifier Pedb [EnsPExternaldatabase*]
2329 ** Ensembl External Database address
2330 ** @argrule ByName name [const AjPStr] Database name
2331 ** @argrule ByName release [const AjPStr] Database release
2332 ** @argrule ByName Pedb [EnsPExternaldatabase*]
2333 ** Ensembl External Database address
2334 **
2335 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
2336 **
2337 ** @fcategory use
2338 ******************************************************************************/
2339
2340
2341
2342
2343 /* @funcstatic externaldatabaseadaptorFetchAll ********************************
2344 **
2345 ** An ajTableMap "apply" function to return all External Database objects from
2346 ** the Ensembl External Database Adaptor-internal cache.
2347 **
2348 ** @param [u] key [const void*] AJAX unsigned integer key data address
2349 ** @param [u] Pvalue [void**] Ensembl External Database value data address
2350 ** @param [u] cl [void*] AJAX List of Ensembl External Database objects,
2351 ** passed in via ajTableMap
2352 ** @see ajTableMap
2353 **
2354 ** @return [void]
2355 **
2356 ** @release 6.3.0
2357 ** @@
2358 ******************************************************************************/
2359
externaldatabaseadaptorFetchAll(const void * key,void ** Pvalue,void * cl)2360 static void externaldatabaseadaptorFetchAll(const void *key,
2361 void **Pvalue,
2362 void *cl)
2363 {
2364 if (!key)
2365 return;
2366
2367 if (!Pvalue)
2368 return;
2369
2370 if (!*Pvalue)
2371 return;
2372
2373 if (!cl)
2374 return;
2375
2376 ajListPushAppend(
2377 (AjPList) cl,
2378 (void *) ensExternaldatabaseNewRef(
2379 *((EnsPExternaldatabase *) Pvalue)));
2380
2381 return;
2382 }
2383
2384
2385
2386
2387 /* @func ensExternaldatabaseadaptorFetchAll ***********************************
2388 **
2389 ** Fetch all Ensembl External Databases.
2390 **
2391 ** The caller is responsible for deleting the Ensembl External Databases
2392 ** before deleting the AJAX List.
2393 **
2394 ** @cc Bio::EnsEMBL::DBSQL::BaseAdaptor::fetch_all
2395 ** @param [u] edba [EnsPExternaldatabaseadaptor] Ensembl External
2396 ** Database Adaptor
2397 ** @param [u] edbs [AjPList] AJAX List of Ensembl External Databases
2398 **
2399 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
2400 **
2401 ** @release 6.3.0
2402 ** @@
2403 ******************************************************************************/
2404
ensExternaldatabaseadaptorFetchAll(EnsPExternaldatabaseadaptor edba,AjPList edbs)2405 AjBool ensExternaldatabaseadaptorFetchAll(
2406 EnsPExternaldatabaseadaptor edba,
2407 AjPList edbs)
2408 {
2409 if (!edba)
2410 return ajFalse;
2411
2412 if (!edbs)
2413 return ajFalse;
2414
2415 if (!edba->CacheByIdentifier)
2416 externaldatabaseadaptorCacheInit(edba);
2417
2418 ajTableMap(edba->CacheByIdentifier,
2419 &externaldatabaseadaptorFetchAll,
2420 (void *) edbs);
2421
2422 return ajTrue;
2423 }
2424
2425
2426
2427
2428 /* @func ensExternaldatabaseadaptorFetchByIdentifier **************************
2429 **
2430 ** Fetch an Ensembl External Database by its SQL database-internal identifier.
2431 **
2432 ** The caller is responsible for deleting the Ensembl External Database.
2433 **
2434 ** @cc Bio::EnsEMBL::DBSQL::BaseAdaptor::fetch_by_dbID
2435 ** @param [u] edba [EnsPExternaldatabaseadaptor]
2436 ** Ensembl External Database Adaptor
2437 ** @param [r] identifier [ajuint] SQL database-internal identifier
2438 ** @param [wP] Pedb [EnsPExternaldatabase*] Ensembl External Database address
2439 **
2440 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
2441 **
2442 ** @release 6.2.0
2443 ** @@
2444 ******************************************************************************/
2445
ensExternaldatabaseadaptorFetchByIdentifier(EnsPExternaldatabaseadaptor edba,ajuint identifier,EnsPExternaldatabase * Pedb)2446 AjBool ensExternaldatabaseadaptorFetchByIdentifier(
2447 EnsPExternaldatabaseadaptor edba,
2448 ajuint identifier,
2449 EnsPExternaldatabase *Pedb)
2450 {
2451 AjBool result = AJFALSE;
2452
2453 if (!edba)
2454 return ajFalse;
2455
2456 if (!identifier)
2457 return ajFalse;
2458
2459 if (!Pedb)
2460 return ajFalse;
2461
2462 if (ajDebugTest("ensExternaldatabaseadaptorFetchByIdentifier"))
2463 ajDebug("ensExternaldatabaseadaptorFetchByIdentifier\n"
2464 " edba %p\n"
2465 " identifier %u\n"
2466 " Pedb %p\n",
2467 edba,
2468 identifier,
2469 Pedb);
2470
2471 /*
2472 ** Initially, search the identifier cache.
2473 ** For any object returned by the AJAX Table the reference counter needs
2474 ** to be incremented manually.
2475 */
2476
2477 if (!edba->CacheByIdentifier)
2478 externaldatabaseadaptorCacheInit(edba);
2479
2480 *Pedb = (EnsPExternaldatabase) ajTableFetchmodV(
2481 edba->CacheByIdentifier,
2482 (const void *) &identifier);
2483
2484 if (*Pedb)
2485 {
2486 ensExternaldatabaseNewRef(*Pedb);
2487
2488 return ajTrue;
2489 }
2490
2491 /* In case of a cache miss, re-query the database. */
2492
2493 result = ensBaseadaptorFetchByIdentifier(
2494 ensExternaldatabaseadaptorGetBaseadaptor(edba),
2495 identifier,
2496 (void **) Pedb);
2497
2498 externaldatabaseadaptorCacheInsert(edba, Pedb);
2499
2500 return result;
2501 }
2502
2503
2504
2505
2506 /* @func ensExternaldatabaseadaptorFetchByName ********************************
2507 **
2508 ** Fetch an Ensembl External Database by its name.
2509 **
2510 ** The caller is responsible for deleting the Ensembl External Database.
2511 **
2512 ** @param [u] edba [EnsPExternaldatabaseadaptor] Ensembl External Database
2513 ** Adaptor
2514 ** @param [r] name [const AjPStr] Database name
2515 ** @param [r] release [const AjPStr] Database release
2516 ** @param [wP] Pedb [EnsPExternaldatabase*] Ensembl External Database address
2517 **
2518 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
2519 **
2520 ** @release 6.3.0
2521 ** @@
2522 ******************************************************************************/
2523
ensExternaldatabaseadaptorFetchByName(EnsPExternaldatabaseadaptor edba,const AjPStr name,const AjPStr release,EnsPExternaldatabase * Pedb)2524 AjBool ensExternaldatabaseadaptorFetchByName(
2525 EnsPExternaldatabaseadaptor edba,
2526 const AjPStr name,
2527 const AjPStr release,
2528 EnsPExternaldatabase *Pedb)
2529 {
2530 char *txtname = NULL;
2531 char *txtrelease = NULL;
2532
2533 AjBool result = AJFALSE;
2534
2535 AjIList iter = NULL;
2536 AjPList edbs = NULL;
2537 AjPList list = NULL;
2538
2539 AjPStr constraint = NULL;
2540
2541 EnsPBaseadaptor ba = NULL;
2542
2543 EnsPExternaldatabase edb = NULL;
2544
2545 if (!edba)
2546 return ajFalse;
2547
2548 if (!(name && ajStrGetLen(name)))
2549 return ajFalse;
2550
2551 if (!(release && ajStrGetLen(release)))
2552 return ajFalse;
2553
2554 if (!Pedb)
2555 return ajFalse;
2556
2557 *Pedb = NULL;
2558
2559 /*
2560 ** Initially, search the name cache.
2561 ** For any object returned by the AJAX Table the reference counter needs
2562 ** to be incremented manually.
2563 */
2564
2565 if (!edba->CacheByName)
2566 externaldatabaseadaptorCacheInit(edba);
2567
2568 list = (AjPList) ajTableFetchmodS(edba->CacheByName, name);
2569
2570 if (list)
2571 {
2572 iter = ajListIterNew(list);
2573
2574 while (!ajListIterDone(iter))
2575 {
2576 edb = (EnsPExternaldatabase) ajListIterGet(iter);
2577
2578 if (ajStrMatchS(edb->Release, release))
2579 {
2580 *Pedb = edb;
2581
2582 break;
2583 }
2584 }
2585
2586 ajListIterDel(&iter);
2587 }
2588
2589 if (*Pedb)
2590 {
2591 ensExternaldatabaseNewRef(*Pedb);
2592
2593 return ajTrue;
2594 }
2595
2596 /* In case of a cache miss, re-query the database. */
2597
2598 ba = ensExternaldatabaseadaptorGetBaseadaptor(edba);
2599
2600 ensBaseadaptorEscapeC(ba, &txtname, name);
2601 ensBaseadaptorEscapeC(ba, &txtrelease, release);
2602
2603 constraint = ajFmtStr("external_db.db_name = '%s' "
2604 "AND "
2605 "external_db.db_release = '%s'",
2606 txtname,
2607 txtrelease);
2608
2609 ajCharDel(&txtname);
2610 ajCharDel(&txtrelease);
2611
2612 edbs = ajListNew();
2613
2614 result = ensBaseadaptorFetchAllbyConstraint(
2615 ba,
2616 constraint,
2617 (EnsPAssemblymapper) NULL,
2618 (EnsPSlice) NULL,
2619 edbs);
2620
2621 if (ajListGetLength(edbs) > 1)
2622 ajWarn("ensExternaldatabaseadaptorFetchByName got more "
2623 "than one Ensembl External Database for name '%S' "
2624 "and release '%S'.\n",
2625 name, release);
2626
2627 ajListPop(edbs, (void **) Pedb);
2628
2629 externaldatabaseadaptorCacheInsert(edba, Pedb);
2630
2631 while (ajListPop(edbs, (void **) &edb))
2632 {
2633 externaldatabaseadaptorCacheInsert(edba, &edb);
2634
2635 ensExternaldatabaseDel(&edb);
2636 }
2637
2638 ajListFree(&edbs);
2639
2640 ajStrDel(&constraint);
2641
2642 return result;
2643 }
2644