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