001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.11 004 * 005 * Do not make changes to this file unless you know what you are doing--modify 006 * the SWIG interface file instead. 007 * ----------------------------------------------------------------------------- */ 008 009package org.sbml.libsbml; 010 011/** 012 * 013 * Read/write/manipulate RDF annotations stored in SBML 014 * annotation elements. 015 * <p> 016 * <p style='color: #777; font-style: italic'> 017This class of objects is defined by libSBML only and has no direct 018equivalent in terms of SBML components. This class is not prescribed by 019the SBML specifications, although it is used to implement features 020defined in SBML. 021</p> 022 023 * <p> 024 * {@link RDFAnnotationParser} is a libSBML construct used as part of the libSBML 025 * support for annotations conforming to the guidelines specified by MIRIAM 026 * ('Minimum Information Requested in the Annotation of biochemical 027 * Models', <i>Nature Biotechnology</i>, vol. 23, no. 12, Dec. 2005). 028 * Section 6 of the SBML Level 2 and Level 3 specification 029 * documents defines a recommended way of encoding MIRIAM information using 030 * a subset of RDF in SBML. The general scheme is as follows. A set of 031 * RDF-based annotations attached to a given SBML 032 * <code><annotation></code> element are read by {@link RDFAnnotationParser} 033 * and converted into a list of {@link CVTerm} objects. There 034 * are different versions of the main method, 035 * {@link RDFAnnotationParser#parseRDFAnnotation(XMLNode annotation, CVTermList CVTerms)} 036 * and {@link RDFAnnotationParser#parseRDFAnnotation(XMLNode annotation)}, 037 * used depending on whether the annotation in question concerns the MIRIAM 038 * model history or other MIRIAM resource annotations. A special object 039 * class, {@link ModelHistory}, is used to make it easier to manipulate model 040 * history annotations. 041 * <p> 042 * All of the methods on {@link RDFAnnotationParser} are static; the class exists 043 * only to encapsulate the annotation and {@link CVTerm} parsing and manipulation 044 * functionality. 045 */ 046 047public class RDFAnnotationParser { 048 private long swigCPtr; 049 protected boolean swigCMemOwn; 050 051 protected RDFAnnotationParser(long cPtr, boolean cMemoryOwn) 052 { 053 swigCMemOwn = cMemoryOwn; 054 swigCPtr = cPtr; 055 } 056 057 protected static long getCPtr(RDFAnnotationParser obj) 058 { 059 return (obj == null) ? 0 : obj.swigCPtr; 060 } 061 062 protected static long getCPtrAndDisown (RDFAnnotationParser obj) 063 { 064 long ptr = 0; 065 066 if (obj != null) 067 { 068 ptr = obj.swigCPtr; 069 obj.swigCMemOwn = false; 070 } 071 072 return ptr; 073 } 074 075 protected void finalize() { 076 delete(); 077 } 078 079 public synchronized void delete() { 080 if (swigCPtr != 0) { 081 if (swigCMemOwn) { 082 swigCMemOwn = false; 083 libsbmlJNI.delete_RDFAnnotationParser(swigCPtr); 084 } 085 swigCPtr = 0; 086 } 087 } 088 089 090/** 091 * Parses an annotation (given as an {@link XMLNode} tree) into a list of 092 * {@link CVTerm} objects. 093 * <p> 094 * This is used to take an annotation that has been read into an SBML 095 * model, identify the RDF elements within it, and create a list of 096 * corresponding {@link CVTerm} (controlled vocabulary term) objects. 097 * <p> 098 * @param annotation {@link XMLNode} containing the annotation. 099 * <p> 100 * @param CVTerms list of {@link CVTerm} objects to be created. 101 * @param stream optional XMLInputStream that facilitates error logging 102 * @param metaId optional metaId, if set only the rdf annotation for this metaId will be returned. 103 * <p> 104 * @note Because this is a <em>static</em> method, the non-C++ 105 * language interfaces for libSBML will contain two variants. One will 106 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 107 * other will be a standalone top-level function with the name 108 * RDFAnnotationParser_parseRDFAnnotation(). They are functionally 109 * identical. 110 * <p> 111 * @see RDFAnnotationParser#parseRDFAnnotation(XMLNode annotation) 112 */ public 113 static void parseRDFAnnotation(XMLNode annotation, SWIGTYPE_p_List CVTerms, String metaId, XMLInputStream stream) { 114 libsbmlJNI.RDFAnnotationParser_parseRDFAnnotation__SWIG_0(XMLNode.getCPtr(annotation), annotation, SWIGTYPE_p_List.getCPtr(CVTerms), metaId, XMLInputStream.getCPtr(stream), stream); 115 } 116 117 118/** 119 * Parses an annotation (given as an {@link XMLNode} tree) into a list of 120 * {@link CVTerm} objects. 121 * <p> 122 * This is used to take an annotation that has been read into an SBML 123 * model, identify the RDF elements within it, and create a list of 124 * corresponding {@link CVTerm} (controlled vocabulary term) objects. 125 * <p> 126 * @param annotation {@link XMLNode} containing the annotation. 127 * <p> 128 * @param CVTerms list of {@link CVTerm} objects to be created. 129 * @param stream optional XMLInputStream that facilitates error logging 130 * @param metaId optional metaId, if set only the rdf annotation for this metaId will be returned. 131 * <p> 132 * @note Because this is a <em>static</em> method, the non-C++ 133 * language interfaces for libSBML will contain two variants. One will 134 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 135 * other will be a standalone top-level function with the name 136 * RDFAnnotationParser_parseRDFAnnotation(). They are functionally 137 * identical. 138 * <p> 139 * @see RDFAnnotationParser#parseRDFAnnotation(XMLNode annotation) 140 */ public 141 static void parseRDFAnnotation(XMLNode annotation, SWIGTYPE_p_List CVTerms, String metaId) { 142 libsbmlJNI.RDFAnnotationParser_parseRDFAnnotation__SWIG_1(XMLNode.getCPtr(annotation), annotation, SWIGTYPE_p_List.getCPtr(CVTerms), metaId); 143 } 144 145 146/** 147 * Parses an annotation into a {@link ModelHistory} class instance. 148 * <p> 149 * This is used to take an annotation that has been read into an SBML 150 * model, identify the RDF elements representing model history 151 * information, and create a list of corresponding {@link CVTerm} objects. 152 * <p> 153 * @param annotation {@link XMLNode} containing the annotation. 154 * @param stream optional XMLInputStream that facilitates error logging 155 * @param metaId optional metaId, if set only the rdf annotation for this metaId will be returned. 156 * <p> 157 * @note Because this is a <em>static</em> method, the non-C++ 158 * language interfaces for libSBML will contain two variants. One will 159 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 160 * other will be a standalone top-level function with the name 161 * RDFAnnotationParser_parseRDFAnnotation(). They are functionally 162 * identical. 163 * <p> 164 * @return a pointer to the {@link ModelHistory} created. 165 */ public 166 static ModelHistory parseRDFAnnotation(XMLNode annotation, String metaId, XMLInputStream stream) { 167 long cPtr = libsbmlJNI.RDFAnnotationParser_parseRDFAnnotation__SWIG_2(XMLNode.getCPtr(annotation), annotation, metaId, XMLInputStream.getCPtr(stream), stream); 168 return (cPtr == 0) ? null : new ModelHistory(cPtr, false); 169 } 170 171 172/** 173 * Parses an annotation into a {@link ModelHistory} class instance. 174 * <p> 175 * This is used to take an annotation that has been read into an SBML 176 * model, identify the RDF elements representing model history 177 * information, and create a list of corresponding {@link CVTerm} objects. 178 * <p> 179 * @param annotation {@link XMLNode} containing the annotation. 180 * @param stream optional XMLInputStream that facilitates error logging 181 * @param metaId optional metaId, if set only the rdf annotation for this metaId will be returned. 182 * <p> 183 * @note Because this is a <em>static</em> method, the non-C++ 184 * language interfaces for libSBML will contain two variants. One will 185 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 186 * other will be a standalone top-level function with the name 187 * RDFAnnotationParser_parseRDFAnnotation(). They are functionally 188 * identical. 189 * <p> 190 * @return a pointer to the {@link ModelHistory} created. 191 */ public 192 static ModelHistory parseRDFAnnotation(XMLNode annotation, String metaId) { 193 long cPtr = libsbmlJNI.RDFAnnotationParser_parseRDFAnnotation__SWIG_3(XMLNode.getCPtr(annotation), annotation, metaId); 194 return (cPtr == 0) ? null : new ModelHistory(cPtr, false); 195 } 196 197 198/** 199 * Parses an annotation into a {@link ModelHistory} class instance. 200 * <p> 201 * This is used to take an annotation that has been read into an SBML 202 * model, identify the RDF elements representing model history 203 * information, and create a list of corresponding {@link CVTerm} objects. 204 * <p> 205 * @param annotation {@link XMLNode} containing the annotation. 206 * @param stream optional XMLInputStream that facilitates error logging 207 * @param metaId optional metaId, if set only the rdf annotation for this metaId will be returned. 208 * <p> 209 * @note Because this is a <em>static</em> method, the non-C++ 210 * language interfaces for libSBML will contain two variants. One will 211 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 212 * other will be a standalone top-level function with the name 213 * RDFAnnotationParser_parseRDFAnnotation(). They are functionally 214 * identical. 215 * <p> 216 * @return a pointer to the {@link ModelHistory} created. 217 */ public 218 static ModelHistory parseRDFAnnotation(XMLNode annotation) { 219 long cPtr = libsbmlJNI.RDFAnnotationParser_parseRDFAnnotation__SWIG_4(XMLNode.getCPtr(annotation), annotation); 220 return (cPtr == 0) ? null : new ModelHistory(cPtr, false); 221 } 222 223 224/** 225 * Creates a blank annotation and returns its root {@link XMLNode} object. 226 * <p> 227 * This creates a completely empty SBML <code><annotation></code> 228 * element. It is not attached to any SBML element. An example of how 229 * this might be used is illustrated in the following code fragment. In 230 * this example, suppose that <code>content</code> is an {@link XMLNode} object previously 231 * created, containing MIRIAM-style annotations, and that <code>sbmlObject</code> 232 * is an SBML object derived from {@link SBase} (e.g., a {@link Model}, or a {@link Species}, or 233 * a {@link Compartment}, etc.). Then:<div class='fragment'><pre> 234int success; // Status code variable, used below. 235 236{@link XMLNode} RDF = createRDFAnnotation(); // Create RDF annotation XML structure. 237success = RDF.addChild(...content...); // Put some content into it. 238... // Check 'success' return code value. 239 240{@link XMLNode} ann = createAnnotation(); // Create <annotation> container. 241success = ann.addChild(RDF); // Put the RDF annotation into it. 242... // Check 'success' return code value. 243 244success = sbmlObject.setAnnotation(ann); // Set object's annotation to what we built. 245... // Check 'success' return code value. 246</pre></div> 247 * <p> 248 * The SBML specification contains more information about the format of 249 * annotations. We urge readers to consult Section 6 of the SBML 250 * Level 2 (Versions 2–4) and SBML Level 3 specification 251 * documents. 252 * <p> 253 * @return a pointer to an {@link XMLNode} for the annotation 254 * <p> 255 * @note Because this is a <em>static</em> method, the non-C++ 256 * language interfaces for libSBML will contain two variants. One will 257 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 258 * other will be a standalone top-level function with the name 259 * RDFAnnotationParser_createAnnotation(). They are functionally 260 * identical. 261 * <p> 262 * @see RDFAnnotationParser#createRDFAnnotation() 263 */ public 264 static XMLNode createAnnotation() { 265 long cPtr = libsbmlJNI.RDFAnnotationParser_createAnnotation(); 266 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 267 } 268 269 270/** 271 * Creates a blank RDF element suitable for use in SBML annotations. 272 * <p> 273 * The annotation created by this method has namespace declarations for 274 * all the relevant XML namespaces used in RDF annotations and also has 275 * an empty RDF element. The result is the following XML: 276<div class='fragment'><pre> 277<rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' 278 xmlns:dc='http://purl.org/dc/elements/1.1/' 279 xmlns:dcterms='http://purl.org/dc/terms/' 280 xmlns:vCard='http://www.w3.org/2001/vcard-rdf/3.0#' 281 xmlns:bqbiol='http://biomodels.net/biology-qualifiers/' 282 xmlns:bqmodel='http://biomodels.net/model-qualifiers/' > 283 284</rdf:RDF> 285</pre></div> 286 * <p> 287 * Note that this does not create the containing SBML 288 * <code><annotation></code> element; the method 289 * {@link RDFAnnotationParser#createAnnotation()} 290 * is available for creating the container. 291 * <p> 292 * @return a pointer to an {@link XMLNode} 293 * <p> 294 * @note Because this is a <em>static</em> method, the non-C++ 295 * language interfaces for libSBML will contain two variants. One will 296 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 297 * other will be a standalone top-level function with the name 298 * RDFAnnotationParser_createRDFAnnotation(). They are functionally 299 * identical. 300 * <p> 301 * @see RDFAnnotationParser#createAnnotation() 302 */ public 303 static XMLNode createRDFAnnotation() { 304 long cPtr = libsbmlJNI.RDFAnnotationParser_createRDFAnnotation(); 305 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 306 } 307 308 309/** 310 * Takes a list of {@link CVTerm} objects and creates a the RDF 'Description' 311 * element. 312 * <p> 313 * This essentially takes the given SBML object, reads out the {@link CVTerm} 314 * objects attached to it, creates an RDF 'Description' element to hold 315 * the terms, and adds each term with appropriate qualifiers. 316 * <p> 317 * @param obj the SBML object to start from 318 * <p> 319 * @return the {@link XMLNode} tree corresponding to the Description element of 320 * an RDF annotation. 321 * <p> 322 * @note Because this is a <em>static</em> method, the non-C++ 323 * language interfaces for libSBML will contain two variants. One will 324 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 325 * other will be a standalone top-level function with the name 326 * createRDFDescription(@if java {@link SBase} obj). They are functionally 327 * identical. @endif 328 */ public 329 static XMLNode createCVTerms(SBase obj) { 330 long cPtr = libsbmlJNI.RDFAnnotationParser_createCVTerms(SBase.getCPtr(obj), obj); 331 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 332 } 333 334 335/** 336 * Takes a list of {@link CVTerm} objects and creates a complete SBML annotation 337 * around it. 338 * <p> 339 * This essentially takes the given SBML object, reads out the {@link CVTerm} 340 * objects attached to it, calls * {@link RDFAnnotationParser#createRDFAnnotation()} to create an RDF 341 * annotation to hold the terms, and finally calls * {@link RDFAnnotationParser#createAnnotation()} to wrap the result as 342 * an SBML <code><annotation></code> element. 343 * <p> 344 * @param obj the SBML object to start from 345 * <p> 346 * @return the {@link XMLNode} tree corresponding to the annotation. 347 * <p> 348 * @note Because this is a <em>static</em> method, the non-C++ 349 * language interfaces for libSBML will contain two variants. One will 350 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 351 * other will be a standalone top-level function with the name 352 * RDFAnnotationParser_parseCVTerms(). They are functionally 353 * identical. 354 */ public 355 static XMLNode parseCVTerms(SBase obj) { 356 long cPtr = libsbmlJNI.RDFAnnotationParser_parseCVTerms(SBase.getCPtr(obj), obj); 357 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 358 } 359 360 361/** 362 * Reads the model history and cvTerms stored in <code>obj</code> and creates the 363 * XML structure for an SBML annotation representing that metadata if 364 * there is a model history stored in <code>obj</code>. 365 * <p> 366 * @param obj any {@link SBase} object 367 * <p> 368 * @return the {@link XMLNode} corresponding to an annotation containing 369 * MIRIAM-compliant model history and CV term information in RDF format. 370 * <p> 371 * @note If the object does not have a history element stored then 372 * <code>null</code> is returned even if CVTerms are present. 373 * <p> 374 * @note Because this is a <em>static</em> method, the non-C++ 375 * language interfaces for libSBML will contain two variants. One will 376 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 377 * other will be a standalone top-level function with the name 378 * RDFAnnotationParser_parseModelHistory(@if java Sbase obj). They 379 * are functionally identical. @endif 380 */ public 381 static XMLNode parseModelHistory(SBase obj) { 382 long cPtr = libsbmlJNI.RDFAnnotationParser_parseModelHistory(SBase.getCPtr(obj), obj); 383 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 384 } 385 386 387/** 388 * Reads the model history stored in <code>obj</code> and creates the 389 * XML structure for an SBML annotation representing that history. 390 * <p> 391 * @param obj any {@link SBase} object 392 * <p> 393 * @return the {@link XMLNode} corresponding to an annotation containing 394 * MIRIAM-compliant model history information in RDF format. 395 * <p> 396 * @note Because this is a <em>static</em> method, the non-C++ 397 * language interfaces for libSBML will contain two variants. One will 398 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 399 * other will be a standalone top-level function with the name 400 * RDFAnnotationParser_parseOnlyModelHistory(). They are functionally 401 * identical. 402 */ public 403 static XMLNode parseOnlyModelHistory(SBase obj) { 404 long cPtr = libsbmlJNI.RDFAnnotationParser_parseOnlyModelHistory(SBase.getCPtr(obj), obj); 405 return (cPtr == 0) ? null : new XMLNode(cPtr, false); 406 } 407 408 409/** 410 * Deletes any SBML MIRIAM RDF annotation found in the given {@link XMLNode} 411 * tree and returns 412 * any remaining annotation content. 413 * <p> 414 * The name of the {@link XMLNode} given as parameter <code>annotation</code> must be 415 * 'annotation', or else this method returns <code>null.</code> The method will 416 * walk down the XML structure looking for elements that are in the 417 * RDF XML namespace, and remove them if they conform to the syntax 418 * of a History or {@link CVTerm} element. 419 * <p> 420 * @param annotation the {@link XMLNode} tree within which the RDF annotation is 421 * to be found and deleted 422 * <p> 423 * @return the {@link XMLNode} structure that is left after RDF annotations are 424 * deleted. 425 * <p> 426 * @note Because this is a <em>static</em> method, the non-C++ 427 * language interfaces for libSBML will contain two variants. One will 428 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 429 * other will be a standalone top-level function with the name 430 * RDFAnnotationParser_deleteRDFAnnotation(). They are functionally 431 * identical. 432 */ public 433 static XMLNode deleteRDFAnnotation(XMLNode annotation) { 434 long cPtr = libsbmlJNI.RDFAnnotationParser_deleteRDFAnnotation(XMLNode.getCPtr(annotation), annotation); 435 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 436 } 437 438 439/** 440 * Deletes any SBML MIRIAM RDF 'History' annotation found in the given 441 * {@link XMLNode} tree and returns 442 * any remaining annotation content. 443 * <p> 444 * The name of the {@link XMLNode} given as parameter <code>annotation</code> must be 445 * 'annotation', or else this method returns <code>null.</code> The method will 446 * walk down the XML structure looking for elements that are in the 447 * RDF XML namespace, and remove any that conform to the syntax of a 448 * History element. 449 * <p> 450 * @param annotation the {@link XMLNode} tree within which the RDF annotation is 451 * to be found and deleted 452 * <p> 453 * @return the {@link XMLNode} structure that is left after RDF annotations are 454 * deleted. 455 * <p> 456 * @note Because this is a <em>static</em> method, the non-C++ 457 * language interfaces for libSBML will contain two variants. One will 458 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 459 * other will be a standalone top-level function with the name 460 * RDFAnnotationParser_deleteRDFAnnotation(). They are functionally 461 * identical. 462 */ public 463 static XMLNode deleteRDFHistoryAnnotation(XMLNode annotation) { 464 long cPtr = libsbmlJNI.RDFAnnotationParser_deleteRDFHistoryAnnotation(XMLNode.getCPtr(annotation), annotation); 465 return (cPtr == 0) ? null : new XMLNode(cPtr, false); 466 } 467 468 469/** 470 * Deletes any SBML MIRIAM RDF '{@link CVTerm}' annotation found in the given 471 * {@link XMLNode} tree and returns 472 * any remaining annotation content. 473 * <p> 474 * The name of the {@link XMLNode} given as parameter <code>annotation</code> must be 475 * 'annotation', or else this method returns <code>null.</code> The method will 476 * walk down the XML structure looking for elements that are in the 477 * RDF XML namespace, and remove any that conform to the syntax of a 478 * {@link CVTerm} element. 479 * <p> 480 * @param annotation the {@link XMLNode} tree within which the RDF annotation is 481 * to be found and deleted 482 * <p> 483 * @return the {@link XMLNode} structure that is left after RDF annotations are 484 * deleted. 485 * <p> 486 * @note Because this is a <em>static</em> method, the non-C++ 487 * language interfaces for libSBML will contain two variants. One will 488 * be a static method on the class (i.e., {@link RDFAnnotationParser}), and the 489 * other will be a standalone top-level function with the name 490 * RDFAnnotationParser_deleteRDFAnnotation(). They are functionally 491 * identical. 492 */ public 493 static XMLNode deleteRDFCVTermAnnotation(XMLNode annotation) { 494 long cPtr = libsbmlJNI.RDFAnnotationParser_deleteRDFCVTermAnnotation(XMLNode.getCPtr(annotation), annotation); 495 return (cPtr == 0) ? null : new XMLNode(cPtr, false); 496 } 497 498 public static void parseRDFAnnotation(XMLNode annotation, CVTermList CVTerms) { 499 libsbmlJNI.RDFAnnotationParser_parseRDFAnnotation__SWIG_5(XMLNode.getCPtr(annotation), annotation, CVTermList.getCPtr(CVTerms), CVTerms); 500 } 501 502 public RDFAnnotationParser() { 503 this(libsbmlJNI.new_RDFAnnotationParser(), true); 504 } 505 506}