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 * Parent class for libSBML's 'ListOfXYZ' classes. 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 ListOf} class in libSBML is a utility class that serves as the parent 023 * class for implementing the ListOf__ classes. It provides methods for 024 * working generically with the various SBML lists of objects in a program. 025 * LibSBML uses this separate list class rather than ordinary 026 * Java lists, 027 * so that it can provide the methods and features associated with {@link SBase}. 028 <p> 029 * <p> 030 * The various ListOf___ classes in SBML 031 * are merely containers used for organizing the main components of an SBML 032 * model. In libSBML's implementation, ListOf___ 033 * classes are derived from the 034 * intermediate utility class {@link ListOf}, which 035 * is not defined by the SBML specifications but serves as a useful 036 * programmatic construct. {@link ListOf} is itself is in turn derived from {@link SBase}, 037 * which provides all of the various ListOf___ 038 * classes with common features 039 * defined by the SBML specification, such as 'metaid' attributes and 040 * annotations. 041 <p> 042 * The relationship between the lists and the rest of an SBML model is 043 * illustrated by the following (for SBML Level 2 Version 4): 044 <p> 045 * <figure> 046 <object type="image/svg+xml" data="listof-illustration.svg" class="centered"></object> 047</figure> 048 049 <p> 050 * Readers may wonder about the motivations for using the ListOf___ 051 * containers in SBML. A simpler approach in XML might be to place the 052 * components all directly at the top level of the model definition. The 053 * choice made in SBML is to group them within XML elements named after 054 * ListOf<em>Classname</em>, in part because it helps organize the 055 * components. More importantly, the fact that the container classes are 056 * derived from {@link SBase} means that software tools can add information <em>about</em> 057 * the lists themselves into each list container's 'annotation'. 058 <p> 059 * @see ListOfFunctionDefinitions 060 * @see ListOfUnitDefinitions 061 * @see ListOfCompartmentTypes 062 * @see ListOfSpeciesTypes 063 * @see ListOfCompartments 064 * @see ListOfSpecies 065 * @see ListOfParameters 066 * @see ListOfInitialAssignments 067 * @see ListOfRules 068 * @see ListOfConstraints 069 * @see ListOfReactions 070 * @see ListOfEvents 071 */ 072 073public class ListOf extends SBase { 074 private long swigCPtr; 075 076 protected ListOf(long cPtr, boolean cMemoryOwn) 077 { 078 super(libsbmlJNI.ListOf_SWIGUpcast(cPtr), cMemoryOwn); 079 swigCPtr = cPtr; 080 } 081 082 protected static long getCPtr(ListOf obj) 083 { 084 return (obj == null) ? 0 : obj.swigCPtr; 085 } 086 087 protected static long getCPtrAndDisown (ListOf obj) 088 { 089 long ptr = 0; 090 091 if (obj != null) 092 { 093 ptr = obj.swigCPtr; 094 obj.swigCMemOwn = false; 095 } 096 097 return ptr; 098 } 099 100 protected void finalize() { 101 delete(); 102 } 103 104 public synchronized void delete() { 105 if (swigCPtr != 0) { 106 if (swigCMemOwn) { 107 swigCMemOwn = false; 108 libsbmlJNI.delete_ListOf(swigCPtr); 109 } 110 swigCPtr = 0; 111 } 112 super.delete(); 113 } 114 115 116/** 117 * Creates a new {@link ListOf} object. 118 <p> 119 * @param level the SBML Level; if not assigned, defaults to the 120 * value of {@link SBMLDocument#getDefaultLevel()}. 121 <p> 122 * @param version the Version within the SBML Level; if not assigned, 123 * defaults to the value of {@link SBMLDocument#getDefaultVersion()}. 124 <p> 125 * 126</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 127The native C++ implementation of this method defines a default argument 128value. In the documentation generated for different libSBML language 129bindings, you may or may not see corresponding arguments in the method 130declarations. For example, in Java and C#, a default argument is handled by 131declaring two separate methods, with one of them having the argument and 132the other one lacking the argument. However, the libSBML documentation will 133be <em>identical</em> for both methods. Consequently, if you are reading 134this and do not see an argument even though one is described, please look 135for descriptions of other variants of this method near where this one 136appears in the documentation. 137</dd></dl> 138 139 */ public 140 ListOf(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 141 this(libsbmlJNI.new_ListOf__SWIG_0(level, version), true); 142 } 143 144 145/** 146 * Creates a new {@link ListOf} object. 147 <p> 148 * @param level the SBML Level; if not assigned, defaults to the 149 * value of {@link SBMLDocument#getDefaultLevel()}. 150 <p> 151 * @param version the Version within the SBML Level; if not assigned, 152 * defaults to the value of {@link SBMLDocument#getDefaultVersion()}. 153 <p> 154 * 155</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 156The native C++ implementation of this method defines a default argument 157value. In the documentation generated for different libSBML language 158bindings, you may or may not see corresponding arguments in the method 159declarations. For example, in Java and C#, a default argument is handled by 160declaring two separate methods, with one of them having the argument and 161the other one lacking the argument. However, the libSBML documentation will 162be <em>identical</em> for both methods. Consequently, if you are reading 163this and do not see an argument even though one is described, please look 164for descriptions of other variants of this method near where this one 165appears in the documentation. 166</dd></dl> 167 168 */ public 169 ListOf(long level) throws org.sbml.libsbml.SBMLConstructorException { 170 this(libsbmlJNI.new_ListOf__SWIG_1(level), true); 171 } 172 173 174/** 175 * Creates a new {@link ListOf} object. 176 <p> 177 * @param level the SBML Level; if not assigned, defaults to the 178 * value of {@link SBMLDocument#getDefaultLevel()}. 179 <p> 180 * @param version the Version within the SBML Level; if not assigned, 181 * defaults to the value of {@link SBMLDocument#getDefaultVersion()}. 182 <p> 183 * 184</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 185The native C++ implementation of this method defines a default argument 186value. In the documentation generated for different libSBML language 187bindings, you may or may not see corresponding arguments in the method 188declarations. For example, in Java and C#, a default argument is handled by 189declaring two separate methods, with one of them having the argument and 190the other one lacking the argument. However, the libSBML documentation will 191be <em>identical</em> for both methods. Consequently, if you are reading 192this and do not see an argument even though one is described, please look 193for descriptions of other variants of this method near where this one 194appears in the documentation. 195</dd></dl> 196 197 */ public 198 ListOf() throws org.sbml.libsbml.SBMLConstructorException { 199 this(libsbmlJNI.new_ListOf__SWIG_2(), true); 200 } 201 202 203/** 204 * Creates a new {@link ListOf} with {@link SBMLNamespaces} object. 205 <p> 206 * @param sbmlns the set of SBML namespaces that this {@link ListOf} should 207 * contain. 208 */ public 209 ListOf(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 210 this(libsbmlJNI.new_ListOf__SWIG_3(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 211 } 212 213 214/** 215 * Copy constructor; creates a copy of this {@link ListOf}. 216 <p> 217 * @param orig the {@link ListOf} instance to copy. 218 */ public 219 ListOf(ListOf orig) throws org.sbml.libsbml.SBMLConstructorException { 220 this(libsbmlJNI.new_ListOf__SWIG_4(ListOf.getCPtr(orig), orig), true); 221 } 222 223 224/** 225 * Creates and returns a deep copy of this {@link ListOf}. 226 <p> 227 * @return a (deep) copy of this {@link ListOf}. 228 */ public 229 ListOf cloneObject() { 230 long cPtr = libsbmlJNI.ListOf_cloneObject(swigCPtr, this); 231 return (cPtr == 0) ? null : new ListOf(cPtr, true); 232 } 233 234 235/** 236 * Adds an item to the end of this {@link ListOf}'s list of items. 237 <p> 238 * This method makes a clone of the <code>item</code> handed to it. This means that 239 * when the {@link ListOf} object is destroyed, the original items will not be 240 * destroyed. For a method with an alternative ownership behavior, see the 241 * {@link ListOf#appendAndOwn(SBase item)} method. 242 <p> 243 * @param item the item to be added to the list. 244 <p> 245 * @see #appendAndOwn(SBase item) 246 * @see #appendFrom(ListOf list) 247 */ public 248 int append(SBase item) { 249 return libsbmlJNI.ListOf_append(swigCPtr, this, SBase.getCPtr(item), item); 250 } 251 252 253/** 254 * Adds an item to the end of this {@link ListOf}'s list of items. 255 <p> 256 * This method does not clone the <code>item</code> handed to it; instead, it assumes 257 * ownership of it. This means that when the {@link ListOf} is destroyed, the item 258 * will be destroyed along with it. For a method with an alternative 259 * ownership behavior, see the {@link ListOf#append(SBase item)} method. 260 <p> 261 * @param item the item to be added to the list. 262 <p> 263 * @see #append(SBase item) 264 * @see #appendFrom(ListOf list) 265 */ public 266 int appendAndOwn(SBase item) { 267 return libsbmlJNI.ListOf_appendAndOwn(swigCPtr, this, SBase.getCPtrAndDisown(item), item); 268 } 269 270 271/** 272 * Adds a clone of a list of items to this {@link ListOf}'s list. 273 <p> 274 * Note that because this clones the objects handed to it, the original 275 * items will not be destroyed when this {@link ListOf} object is destroyed. 276 <p> 277 * @param list a list of items to be added. 278 <p> 279 * @see #append(SBase item) 280 * @see #appendAndOwn(SBase item) 281 */ public 282 int appendFrom(ListOf list) { 283 return libsbmlJNI.ListOf_appendFrom(swigCPtr, this, ListOf.getCPtr(list), list); 284 } 285 286 287/** 288 * Inserts an item at a given position in this {@link ListOf}'s list of items. 289 <p> 290 * This variant of the method makes a clone of the <code>item</code> handed to it. 291 * This means that when the {@link ListOf} is destroyed, the original items will 292 * not be destroyed. For an alternative method with different ownership 293 * behavior, see insertAndOwn(int location, {@link SBase} item). 294 <p> 295 * @param location the location in the list where to insert the item. 296 * @param item the item to be inserted to the list. 297 <p> 298 * @see #insertAndOwn(int location, SBase item) 299 */ public 300 int insert(int location, SBase item) { 301 return libsbmlJNI.ListOf_insert(swigCPtr, this, location, SBase.getCPtr(item), item); 302 } 303 304 305/** 306 * Inserts an item at a given position in this {@link ListOf}'s list of items. 307 <p> 308 * This variant of the method makes a clone of the <code>item</code> handet to it. 309 * This means that when the {@link ListOf} is destroyed, the original items will 310 * not be destroyed. 311 <p> 312 * @param location the location where to insert the item 313 * @param item the item to be inserted to the list 314 <p> 315 * @see #insert(int location, SBase item) 316 */ public 317 int insertAndOwn(int location, SBase item) { 318 return libsbmlJNI.ListOf_insertAndOwn(swigCPtr, this, location, SBase.getCPtrAndDisown(item), item); 319 } 320 321 322/** 323 * Get an item from the list. 324 <p> 325 * @param n the index number of the item to get. 326 <p> 327 * @return the nth item in this {@link ListOf} items. 328 <p> 329 * @see #size() 330 */ public 331 SBase get(long n) { 332 return libsbml.DowncastSBase(libsbmlJNI.ListOf_get__SWIG_0(swigCPtr, this, n), false); 333} 334 335 336/** 337 * Returns the first child element found that has the given identifier. 338 <p> 339 * This method searches this {@link ListOf}'s list of items for SBML objects based 340 * on their 'id' attribute value in the model-wide SId namespace. 341 <p> 342 * @param id string representing the id of objects to find. 343 <p> 344 * @return the first element found with the given <code>id</code>, or <code>null</code> if no 345 * such object is found. 346 */ public 347 SBase getElementBySId(String id) { 348 return libsbml.DowncastSBase(libsbmlJNI.ListOf_getElementBySId(swigCPtr, this, id), false); 349} 350 351 352/** 353 * Returns the first child element found with the given <code>metaid</code>. 354 <p> 355 * @param metaid string representing the metaid of objects to find 356 <p> 357 * @return the first element found with the given <code>metaid</code>, or <code>null</code> if 358 * no such object is found. 359 */ public 360 SBase getElementByMetaId(String metaid) { 361 return libsbml.DowncastSBase(libsbmlJNI.ListOf_getElementByMetaId(swigCPtr, this, metaid), false); 362} 363 364 365/** 366 * Removes all items in this {@link ListOf} object. 367 <p> 368 * If parameter <code>doDelete</code> is <code>true</code> (default), all items in this {@link ListOf} 369 * object are deleted and cleared, and thus the caller doesn't have to 370 * delete those items. Otherwise, all items are cleared only from this 371 * {@link ListOf} object; the caller is still responsible for deleting all items. 372 * (In the latter case, callers are advised to store pointers to all items 373 * elsewhere before calling this function.) 374 <p> 375 * @param doDelete if <code>true</code> (default), all items are deleted and cleared. 376 * Otherwise, all items are just cleared and not deleted. 377 <p> 378 * 379</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 380The native C++ implementation of this method defines a default argument 381value. In the documentation generated for different libSBML language 382bindings, you may or may not see corresponding arguments in the method 383declarations. For example, in Java and C#, a default argument is handled by 384declaring two separate methods, with one of them having the argument and 385the other one lacking the argument. However, the libSBML documentation will 386be <em>identical</em> for both methods. Consequently, if you are reading 387this and do not see an argument even though one is described, please look 388for descriptions of other variants of this method near where this one 389appears in the documentation. 390</dd></dl> 391 392 */ public 393 void clear(boolean doDelete) { 394 libsbmlJNI.ListOf_clear__SWIG_0(swigCPtr, this, doDelete); 395 } 396 397 398/** 399 * Removes all items in this {@link ListOf} object. 400 <p> 401 * If parameter <code>doDelete</code> is <code>true</code> (default), all items in this {@link ListOf} 402 * object are deleted and cleared, and thus the caller doesn't have to 403 * delete those items. Otherwise, all items are cleared only from this 404 * {@link ListOf} object; the caller is still responsible for deleting all items. 405 * (In the latter case, callers are advised to store pointers to all items 406 * elsewhere before calling this function.) 407 <p> 408 * @param doDelete if <code>true</code> (default), all items are deleted and cleared. 409 * Otherwise, all items are just cleared and not deleted. 410 <p> 411 * 412</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 413The native C++ implementation of this method defines a default argument 414value. In the documentation generated for different libSBML language 415bindings, you may or may not see corresponding arguments in the method 416declarations. For example, in Java and C#, a default argument is handled by 417declaring two separate methods, with one of them having the argument and 418the other one lacking the argument. However, the libSBML documentation will 419be <em>identical</em> for both methods. Consequently, if you are reading 420this and do not see an argument even though one is described, please look 421for descriptions of other variants of this method near where this one 422appears in the documentation. 423</dd></dl> 424 425 */ public 426 void clear() { 427 libsbmlJNI.ListOf_clear__SWIG_1(swigCPtr, this); 428 } 429 430 431/** 432 * Because {@link ListOf} objects typically live as object children of their parent 433 * object and not as pointer children, this function clears itself, but 434 * does not attempt to do anything else. 435 <p> 436 * If a particular {@link ListOf} subclass does indeed exist as a pointer only, 437 * this function will need to be overridden. 438 <p> 439 * @return integer value indicating success/failure of the 440 * function. The possible values 441 * returned by this function are: 442 * <ul> 443 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 444 * </ul> 445 */ public 446 int removeFromParentAndDelete() { 447 return libsbmlJNI.ListOf_removeFromParentAndDelete(swigCPtr, this); 448 } 449 450 451/** 452 * Removes the <em>n</em>th item from this {@link ListOf} items and returns it. 453 <p> 454 * The caller owns the returned item and is responsible for deleting it. 455 <p> 456 * @param n the index of the item to remove 457 <p> 458 * @see #size() 459 */ public 460 SBase remove(long n) { 461 return libsbml.DowncastSBase(libsbmlJNI.ListOf_remove(swigCPtr, this, n), true); 462} 463 464 465/** 466 * Returns number of items in this {@link ListOf} list. 467 <p> 468 * @return the number of items in this {@link ListOf} items. 469 */ public 470 long size() { 471 return libsbmlJNI.ListOf_size(swigCPtr, this); 472 } 473 474 475/** 476 * Sets this SBML object to child SBML objects (if any). 477 * (Creates a child-parent relationship by the parent) 478 <p> 479 * Subclasses must override this function if they define 480 * one ore more child elements. 481 * Basically, this function needs to be called in 482 * constructor, copy constructor and assignment operator. 483 <p> 484 <p> 485 * @internal 486 */ public 487 void connectToChild() { 488 libsbmlJNI.ListOf_connectToChild(swigCPtr, this); 489 } 490 491 492/** 493 * Returns the libSBML type code for this object, namely, 494 * {@link libsbmlConstants#SBML_LIST_OF SBML_LIST_OF}. 495 <p> 496 * <p> 497 * LibSBML attaches an identifying code to every kind of SBML object. These 498 * are integer constants known as <em>SBML type codes</em>. The names of all 499 * the codes begin with the characters “<code>SBML_</code>”. 500 * In the Java language interface for libSBML, the 501 * type codes are defined as static integer constants in the interface class 502 * {@link libsbmlConstants}. Note that different Level 3 503 * package plug-ins may use overlapping type codes; to identify the package 504 * to which a given object belongs, call the <code>getPackageName()</code> 505 * method on the object. 506 <p> 507 * @return the SBML type code for this object: 508 * {@link libsbmlConstants#SBML_LIST_OF SBML_LIST_OF} (default). 509 <p> 510 * @note The various {@link ListOf} classes mostly differ from each other in what they 511 * contain. Hence, one must call getItemTypeCode() to fully determine the 512 * class of this SBML object. 513 <p> 514 * <p> 515 * @warning <span class='warning'>The specific integer values of the possible 516 * type codes may be reused by different Level 3 package plug-ins. 517 * Thus, to identifiy the correct code, <strong>it is necessary to invoke 518 * both getTypeCode() and getPackageName()</strong>.</span> 519 <p> 520 * @see #getItemTypeCode() 521 * @see #getElementName() 522 * @see #getPackageName() 523 */ public 524 int getTypeCode() { 525 return libsbmlJNI.ListOf_getTypeCode(swigCPtr, this); 526 } 527 528 529/** 530 * Get the type code of the objects contained in this {@link ListOf}. 531 <p> 532 * <p> 533 * LibSBML attaches an identifying code to every kind of SBML object. These 534 * are integer constants known as <em>SBML type codes</em>. The names of all 535 * the codes begin with the characters “<code>SBML_</code>”. 536 * In the Java language interface for libSBML, the 537 * type codes are defined as static integer constants in the interface class 538 * {@link libsbmlConstants}. Note that different Level 3 539 * package plug-ins may use overlapping type codes; to identify the package 540 * to which a given object belongs, call the <code>getPackageName()</code> 541 * method on the object. 542 <p> 543 * Classes that inherit from the {@link ListOf} class should 544 * override this function to return the SBML type code for 545 * the objects contained in this {@link ListOf}. If they do not, 546 * {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} is returned. 547 <p> 548 * @return The {@link ListOf} class itself contains no SBML objects, and 549 * therefore returns {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN}. 550 <p> 551 * @see #getElementName() 552 * @see #getPackageName() 553 */ public 554 int getItemTypeCode() { 555 return libsbmlJNI.ListOf_getItemTypeCode(swigCPtr, this); 556 } 557 558 559/** 560 * Returns the XML element name of this object, which for {@link ListOf}, is 561 * always <code>'listOf'.</code> 562 <p> 563 * @return the XML name of this element. 564 */ public 565 String getElementName() { 566 return libsbmlJNI.ListOf_getElementName(swigCPtr, this); 567 } 568 569 570/** 571 * Enables/Disables the given package with this element and child 572 * elements (if any). 573 * (This is an internal implementation for enablePackage function) 574 <p> 575 * @note Subclasses of the SBML Core package in which one or more child 576 * elements are defined must override this function. 577 * @internal 578 */ public 579 void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) { 580 libsbmlJNI.ListOf_enablePackageInternal(swigCPtr, this, pkgURI, pkgPrefix, flag); 581 } 582 583}