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