001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.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 *  Base class for SBML Level 3 package plug-ins.
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 * The {@link SBMLExtension} class is a component of the libSBML package extension
023 * mechanism.  It is an abstract class that is extended by each package
024 * extension implementation. 
025 <p>
026 * <p>
027 * <h2>Basic principles of SBML package extensions in libSBML</h2>
028 <p>
029 * SBML Level&nbsp;3's package structure permits modular extensions to the
030 * core SBML format.  In libSBML, support for SBML Level&nbsp;3 packages is
031 * provided through optional <em>package extensions</em> that can be plugged
032 * into libSBML at the time it is built/compiled.  Users of libSBML can thus
033 * choose which extensions are enabled in their software applications.
034 <p>
035 * LibSBML defines a number of classes that developers of package extensions
036 * can use to implement support for an SBML Level&nbsp;3 package.  These
037 * classes make it easier to extend libSBML objects with new attributes
038 * and/or subobjects as needed by a particular Level&nbsp;3 package.
039 * Three overall categories of classes make up libSBML's facilities for
040 * implementing package extensions.  There are (1) classes that serve as base
041 * classes meant to be subclassed, (2) template classes meant to be
042 * instantiated rather than subclassed, and (3) support classes that provide
043 * utility features. A given package implementation for libSBML will take
044 * the form of code using these and other libSBML classes, placed in a
045 * subdirectory of <code>src/sbml/packages/</code>.
046 <p>
047 * The basic libSBML distribution includes a number of package extensions
048 * implementing support for officially-endorsed SBML Level&nbsp;3 packages;
049 * among these are <em>Flux Balance Constraints</em> ('fbc'),
050 * <em>Hierarchical Model Composition</em> ('comp'), <em>Layout</em>
051 * ('layout'), and <em>Qualitative Models</em> ('qual').  They can serve as
052 * working examples for developers working to implement other packages.
053 <p>
054 * Extensions in libSBML can currently only be implemented in C++ or C;
055 * there is no mechanism to implement them first in languages such as
056 * Java or Python.  However, once implemented in C++ or C, language
057 * interfaces can be generated semi-automatically using the framework in
058 * place in libSBML.  (The approach is based on using <a target='_blank'
059 * href='http://www.swig.org'>SWIG</a> and facilities in libSBML's build
060 * system.)
061 <p>
062 * <h2>Special handling for SBML Level&nbsp;2</h2>
063 * <p>
064 * Due to the historical background of the SBML Layout package, libSBML
065 * implements special behavior for that package: it <em>always</em> creates a
066 * Layout plugin object for any SBML Level&nbsp;2 document it reads in,
067 * regardless of whether that document actually uses Layout constructs.  This
068 * is unlike the case for SBML Level&nbsp;3 documents that use Layout; for
069 * them, libSBML will <em>not</em> create a plugin object unless the document
070 * actually declares the use of the Layout package (via the usual Level&nbsp;3
071 * namespace declaration for Level&nbsp;3 packages).
072 <p>
073 * This has the following consequence.  If an application queries for the
074 * presence of Layout in an SBML Level&nbsp;2 document by testing only for
075 * the existence of the plugin object, <strong>it will always get a positive
076 * result</strong>; in other words, the presence of a Layout extension
077 * object is not an indication of whether a read-in Level&nbsp;2 document
078 * does or does not use SBML Layout.  Instead, callers have to query
079 * explicitly for the existence of layout information.  An example of such a
080 * query is the following code:
081 <p>
082<pre class='fragment'>
083// Assume 'doc' below is an {@link SBMLDocument} object.
084{@link Model} m = doc.getModel();
085{@link LayoutModelPlugin} lmp = (LayoutModelPlugin) m.getPlugin('layout');
086if (lmp != null)
087{
088  int numLayouts = lmp.getNumLayouts();
089  // If numLayouts is greater than zero, then the model uses {@link Layout}.
090}
091</pre>
092<p>
093 * The special, always-available Level&nbsp;2 Layout behavior was motivated
094 * by a desire to support legacy applications.  In SBML Level&nbsp;3, the
095 * Layout package uses the normal SBML Level&nbsp;3 scheme of requiring
096 * declarations on the SBML document element.  This means that upon reading a
097 * model, libSBML knows right away whether it contains layout information.
098 * In SBML Level&nbsp;2, there is no top-level declaration because layout is
099 * stored as annotations in the body of the model.  Detecting the presence of
100 * layout information when reading a Level&nbsp;2 model requires parsing the
101 * annotations.  For efficiency reasons, libSBML normally does not parse
102 * annotations automatically when reading a model.  However, applications
103 * that predated the introduction of Level&nbsp;3 Layout and the updated
104 * version of libSBML never had to do anything special to enable parsing
105 * layout; the facilities were always available for every Level&nbsp;2 model
106 * as long as libSBML was compiled with Layout support.  To avoid burdening
107 * developers of legacy applications with the need to modify their software,
108 * libSBML provides backward compatibility by always preloading the Layout
109 * package extension when reading Level&nbsp;2 models.  The same applies to
110 * the creation of Level&nbsp;2 models: with the plugin-oriented libSBML,
111 * applications normally would have to take deliberate steps to activate
112 * package code, instantiate objects, manage namespaces, and so on.  LibSBML
113 * again loads the Layout package plugin automatically when creating a
114 * Level&nbsp;2 model, thereby making the APIs available to legacy
115 * applications without further work on their part.
116 */
117
118public class SBMLExtension {
119   private long swigCPtr;
120   protected boolean swigCMemOwn;
121
122   protected SBMLExtension(long cPtr, boolean cMemoryOwn)
123   {
124     swigCMemOwn = cMemoryOwn;
125     swigCPtr    = cPtr;
126   }
127
128   protected static long getCPtr(SBMLExtension obj)
129   {
130     return (obj == null) ? 0 : obj.swigCPtr;
131   }
132
133   protected static long getCPtrAndDisown (SBMLExtension obj)
134   {
135     long ptr = 0;
136
137     if (obj != null)
138     {
139       ptr             = obj.swigCPtr;
140       obj.swigCMemOwn = false;
141     }
142
143     return ptr;
144   }
145
146  protected void finalize() {
147    delete();
148  }
149
150  public synchronized void delete() {
151    if (swigCPtr != 0) {
152      if (swigCMemOwn) {
153        swigCMemOwn = false;
154        libsbmlJNI.delete_SBMLExtension(swigCPtr);
155      }
156      swigCPtr = 0;
157    }
158  }
159
160  /**
161   * SBMLExtension derived classes must override this method
162   * @internal
163   */
164  public SBasePlugin DowncastSBasePlugin(long cPtr, boolean owner)
165  {
166    if (cPtr == 0) return null;
167
168    return new SBasePlugin(cPtr,false);
169  }
170
171
172  /**
173   * SBMLExtension derived classes must override this method
174   * @internal
175   */
176  public SBase DowncastSBase(long cPtr, boolean owner)
177  {
178    if (cPtr == 0) return null;
179
180    return new SBase(cPtr, owner);
181  }
182
183  
184/**
185   * Returns the number of SBasePluginCreatorBase objects stored in this
186   * object.
187   <p>
188   * @return the total number of SBasePluginCreatorBase objects stored in
189   * this {@link SBMLExtension}-derived object.
190   */ public
191 int getNumOfSBasePlugins() {
192    return libsbmlJNI.SBMLExtension_getNumOfSBasePlugins(swigCPtr, this);
193  }
194
195  
196/**
197   * Returns the number of supported package namespace URIs.
198   <p>
199   * @return the number of supported package XML namespace URIs of this
200   * package extension.
201   */ public
202 long getNumOfSupportedPackageURI() {
203    return libsbmlJNI.SBMLExtension_getNumOfSupportedPackageURI(swigCPtr, this);
204  }
205
206  
207/**
208   * Returns <code>true</code> if the given XML namespace URI is supported by this
209   * package extension.
210   <p>
211   * @return <code>true</code> if the given XML namespace URI (equivalent to a package
212   * version) is supported by this package extension, <code>false</code> otherwise.
213   */ public
214 boolean isSupported(String uri) {
215    return libsbmlJNI.SBMLExtension_isSupported(swigCPtr, this, uri);
216  }
217
218  
219/**
220   * Returns the nth XML namespace URI.
221   <p>
222   * @param n the index number of the namespace URI being sought.
223<p>
224   * @return a string representing the XML namespace URI understood to be
225   * supported by this package.  An empty string will be returned if there is
226   * no nth URI.
227   */ public
228 String getSupportedPackageURI(long n) {
229    return libsbmlJNI.SBMLExtension_getSupportedPackageURI(swigCPtr, this, n);
230  }
231
232  
233/**
234   * Creates and returns a deep copy of this {@link SBMLExtension} object.
235   <p>
236   * @return a (deep) copy of this {@link SBMLExtension} object.
237   <p>
238   * <p>
239 * @note
240 * This is a method that package extension implementations must override.
241 * See the libSBML documentation on extending libSBML to support SBML
242 * packages for more information on this topic.
243   */ public
244 SBMLExtension cloneObject() {
245    return libsbml.DowncastExtension(libsbmlJNI.SBMLExtension_cloneObject(swigCPtr, this), true);
246}
247
248  
249/**
250   * Returns the nickname of this package.
251   <p>
252   * This returns the short-form name of an SBML Level&nbsp;3 package
253   * implemented by a given {@link SBMLExtension}-derived class.  Examples of
254   * such names are 'layout', 'fbc', etc.
255   <p>
256   * @return a string, the nickname of SBML package.
257   <p>
258   * <p>
259 * @note
260 * This is a method that package extension implementations must override.
261 * See the libSBML documentation on extending libSBML to support SBML
262 * packages for more information on this topic.
263   */ public
264 String getName() {
265    return libsbmlJNI.SBMLExtension_getName(swigCPtr, this);
266  }
267
268  
269/**
270   * Returns the XML namespace URI for a given Level and Version.
271   <p>
272   * @param sbmlLevel the SBML Level.
273   * @param sbmlVersion the SBML Version.
274   * @param pkgVersion the version of the package.
275   <p>
276   * @return a string, the XML namespace URI for the package for the given
277   * SBML Level, SBML Version, and package version.
278   <p>
279   * <p>
280 * @note
281 * This is a method that package extension implementations must override.
282 * See the libSBML documentation on extending libSBML to support SBML
283 * packages for more information on this topic.
284   */ public
285 String getURI(long sbmlLevel, long sbmlVersion, long pkgVersion) {
286    return libsbmlJNI.SBMLExtension_getURI(swigCPtr, this, sbmlLevel, sbmlVersion, pkgVersion);
287  }
288
289  
290/**
291   * Returns the SBML Level associated with the given XML namespace URI.
292   <p>
293   * @param uri the string of URI that represents a version of the package.
294   <p>
295   * @return the SBML Level associated with the given URI of this package.
296   <p>
297   * <p>
298 * @note
299 * This is a method that package extension implementations must override.
300 * See the libSBML documentation on extending libSBML to support SBML
301 * packages for more information on this topic.
302   */ public
303 long getLevel(String uri) {
304    return libsbmlJNI.SBMLExtension_getLevel(swigCPtr, this, uri);
305  }
306
307  
308/**
309   * Returns the SBML Version associated with the given XML namespace URI.
310   <p>
311   * @param uri the string of URI that represents a version of the package.
312   <p>
313   * @return the SBML Version associated with the given URI of this package.
314   <p>
315   * <p>
316 * @note
317 * This is a method that package extension implementations must override.
318 * See the libSBML documentation on extending libSBML to support SBML
319 * packages for more information on this topic.
320   */ public
321 long getVersion(String uri) {
322    return libsbmlJNI.SBMLExtension_getVersion(swigCPtr, this, uri);
323  }
324
325  
326/**
327   * Returns the package version associated with the given XML namespace URI.
328   <p>
329   * @param uri the string of URI that represents a version of this package.
330   <p>
331   * @return the package version associated with the given URI of this package.
332   <p>
333   * <p>
334 * @note
335 * This is a method that package extension implementations must override.
336 * See the libSBML documentation on extending libSBML to support SBML
337 * packages for more information on this topic.
338   */ public
339 long getPackageVersion(String uri) {
340    return libsbmlJNI.SBMLExtension_getPackageVersion(swigCPtr, this, uri);
341  }
342
343  
344/**
345   * Returns a string representation of a type code.
346   <p>
347   * This method takes a numerical type code <code>typeCode</code> for a component
348   * object implemented by this package extension, and returns a string
349   * representing that type code.
350   <p>
351   * @param typeCode the type code to turn into a string.
352   <p>
353   * @return the string representation of <code>typeCode</code>.
354   <p>
355   * <p>
356 * @note
357 * This is a method that package extension implementations must override.
358 * See the libSBML documentation on extending libSBML to support SBML
359 * packages for more information on this topic.
360   */ public
361 String getStringFromTypeCode(int typeCode) {
362    return libsbmlJNI.SBMLExtension_getStringFromTypeCode(swigCPtr, this, typeCode);
363  }
364
365  
366/**
367   * Returns a specialized {@link SBMLNamespaces} object corresponding to a given
368   * namespace URI.
369   <p>
370   * LibSBML package extensions each define a subclass of
371   * {@link SBMLNamespaces}.
372   <p>
373   * The present method returns the appropriate object corresponding
374   * to the given XML namespace URI in argument <code>uri</code>.
375   <p>
376   * @param uri the namespace URI that represents one of versions of the
377   * package implemented in this extension.
378   <p>
379   * @return an {@link SBMLNamespaces}  
380   * object, or <code>null</code> if the given <code>uri</code> is not defined in the
381   * corresponding package.
382   <p>
383   * <p>
384 * @note
385 * This is a method that package extension implementations must override.
386 * See the libSBML documentation on extending libSBML to support SBML
387 * packages for more information on this topic.
388   */ public
389 SBMLNamespaces getSBMLExtensionNamespaces(String uri) {
390  return libsbml.DowncastSBMLNamespaces(libsbmlJNI.SBMLExtension_getSBMLExtensionNamespaces(swigCPtr, this, uri), false);
391}
392
393  
394/**
395   * Enable or disable this package.
396   <p>
397   * @param isEnabled flag indicating whether to enable (if <code>true</code>) or
398   * disable (<code>false</code>) this package extension.
399   <p>
400   * @return <code>true</code> if this call succeeded; <code>false</code> otherwise.
401   */ public
402 boolean setEnabled(boolean isEnabled) {
403    return libsbmlJNI.SBMLExtension_setEnabled(swigCPtr, this, isEnabled);
404  }
405
406  
407/**
408   * Returns <code>true</code> if this package is enabled.
409   <p>
410   * @return <code>true</code> if this package is enabled, <code>false</code> otherwise.
411   */ public
412 boolean isEnabled() {
413    return libsbmlJNI.SBMLExtension_isEnabled(swigCPtr, this);
414  }
415
416  
417/**
418   * Removes the package's Level&nbsp;2 namespace(s).
419   <p>
420   * @internal 
421   <p>
422   * <p>
423 * This method is related to special facilities designed to support
424 * legacy behaviors surrounding SBML Level&nbsp;2 models.  Due to the
425 * historical background of the SBML Layout package, libSBML implements
426 * special behavior for that package: it <em>always</em> creates a Layout
427 * plugin object for any SBML Level&nbsp;2 document it reads in,
428 * regardless of whether that document actually uses Layout constructs.
429 * Since Level&nbsp;2 does not use namespaces on the top level of the
430 * SBML document object, libSBML simply keys off the fact that the model
431 * is a Level&nbsp;2 model.  To allow the extensions for the Layout and
432 * Render (and possibly other) packages to support this behavior, the
433 * {@link SBMLExtension} class contains special methods to allow packages to
434 * hook themselves into the Level&nbsp;2 parsing apparatus when necessary.
435   <p>
436   * @param xmlns an {@link XMLNamespaces} object that will be used for the annotation.
437   * Implementations should override this method with something that removes
438   * the package's namespace(s) from the set of namespaces in <code>xmlns</code>.  For
439   * instance, here is the code from the Layout package extension:
440   * <pre class='fragment'>{.cpp}
441for (int n = 0; n &lt; xmlns-&gt;getNumNamespaces(); n++)
442{
443  if (xmlns-&gt;getURI(n) == {@link LayoutExtension#getXmlnsL2()})
444    xmlns-&gt;remove(n);
445}
446</pre>
447   */ public
448 void removeL2Namespaces(XMLNamespaces xmlns) {
449    libsbmlJNI.SBMLExtension_removeL2Namespaces(swigCPtr, this, XMLNamespaces.getCPtr(xmlns), xmlns);
450  }
451
452  
453/**
454   * Adds the package's Level&nbsp;2 namespace(s).
455   <p>
456   * @internal 
457   <p>
458   * <p>
459 * This method is related to special facilities designed to support
460 * legacy behaviors surrounding SBML Level&nbsp;2 models.  Due to the
461 * historical background of the SBML Layout package, libSBML implements
462 * special behavior for that package: it <em>always</em> creates a Layout
463 * plugin object for any SBML Level&nbsp;2 document it reads in,
464 * regardless of whether that document actually uses Layout constructs.
465 * Since Level&nbsp;2 does not use namespaces on the top level of the
466 * SBML document object, libSBML simply keys off the fact that the model
467 * is a Level&nbsp;2 model.  To allow the extensions for the Layout and
468 * Render (and possibly other) packages to support this behavior, the
469 * {@link SBMLExtension} class contains special methods to allow packages to
470 * hook themselves into the Level&nbsp;2 parsing apparatus when necessary.
471   <p>
472   * @param xmlns an {@link XMLNamespaces} object that will be used for the annotation.
473   * Implementation should override this method with something that adds
474   * the package's namespace(s) to the set of namespaces in <code>xmlns</code>.  For
475   * instance, here is the code from the Layout package extension:
476   * <pre class='fragment'>{.cpp}
477if (!xmlns-&gt;containsUri( {@link LayoutExtension#getXmlnsL2()}))
478  xmlns-&gt;add({@link LayoutExtension#getXmlnsL2()}, 'layout');
479</pre>
480   */ public
481 void addL2Namespaces(XMLNamespaces xmlns) {
482    libsbmlJNI.SBMLExtension_addL2Namespaces(swigCPtr, this, XMLNamespaces.getCPtr(xmlns), xmlns);
483  }
484
485  
486/**
487   * Called to enable the package on the {@link SBMLDocument} object.
488   <p>
489   * @internal 
490   <p>
491   * <p>
492 * This method is related to special facilities designed to support
493 * legacy behaviors surrounding SBML Level&nbsp;2 models.  Due to the
494 * historical background of the SBML Layout package, libSBML implements
495 * special behavior for that package: it <em>always</em> creates a Layout
496 * plugin object for any SBML Level&nbsp;2 document it reads in,
497 * regardless of whether that document actually uses Layout constructs.
498 * Since Level&nbsp;2 does not use namespaces on the top level of the
499 * SBML document object, libSBML simply keys off the fact that the model
500 * is a Level&nbsp;2 model.  To allow the extensions for the Layout and
501 * Render (and possibly other) packages to support this behavior, the
502 * {@link SBMLExtension} class contains special methods to allow packages to
503 * hook themselves into the Level&nbsp;2 parsing apparatus when necessary.
504   <p>
505   * @param doc the {@link SBMLDocument} object for the model.
506   * Implementations should override this method with something that
507   * enables the package based on the package's namespace(s). For example,
508   * here is the code from the Layout package extension:
509   * <pre class='fragment'>{.cpp}
510if (doc-&gt;getLevel() == 2)
511  doc-&gt;enablePackage({@link LayoutExtension#getXmlnsL2()}, 'layout', true);
512</pre>
513   */ public
514 void enableL2NamespaceForDocument(SBMLDocument doc) {
515    libsbmlJNI.SBMLExtension_enableL2NamespaceForDocument(swigCPtr, this, SBMLDocument.getCPtr(doc), doc);
516  }
517
518  
519/**
520   * Indicates whether this extension is being used by the given {@link SBMLDocument}.
521   <p>
522   * The default implementation returns <code>true.</code>  This means that when a
523   * document had this extension enabled, it will not be possible to convert
524   * it to SBML Level&nbsp;2 as we cannot make sure that the extension can be
525   * converted.
526   <p>
527   * @param doc the SBML document to test.
528   <p>
529   * @return a boolean indicating whether the extension is actually being
530   * used by the document.
531   */ public
532 boolean isInUse(SBMLDocument doc) {
533    return libsbmlJNI.SBMLExtension_isInUse(swigCPtr, this, SBMLDocument.getCPtr(doc), doc);
534  }
535
536  
537/** * @internal */ public
538 boolean hasMultipleVersions() {
539    return libsbmlJNI.SBMLExtension_hasMultipleVersions(swigCPtr, this);
540  }
541
542  
543/** * @internal */ public
544 long getErrorTableIndex(long errorId) {
545    return libsbmlJNI.SBMLExtension_getErrorTableIndex(swigCPtr, this, errorId);
546  }
547
548  
549/** * @internal */ public
550 long getErrorIdOffset() {
551    return libsbmlJNI.SBMLExtension_getErrorIdOffset(swigCPtr, this);
552  }
553
554  
555/** * @internal */ public
556 long getSeverity(long index, long pkgVersion) {
557    return libsbmlJNI.SBMLExtension_getSeverity(swigCPtr, this, index, pkgVersion);
558  }
559
560  
561/** * @internal */ public
562 long getCategory(long index) {
563    return libsbmlJNI.SBMLExtension_getCategory(swigCPtr, this, index);
564  }
565
566  
567/** * @internal */ public
568 String getMessage(long index, long pkgVersion, String details) {
569    return libsbmlJNI.SBMLExtension_getMessage(swigCPtr, this, index, pkgVersion, details);
570  }
571
572  
573/** * @internal */ public
574 String getShortMessage(long index) {
575    return libsbmlJNI.SBMLExtension_getShortMessage(swigCPtr, this, index);
576  }
577
578}