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&nbsp;2 and Level&nbsp;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>&lt;annotation&gt;</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>&lt;annotation&gt;</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 &lt;annotation&gt; 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&nbsp;6 of the SBML
179   * Level&nbsp;2 (Versions 2&ndash;4) and SBML Level&nbsp;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&lt;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/' &gt;
207
208&lt;/rdf:RDF&gt;
209</pre></div>
210   <p>
211   * Note that this does not create the containing SBML
212   * <code>&lt;annotation&gt;</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>&lt;annotation&gt;</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}