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 3's package structure permits modular extensions to the 030 * core SBML format. In libSBML, support for SBML Level 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 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 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 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 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 2 document it reads in, 067 * regardless of whether that document actually uses Layout constructs. This 068 * is unlike the case for SBML Level 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 3 071 * namespace declaration for Level 3 packages). 072 <p> 073 * This has the following consequence. If an application queries for the 074 * presence of Layout in an SBML Level 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 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 2 Layout behavior was motivated 094 * by a desire to support legacy applications. In SBML Level 3, the 095 * Layout package uses the normal SBML Level 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 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 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 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 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 2 models. The same applies to 110 * the creation of Level 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 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 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 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 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 2 document it reads in, 428 * regardless of whether that document actually uses Layout constructs. 429 * Since Level 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 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 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 < xmlns->getNumNamespaces(); n++) 442{ 443 if (xmlns->getURI(n) == {@link LayoutExtension#getXmlnsL2()}) 444 xmlns->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 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 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 2 document it reads in, 464 * regardless of whether that document actually uses Layout constructs. 465 * Since Level 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 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 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->containsUri( {@link LayoutExtension#getXmlnsL2()})) 478 xmlns->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 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 2 document it reads in, 497 * regardless of whether that document actually uses Layout constructs. 498 * Since Level 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 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 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->getLevel() == 2) 511 doc->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 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}