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&nbsp;2 and Level&nbsp;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>&lt;annotation&gt;</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>&lt;annotation&gt;</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 &lt;annotation&gt; 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&nbsp;6 of the SBML
250   * Level&nbsp;2 (Versions 2&ndash;4) and SBML Level&nbsp;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&lt;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/' &gt;
283
284&lt;/rdf:RDF&gt;
285</pre></div>
286   * <p>
287   * Note that this does not create the containing SBML
288   * <code>&lt;annotation&gt;</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>&lt;annotation&gt;</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}