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 *  Representation of a plug-in object of SBML's package
013 * extension.
014 <p>
015 * Additional attributes and/or elements of a package extension which are directly 
016 * contained by some pre-defined element are contained/accessed by <a href='#{@link SBasePlugin}'> 
017 * {@link SBasePlugin} </a> class which is extended by package developers for each extension point.
018 * The extension point, which represents an element to be extended, is identified by a 
019 * combination of a Package name and a typecode of the element, and is represented by
020 * {@link SBaseExtensionPoint} class.
021 * </p>
022 <p>
023 <p>
024 * For example, the layout extension defines <em>&lt;listOfLayouts&gt;</em> element which is 
025 * directly contained in <em>&lt;model&gt;</em> element of the core package. 
026 * In the layout package (provided as one of example packages in libSBML-5), the additional 
027 * element for the model element is implemented as {@link ListOfLayouts} class (an {@link SBase} derived class) and 
028 * the object is contained/accessed by a {@link LayoutModelPlugin} class (an {@link SBasePlugin} derived class). 
029 * </p>
030 <p>
031 <p>
032 * {@link SBasePlugin} class defines basic virtual functions for reading/writing/checking 
033 * additional attributes and/or top-level elements which should or must be overridden by 
034 * subclasses like {@link SBase} class and its derived classes.
035 * </p>
036 <p>
037 <p>
038 *  Package developers must implement an {@link SBasePlugin} exntended class for 
039 *  each element to be extended (e.g. {@link SBMLDocument}, {@link Model}, ...) in which additional 
040 *  attributes and/or top-level elements of the package extension are directly contained.
041 *</p>
042 <p>
043 *  To implement reading/writing functions for attributes and/or top-level 
044 *  elements of the SBsaePlugin extended class, package developers should or must
045 *  override the corresponding virtual functions below provided in the {@link SBasePlugin} class:
046 <p>
047 *   <ul>
048 *     <li> <p>reading elements : </p>
049 *       <ol>
050 *         <li> <code>virtual {@link SBase} createObject (XMLInputStream stream) </code>
051 <p>This function must be overridden if one or more additional elements are defined.</p>
052 *         </li>
053 *         <li> <code>virtual boolean readOtherXML (SBase parentObject, {@link XMLInputStream} stream)</code>
054 <p>This function should be overridden if elements of annotation, notes, MathML, etc. need 
055 *            to be directly parsed from the given {@link XMLInputStream} object .
056 *         </p> 
057 *         </li>
058 *       </ol>
059 *     </li>
060 *     <li> <p>reading attributes (must be overridden if additional attributes are defined) :</p>
061 *       <ol>
062 *         <li><code>virtual void addExpectedAttributes(ExpectedAttributes& attributes) </code></li>
063 *         <li><code>virtual void readAttributes (XMLAttributes attributes, const ExpectedAttributes& expectedAttributes)</code></li>
064 *       </ol>
065 *     </li>
066 *     <li> <p>writing elements (must be overridden if additional elements are defined) :</p>
067 *       <ol>
068 *         <li><code>virtual void writeElements (XMLOutputStream stream) const </code></li>
069 *       </ol>
070 *     </li>
071 *     <li> <p>writing attributes : </p>
072 *       <ol>
073 *        <li><code>virtual void writeAttributes (XMLOutputStream stream) const </code>
074 <p>This function must be overridden if one or more additional attributes are defined.</p>
075 *        </li>
076 *        <li><code>virtual void writeXMLNS (XMLOutputStream stream) const </code>
077 <p>This function must be overridden if one or more additional xmlns attributes are defined.</p>
078 *        </li>
079 *       </ol>
080 *     </li>
081 <p>
082 *     <li> <p>checking elements (should be overridden) :</p>
083 *       <ol>
084 *         <li><code>virtual boolean hasRequiredElements() const </code></li>
085 *       </ol>
086 *     </li>
087 <p>
088 *     <li> <p>checking attributes (should be overridden) :</p>
089 *       <ol>
090 *         <li><code>virtual boolean hasRequiredAttributes() const </code></li>
091 *       </ol>
092 *     </li>
093 *   </ul>
094 <p>
095 <p>
096 *   To implement package-specific creating/getting/manipulating functions of the
097 *   {@link SBasePlugin} derived class (e.g., getListOfLayouts(), createLyout(), getLayout(),
098 *   and etc are implemented in {@link LayoutModelPlugin} class of the layout package), package
099 *   developers must newly implement such functions (as they like) in the derived class.
100 *</p>
101 <p>
102 <p>
103 *   {@link SBasePlugin} class defines other virtual functions of internal implementations
104 *   such as:
105 <p>
106 *   <ul>
107 *    <li><code> virtual void setSBMLDocument(SBMLDocument d) </code>
108 *    <li><code> virtual void connectToParent(SBase sbase) </code>
109 *    <li><code> virtual void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) </code>
110 *   </ul>
111 <p>
112 *   These functions must be overridden by subclasses in which one or more top-level elements are defined.
113 *</p>
114 <p>
115 <p>
116 *   For example, the following three {@link SBasePlugin} extended classes are implemented in
117 *   the layout extension:
118 *</p>
119 <p>
120 *<ol>
121 <p>
122 *  <li> <p><a href='class_s_b_m_l_document_plugin.html'> {@link SBMLDocumentPlugin} </a> class for {@link SBMLDocument} element</p>
123 <p>
124 *    <ul>
125 *         <li> <em> required </em> attribute is added to {@link SBMLDocument} object.
126 *         </li>
127 *    </ul>
128 <p>
129 <p>
130 *(<a href='class_s_b_m_l_document_plugin.html'> {@link SBMLDocumentPlugin} </a> class is a common {@link SBasePlugin} 
131 *extended class for {@link SBMLDocument} class. Package developers can use this class as-is if no additional 
132 *elements/attributes (except for <em> required </em> attribute) is needed for the {@link SBMLDocument} class 
133 *in their packages, otherwise package developers must implement a new {@link SBMLDocumentPlugin} derived class.)
134 *</p>
135 <p>
136 *  <li> <p>LayoutModelPlugin class for {@link Model} element</p>
137 *    <ul>
138 *       <li> &lt;listOfLayouts&gt; element is added to {@link Model} object.
139 *       </li>
140 <p>
141 *       <li> <p>
142 *            The following virtual functions for reading/writing/checking
143 *            are overridden: (type of arguments and return values are omitted)
144 *            </p>
145 *           <ul>
146 *              <li> <code> createObject() </code> : (read elements)
147 *              </li>
148 *              <li> <code> readOtherXML() </code> : (read elements in annotation of SBML L2)
149 *              </li>
150 *              <li> <code> writeElements() </code> : (write elements)
151 *              </li>
152 *           </ul>
153 *       </li>
154 <p>
155 *        <li> <p>
156 *             The following virtual functions of internal implementations
157 *             are overridden: (type of arguments and return values are omitted)
158 *            </p>  
159 *            <ul>
160 *              <li> <code> setSBMLDocument() </code> 
161 *              </li>
162 *              <li> <code> connectToParent() </code>
163 *              </li>
164 *              <li> <code> enablePackageInternal() </code>
165 *              </li>
166 *            </ul>
167 *        </li>
168 <p>
169 <p>
170 *        <li> <p>
171 *             The following creating/getting/manipulating functions are newly 
172 *             implemented: (type of arguments and return values are omitted)
173 *            </p>
174 *            <ul>
175 *              <li> <code> getListOfLayouts() </code>
176 *              </li>
177 *              <li> <code> getLayout ()  </code>
178 *              </li>
179 *              <li> <code> addLayout() </code>
180 *              </li>
181 *              <li> <code> createLayout() </code>
182 *              </li>
183 *              <li> <code> removeLayout() </code>
184 *              </li>    
185 *              <li> <code> getNumLayouts() </code>
186 *              </li>
187 *           </ul>
188 *        </li>
189 <p>
190 *    </ul>
191 *  </li>
192 <p>
193 *  <li> <p>LayoutSpeciesReferencePlugin class for {@link SpeciesReference} element (used only for SBML L2V1) </p>
194 <p>
195 *      <ul>
196 *        <li>
197 *         <em> id </em> attribute is internally added to {@link SpeciesReference} object
198 *          only for SBML L2V1 
199 *        </li>
200 <p>
201 *        <li>
202 *         The following virtual functions for reading/writing/checking
203 *          are overridden: (type of arguments and return values are omitted)
204 *        </li>
205 <p>
206 *         <ul>
207 *          <li>
208 *          <code> readOtherXML() </code>
209 *          </li>
210 *          <li>
211 *          <code> writeAttributes() </code>
212 *          </li>
213 *        </ul>
214 *      </ul>
215 *    </li>
216 <p>
217 * </ol>
218 */
219
220public class SBasePlugin {
221   private long swigCPtr;
222   protected boolean swigCMemOwn;
223
224   protected SBasePlugin(long cPtr, boolean cMemoryOwn)
225   {
226     swigCMemOwn = cMemoryOwn;
227     swigCPtr    = cPtr;
228   }
229
230   protected static long getCPtr(SBasePlugin obj)
231   {
232     return (obj == null) ? 0 : obj.swigCPtr;
233   }
234
235   protected static long getCPtrAndDisown (SBasePlugin obj)
236   {
237     long ptr = 0;
238
239     if (obj != null)
240     {
241       ptr             = obj.swigCPtr;
242       obj.swigCMemOwn = false;
243     }
244
245     return ptr;
246   }
247
248  protected void finalize() {
249    delete();
250  }
251
252  public synchronized void delete() {
253    if (swigCPtr != 0) {
254      if (swigCMemOwn) {
255        swigCMemOwn = false;
256        libsbmlJNI.delete_SBasePlugin(swigCPtr);
257      }
258      swigCPtr = 0;
259    }
260  }
261
262  
263/**
264   * Returns the XML namespace (URI) of the package extension
265   * of this plugin object.
266   <p>
267   * @return the URI of the package extension of this plugin object.
268   */ public
269 String getElementNamespace() {
270    return libsbmlJNI.SBasePlugin_getElementNamespace(swigCPtr, this);
271  }
272
273  
274/**
275   * Returns the prefix of the package extension of this plugin object.
276   <p>
277   * @return the prefix of the package extension of this plugin object.
278   */ public
279 String getPrefix() {
280    return libsbmlJNI.SBasePlugin_getPrefix(swigCPtr, this);
281  }
282
283  
284/**
285   * Returns the package name of this plugin object.
286   <p>
287   * @return the package name of this plugin object.
288   */ public
289 String getPackageName() {
290    return libsbmlJNI.SBasePlugin_getPackageName(swigCPtr, this);
291  }
292
293  
294/**
295   * Creates and returns a deep copy of this {@link SBasePlugin} object.
296   <p>
297   * @return a (deep) copy of this {@link SBase} object
298   */ public
299 SBasePlugin cloneObject() {
300    return libsbml.DowncastSBasePlugin(libsbmlJNI.SBasePlugin_cloneObject(swigCPtr, this), true);
301}
302
303  
304/**
305   * Returns the first child element found that has the given <code>id</code> in the model-wide SId namespace, or <code>null</code> if no such object is found.
306   <p>
307   * @param id string representing the id of objects to find
308   <p>
309   * @return pointer to the first element found with the given <code>id</code>.
310   */ public
311 SBase getElementBySId(String id) {
312  return libsbml.DowncastSBase(libsbmlJNI.SBasePlugin_getElementBySId(swigCPtr, this, id), false);
313}
314
315  
316/**
317   * Returns the first child element it can find with the given <code>metaid</code>, or <code>null</code> if no such object is found.
318   <p>
319   * @param metaid string representing the metaid of objects to find
320   <p>
321   * @return pointer to the first element found with the given <code>metaid</code>.
322   */ public
323 SBase getElementByMetaId(String metaid) {
324  return libsbml.DowncastSBase(libsbmlJNI.SBasePlugin_getElementByMetaId(swigCPtr, this, metaid), false);
325}
326
327  
328/**
329   * Sets the parent SBML object of this plugin object to
330   * this object and child elements (if any).
331   * (Creates a child-parent relationship by this plugin object)
332   <p>
333   * This function is called when this object is created by
334   * the parent element.
335   * Subclasses must override this this function if they have one
336   * or more child elements. Also, {@link SBasePlugin#connectToParent(SBase sbase)}
337   * must be called in the overridden function.
338   <p>
339   * @param sbase the {@link SBase} object to use
340   <p>
341   <p>
342   * @internal
343   */ public
344 void connectToParent(SBase sbase) {
345    libsbmlJNI.SBasePlugin_connectToParent(swigCPtr, this, SBase.getCPtr(sbase), sbase);
346  }
347
348  
349/**
350   * Enables/Disables the given package with child elements in this plugin 
351   * object (if any).
352   * (This is an internal implementation invoked from 
353   *  {@link SBase#enablePackageInternal()} function)
354   <p>
355   * Subclasses which contain one or more {@link SBase} derived elements should 
356   * override this function if elements defined in them can be extended by
357   * some other package extension.
358   <p>
359   <p>
360   * @internal
361   */ public
362 void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) {
363    libsbmlJNI.SBasePlugin_enablePackageInternal(swigCPtr, this, pkgURI, pkgPrefix, flag);
364  }
365
366  
367/** * @internal */ public
368 boolean stripPackage(String pkgPrefix, boolean flag) {
369    return libsbmlJNI.SBasePlugin_stripPackage(swigCPtr, this, pkgPrefix, flag);
370  }
371
372  
373/**
374   * Returns the parent {@link SBMLDocument} of this plugin object.
375   <p>
376   * @return the parent {@link SBMLDocument} object of this plugin object.
377   */ public
378 SBMLDocument getSBMLDocument() {
379    long cPtr = libsbmlJNI.SBasePlugin_getSBMLDocument__SWIG_0(swigCPtr, this);
380    return (cPtr == 0) ? null : new SBMLDocument(cPtr, false);
381  }
382
383  
384/**
385   * Gets the URI to which this element belongs to.
386   * For example, all elements that belong to SBML Level 3 Version 1 Core
387   * must would have the URI 'http://www.sbml.org/sbml/level3/version1/core'; 
388   * all elements that belong to {@link Layout} Extension Version 1 for SBML Level 3
389   * Version 1 Core must would have the URI
390   * 'http://www.sbml.org/sbml/level3/version1/layout/version1/'
391   <p>
392   * Unlike getElementNamespace, this function first returns the URI for this 
393   * element by looking into the {@link SBMLNamespaces} object of the document with 
394   * the its package name. if not found it will return the result of 
395   * getElementNamespace
396   <p>
397   * @return the URI this elements  
398   <p>
399   * @see #getPackageName()
400   * @see #getElementNamespace()
401   * @see SBMLDocument#getSBMLNamespaces()
402   * @see #getSBMLDocument()
403   */ public
404 String getURI() {
405    return libsbmlJNI.SBasePlugin_getURI(swigCPtr, this);
406  }
407
408  
409/**
410   * Returns the parent {@link SBase} object to which this plugin 
411   * object connected.
412   <p>
413   * @return the parent {@link SBase} object to which this plugin 
414   * object connected.
415   */ public
416 SBase getParentSBMLObject() {
417  return libsbml.DowncastSBase(libsbmlJNI.SBasePlugin_getParentSBMLObject__SWIG_0(swigCPtr, this), false);
418}
419
420  
421/**
422   * Sets the XML namespace to which this element belongs to.
423   * For example, all elements that belong to SBML Level 3 Version 1 Core
424   * must set the namespace to 'http://www.sbml.org/sbml/level3/version1/core'; 
425   * all elements that belong to {@link Layout} Extension Version 1 for SBML Level 3
426   * Version 1 Core must set the namespace to 
427   * 'http://www.sbml.org/sbml/level3/version1/layout/version1/'
428   <p>
429   * @return integer value indicating success/failure of the
430   * function.   The possible values
431   * returned by this function are:
432   * <ul>
433   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
434   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
435   * </ul>
436   */ public
437 int setElementNamespace(String uri) {
438    return libsbmlJNI.SBasePlugin_setElementNamespace(swigCPtr, this, uri);
439  }
440
441  
442/**
443   * Returns the SBML level of the package extension of 
444   * this plugin object.
445   <p>
446   * @return the SBML level of the package extension of
447   * this plugin object.
448   */ public
449 long getLevel() {
450    return libsbmlJNI.SBasePlugin_getLevel(swigCPtr, this);
451  }
452
453  
454/**
455   * Returns the SBML version of the package extension of
456   * this plugin object.
457   <p>
458   * @return the SBML version of the package extension of
459   * this plugin object.
460   */ public
461 long getVersion() {
462    return libsbmlJNI.SBasePlugin_getVersion(swigCPtr, this);
463  }
464
465  
466/**
467   * Returns the package version of the package extension of
468   * this plugin object.
469   <p>
470   * @return the package version of the package extension of
471   * this plugin object.
472   */ public
473 long getPackageVersion() {
474    return libsbmlJNI.SBasePlugin_getPackageVersion(swigCPtr, this);
475  }
476
477  
478/**
479   * If this object has a child 'math' object (or anything with ASTNodes in general), replace all nodes with the name 'id' with the provided function. 
480   <p>
481   * @note This function does nothing itself--subclasses with {@link ASTNode} subelements must override this function.
482   * @internal
483   */ public
484 void replaceSIDWithFunction(String id, ASTNode function) {
485    libsbmlJNI.SBasePlugin_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
486  }
487
488  
489/**
490   * If the function of this object is to assign a value has a child 'math' object (or anything with ASTNodes in general), replace  the 'math' object with the function (existing/function).  
491   <p>
492   * @note This function does nothing itself--subclasses with {@link ASTNode} subelements must override this function.
493   * @internal
494   */ public
495 void divideAssignmentsToSIdByFunction(String id, ASTNode function) {
496    libsbmlJNI.SBasePlugin_divideAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
497  }
498
499  
500/**
501   * If this assignment assigns a value to the 'id' element, replace the 'math' object with the function (existing*function). 
502   * @internal 
503   */ public
504 void multiplyAssignmentsToSIdByFunction(String id, ASTNode function) {
505    libsbmlJNI.SBasePlugin_multiplyAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
506  }
507
508  
509/**
510   * Check to see if the given prefix is used by any of the IDs defined by extension elements.  A package that defines its own 'id' attribute for a core element would check that attribute here.
511   * @internal
512   */ public
513 boolean hasIdentifierBeginningWith(String prefix) {
514    return libsbmlJNI.SBasePlugin_hasIdentifierBeginningWith(swigCPtr, this, prefix);
515  }
516
517  
518/**
519   * Add the given string to all identifiers in the object.  If the string is added to anything other than an id or a metaid, this code is responsible for tracking down and renaming all *idRefs in the package extention that identifier comes from.
520   * @internal
521   */ public
522 int prependStringToAllIdentifiers(String prefix) {
523    return libsbmlJNI.SBasePlugin_prependStringToAllIdentifiers(swigCPtr, this, prefix);
524  }
525
526  
527/** * @internal */ public
528 int transformIdentifiers(IdentifierTransformer sidTransformer) {
529    return libsbmlJNI.SBasePlugin_transformIdentifiers(swigCPtr, this, IdentifierTransformer.getCPtr(sidTransformer), sidTransformer);
530  }
531
532  
533/**
534   * Returns the line number on which this object first appears in the XML
535   * representation of the SBML document.
536   <p>
537   * @return the line number of the underlying SBML object.
538   <p>
539   * @note The line number for each construct in an SBML model is set upon
540   * reading the model.  The accuracy of the line number depends on the
541   * correctness of the XML representation of the model, and on the
542   * particular XML parser library being used.  The former limitation
543   * relates to the following problem: if the model is actually invalid
544   * XML, then the parser may not be able to interpret the data correctly
545   * and consequently may not be able to establish the real line number.
546   * The latter limitation is simply that different parsers seem to have
547   * their own accuracy limitations, and out of all the parsers supported
548   * by libSBML, none have been 100% accurate in all situations. (At this
549   * time, libSBML supports the use of <a target='_blank'
550   * href='http://xmlsoft.org'>libxml2</a>, <a target='_blank'
551   * href='http://expat.sourceforge.net/'>Expat</a> and <a target='_blank'
552   * href='http://xerces.apache.org/xerces-c/'>Xerces</a>.)
553   <p>
554   * @see #getColumn()
555   * @internal
556   */ public
557 long getLine() {
558    return libsbmlJNI.SBasePlugin_getLine(swigCPtr, this);
559  }
560
561  
562/**
563   * Returns the column number on which this object first appears in the XML
564   * representation of the SBML document.
565   <p>
566   * @return the column number of the underlying SBML object.
567   <p>
568   * @note The column number for each construct in an SBML model is set
569   * upon reading the model.  The accuracy of the column number depends on
570   * the correctness of the XML representation of the model, and on the
571   * particular XML parser library being used.  The former limitation
572   * relates to the following problem: if the model is actually invalid
573   * XML, then the parser may not be able to interpret the data correctly
574   * and consequently may not be able to establish the real column number.
575   * The latter limitation is simply that different parsers seem to have
576   * their own accuracy limitations, and out of all the parsers supported
577   * by libSBML, none have been 100% accurate in all situations. (At this
578   * time, libSBML supports the use of <a target='_blank'
579   * href='http://xmlsoft.org'>libxml2</a>, <a target='_blank'
580   * href='http://expat.sourceforge.net/'>Expat</a> and <a target='_blank'
581   * href='http://xerces.apache.org/xerces-c/'>Xerces</a>.)
582   <p>
583   * @see #getLine()
584   * @internal
585   */ public
586 long getColumn() {
587    return libsbmlJNI.SBasePlugin_getColumn(swigCPtr, this);
588  }
589
590  
591/** * @internal */ public
592 SBMLNamespaces getSBMLNamespaces() {
593  return libsbml.DowncastSBMLNamespaces(libsbmlJNI.SBasePlugin_getSBMLNamespaces(swigCPtr, this), false);
594}
595
596  
597/**
598   * Helper to log a common type of error for elements.
599   * @internal
600   */ public
601 void logUnknownElement(String element, long sbmlLevel, long sbmlVersion, long pkgVersion) {
602    libsbmlJNI.SBasePlugin_logUnknownElement(swigCPtr, this, element, sbmlLevel, sbmlVersion, pkgVersion);
603  }
604
605  public SBaseList getListOfAllElements(ElementFilter filter) {
606    long cPtr = libsbmlJNI.SBasePlugin_getListOfAllElements__SWIG_0(swigCPtr, this, ElementFilter.getCPtr(filter), filter);
607    return (cPtr == 0) ? null : new SBaseList(cPtr, false);
608  }
609
610  public SBaseList getListOfAllElements() {
611    long cPtr = libsbmlJNI.SBasePlugin_getListOfAllElements__SWIG_1(swigCPtr, this);
612    return (cPtr == 0) ? null : new SBaseList(cPtr, false);
613  }
614
615}