001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.7
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&nbsp;2 and Level&nbsp;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>&lt;annotation&gt;</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>&lt;annotation&gt;</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 &lt;annotation&gt;.
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&nbsp;6 of the SBML
178   * Level&nbsp;2 (Versions 2&ndash;4) and SBML Level&nbsp;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&lt;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/' &gt;
206
207&lt;/rdf:RDF&gt;
208</pre>
209   <p>
210   * Note that this does not create the containing SBML
211   * <code>&lt;annotation&gt;</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&lt;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/' &gt;
240
241&lt;/rdf:RDF&gt;
242</pre>
243   <p>
244   * Note that this does not create the containing SBML
245   * <code>&lt;annotation&gt;</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&lt;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/' &gt;
274
275&lt;/rdf:RDF&gt;
276</pre>
277   <p>
278   * Note that this does not create the containing SBML
279   * <code>&lt;annotation&gt;</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>&lt;annotation&gt;</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}