001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.0.10 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 * <span class="pkg-marker pkg-color-groups"><a href="group__groups.html">groups</a></span> 013 A list of {@link Group} objects. 014 <p> 015 * The SBML Level 3 Groups package provides a means of defining a 016 * <em>group of entities</em>: a simple mechanism for indicating that 017 * particular components of an SBML model are related in some way. A group 018 * is defined using a {@link Group} class object, and all the {@link Group} objects in a 019 * model are stored in the parent {@link Model} object within a {@link ListOfGroups} object. 020 <p> 021 * A {@link ListOfGroups} is optional, but, if present, must contain at least one 022 * {@link Group} object. In common with other ListOf___ classes in SBML, 023 * {@link ListOfGroups} is derived from {@link SBase}. It inherits {@link SBase}'s attributes 024 * 'metaid' and 'sboTerm', as well as the subcomponents for Annotation and 025 * Notes, but does not add any new attributes of its own. 026 <p> 027 * <p> 028 * The various ListOf___ classes in SBML 029 * are merely containers used for organizing the main components of an SBML 030 * model. In libSBML's implementation, ListOf___ 031 * classes are derived from the 032 * intermediate utility class {@link ListOf}, which 033 * is not defined by the SBML specifications but serves as a useful 034 * programmatic construct. {@link ListOf} is itself is in turn derived from {@link SBase}, 035 * which provides all of the various ListOf___ 036 * classes with common features 037 * defined by the SBML specification, such as 'metaid' attributes and 038 * annotations. 039 <p> 040 * The relationship between the lists and the rest of an SBML model is 041 * illustrated by the following (for SBML Level 2 Version 4): 042 <p> 043 * <figure> 044 <object type="image/svg+xml" data="listof-illustration.svg" class="centered"></object> 045</figure> 046 047 <p> 048 * SBML Level 3 Version 1 has essentially the same structure as 049 * Level 2 Version 4, depicted above, but SBML Level 3 050 * Version 2 allows 051 * containers to contain zero or more of the relevant object, instead of 052 * requiring at least one. As such, libsbml will write out an 053 * otherwise-empty ListOf___ element that has any optional attribute set 054 * (such as 'id' or 'metaid'), that has an optional child (such 055 * as a 'notes' or 'annotation'), or that has attributes or children set 056 * from any SBML Level 3 package, whether or not the ListOf___ has 057 * any other children. 058 <p> 059 * Readers may wonder about the motivations for using the ListOf___ 060 * containers in SBML. A simpler approach in XML might be to place the 061 * components all directly at the top level of the model definition. The 062 * choice made in SBML is to group them within XML elements named after 063 * ListOf<em>Classname</em>, in part because it helps organize the 064 * components. More importantly, the fact that the container classes are 065 * derived from {@link SBase} means that software tools can add information <em>about</em> 066 * the lists themselves into each list container's 'annotation'. 067 <p> 068 * @see ListOfFunctionDefinitions 069 * @see ListOfUnitDefinitions 070 * @see ListOfCompartmentTypes 071 * @see ListOfSpeciesTypes 072 * @see ListOfCompartments 073 * @see ListOfSpecies 074 * @see ListOfParameters 075 * @see ListOfInitialAssignments 076 * @see ListOfRules 077 * @see ListOfConstraints 078 * @see ListOfReactions 079 * @see ListOfEvents 080 */ 081 082public class ListOfGroups extends ListOf { 083 private long swigCPtr; 084 085 protected ListOfGroups(long cPtr, boolean cMemoryOwn) 086 { 087 super(libsbmlJNI.ListOfGroups_SWIGUpcast(cPtr), cMemoryOwn); 088 swigCPtr = cPtr; 089 } 090 091 protected static long getCPtr(ListOfGroups obj) 092 { 093 return (obj == null) ? 0 : obj.swigCPtr; 094 } 095 096 protected static long getCPtrAndDisown (ListOfGroups obj) 097 { 098 long ptr = 0; 099 100 if (obj != null) 101 { 102 ptr = obj.swigCPtr; 103 obj.swigCMemOwn = false; 104 } 105 106 return ptr; 107 } 108 109 protected void finalize() { 110 delete(); 111 } 112 113 public synchronized void delete() { 114 if (swigCPtr != 0) { 115 if (swigCMemOwn) { 116 swigCMemOwn = false; 117 libsbmlJNI.delete_ListOfGroups(swigCPtr); 118 } 119 swigCPtr = 0; 120 } 121 super.delete(); 122 } 123 124 125/** 126 * Creates a new {@link ListOfGroups} using the given SBML Level, Version and 127 * “groups” package version. 128 <p> 129 * @param level a long integer, the SBML Level to assign to this 130 * {@link ListOfGroups}. 131 <p> 132 * @param version a long integer, the SBML Version to assign to this 133 * {@link ListOfGroups}. 134 <p> 135 * @param pkgVersion a long integer, the SBML Groups Version to assign to 136 * this {@link ListOfGroups}. 137 <p> 138 * <p> 139 * @note Attempting to add an object to an {@link SBMLDocument} having a different 140 * combination of SBML Level, Version and XML namespaces than the object 141 * itself will result in an error at the time a caller attempts to make the 142 * addition. A parent object must have compatible Level, Version and XML 143 * namespaces. (Strictly speaking, a parent may also have more XML 144 * namespaces than a child, but the reverse is not permitted.) The 145 * restriction is necessary to ensure that an SBML model has a consistent 146 * overall structure. This requires callers to manage their objects 147 * carefully, but the benefit is increased flexibility in how models can be 148 * created by permitting callers to create objects bottom-up if desired. In 149 * situations where objects are not yet attached to parents (e.g., 150 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 151 * libSBML determine such things as whether it is valid to assign a 152 * particular value to an attribute. For packages, this means that the 153 * parent object to which this package element is being added must have 154 * been created with the package namespace, or that the package namespace 155 * was added to it, even if that parent is not a package object itself. 156 */ public 157 ListOfGroups(long level, long version, long pkgVersion) throws org.sbml.libsbml.SBMLConstructorException { 158 this(libsbmlJNI.new_ListOfGroups__SWIG_0(level, version, pkgVersion), true); 159 } 160 161 162/** 163 * Creates a new {@link ListOfGroups} using the given SBML Level, Version and 164 * “groups” package version. 165 <p> 166 * @param level a long integer, the SBML Level to assign to this 167 * {@link ListOfGroups}. 168 <p> 169 * @param version a long integer, the SBML Version to assign to this 170 * {@link ListOfGroups}. 171 <p> 172 * @param pkgVersion a long integer, the SBML Groups Version to assign to 173 * this {@link ListOfGroups}. 174 <p> 175 * <p> 176 * @note Attempting to add an object to an {@link SBMLDocument} having a different 177 * combination of SBML Level, Version and XML namespaces than the object 178 * itself will result in an error at the time a caller attempts to make the 179 * addition. A parent object must have compatible Level, Version and XML 180 * namespaces. (Strictly speaking, a parent may also have more XML 181 * namespaces than a child, but the reverse is not permitted.) The 182 * restriction is necessary to ensure that an SBML model has a consistent 183 * overall structure. This requires callers to manage their objects 184 * carefully, but the benefit is increased flexibility in how models can be 185 * created by permitting callers to create objects bottom-up if desired. In 186 * situations where objects are not yet attached to parents (e.g., 187 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 188 * libSBML determine such things as whether it is valid to assign a 189 * particular value to an attribute. For packages, this means that the 190 * parent object to which this package element is being added must have 191 * been created with the package namespace, or that the package namespace 192 * was added to it, even if that parent is not a package object itself. 193 */ public 194 ListOfGroups(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 195 this(libsbmlJNI.new_ListOfGroups__SWIG_1(level, version), true); 196 } 197 198 199/** 200 * Creates a new {@link ListOfGroups} using the given SBML Level, Version and 201 * “groups” package version. 202 <p> 203 * @param level a long integer, the SBML Level to assign to this 204 * {@link ListOfGroups}. 205 <p> 206 * @param version a long integer, the SBML Version to assign to this 207 * {@link ListOfGroups}. 208 <p> 209 * @param pkgVersion a long integer, the SBML Groups Version to assign to 210 * this {@link ListOfGroups}. 211 <p> 212 * <p> 213 * @note Attempting to add an object to an {@link SBMLDocument} having a different 214 * combination of SBML Level, Version and XML namespaces than the object 215 * itself will result in an error at the time a caller attempts to make the 216 * addition. A parent object must have compatible Level, Version and XML 217 * namespaces. (Strictly speaking, a parent may also have more XML 218 * namespaces than a child, but the reverse is not permitted.) The 219 * restriction is necessary to ensure that an SBML model has a consistent 220 * overall structure. This requires callers to manage their objects 221 * carefully, but the benefit is increased flexibility in how models can be 222 * created by permitting callers to create objects bottom-up if desired. In 223 * situations where objects are not yet attached to parents (e.g., 224 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 225 * libSBML determine such things as whether it is valid to assign a 226 * particular value to an attribute. For packages, this means that the 227 * parent object to which this package element is being added must have 228 * been created with the package namespace, or that the package namespace 229 * was added to it, even if that parent is not a package object itself. 230 */ public 231 ListOfGroups(long level) throws org.sbml.libsbml.SBMLConstructorException { 232 this(libsbmlJNI.new_ListOfGroups__SWIG_2(level), true); 233 } 234 235 236/** 237 * Creates a new {@link ListOfGroups} using the given SBML Level, Version and 238 * “groups” package version. 239 <p> 240 * @param level a long integer, the SBML Level to assign to this 241 * {@link ListOfGroups}. 242 <p> 243 * @param version a long integer, the SBML Version to assign to this 244 * {@link ListOfGroups}. 245 <p> 246 * @param pkgVersion a long integer, the SBML Groups Version to assign to 247 * this {@link ListOfGroups}. 248 <p> 249 * <p> 250 * @note Attempting to add an object to an {@link SBMLDocument} having a different 251 * combination of SBML Level, Version and XML namespaces than the object 252 * itself will result in an error at the time a caller attempts to make the 253 * addition. A parent object must have compatible Level, Version and XML 254 * namespaces. (Strictly speaking, a parent may also have more XML 255 * namespaces than a child, but the reverse is not permitted.) The 256 * restriction is necessary to ensure that an SBML model has a consistent 257 * overall structure. This requires callers to manage their objects 258 * carefully, but the benefit is increased flexibility in how models can be 259 * created by permitting callers to create objects bottom-up if desired. In 260 * situations where objects are not yet attached to parents (e.g., 261 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 262 * libSBML determine such things as whether it is valid to assign a 263 * particular value to an attribute. For packages, this means that the 264 * parent object to which this package element is being added must have 265 * been created with the package namespace, or that the package namespace 266 * was added to it, even if that parent is not a package object itself. 267 */ public 268 ListOfGroups() throws org.sbml.libsbml.SBMLConstructorException { 269 this(libsbmlJNI.new_ListOfGroups__SWIG_3(), true); 270 } 271 272 273/** 274 * Creates a new {@link ListOfGroups} using the given {@link GroupsPkgNamespaces} object. 275 <p> 276 * <p> 277 * The package namespaces object used in this constructor is derived from a 278 * {@link SBMLNamespaces} object, which encapsulates SBML Level/Version/namespaces 279 * information. It is used to communicate the SBML Level, Version, and 280 * package version and name information used in addition to SBML Level 3 Core. A 281 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 282 * package namespace object somewhere in a program once, then hand that object 283 * as needed to object constructors of that package that accept it as and 284 * argument, such as this one. 285 <p> 286 * @param groupsns the {@link GroupsPkgNamespaces} object. 287 <p> 288 * <p> 289 * @note Attempting to add an object to an {@link SBMLDocument} having a different 290 * combination of SBML Level, Version and XML namespaces than the object 291 * itself will result in an error at the time a caller attempts to make the 292 * addition. A parent object must have compatible Level, Version and XML 293 * namespaces. (Strictly speaking, a parent may also have more XML 294 * namespaces than a child, but the reverse is not permitted.) The 295 * restriction is necessary to ensure that an SBML model has a consistent 296 * overall structure. This requires callers to manage their objects 297 * carefully, but the benefit is increased flexibility in how models can be 298 * created by permitting callers to create objects bottom-up if desired. In 299 * situations where objects are not yet attached to parents (e.g., 300 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 301 * libSBML determine such things as whether it is valid to assign a 302 * particular value to an attribute. For packages, this means that the 303 * parent object to which this package element is being added must have 304 * been created with the package namespace, or that the package namespace 305 * was added to it, even if that parent is not a package object itself. 306 */ public 307 ListOfGroups(GroupsPkgNamespaces groupsns) throws org.sbml.libsbml.SBMLConstructorException { 308 this(libsbmlJNI.new_ListOfGroups__SWIG_4(GroupsPkgNamespaces.getCPtr(groupsns), groupsns), true); 309 } 310 311 312/** 313 * Copy constructor for {@link ListOfGroups}. 314 <p> 315 * @param orig the {@link ListOfGroups} instance to copy. 316 */ public 317 ListOfGroups(ListOfGroups orig) throws org.sbml.libsbml.SBMLConstructorException { 318 this(libsbmlJNI.new_ListOfGroups__SWIG_5(ListOfGroups.getCPtr(orig), orig), true); 319 } 320 321 322/** 323 * Creates and returns a deep copy of this {@link ListOfGroups} object. 324 <p> 325 * @return a (deep) copy of this {@link ListOfGroups} object. 326 */ public 327 ListOfGroups cloneObject() { 328 long cPtr = libsbmlJNI.ListOfGroups_cloneObject(swigCPtr, this); 329 return (cPtr == 0) ? null : new ListOfGroups(cPtr, true); 330 } 331 332 333/** 334 * Get a {@link Group} from the {@link ListOfGroups}. 335 <p> 336 * @param n a long integer representing the index of the {@link Group} to retrieve. 337 <p> 338 * @return the nth {@link Group} in this {@link ListOfGroups}. 339 <p> 340 * @see #addGroup(Group g) 341 * @see #createGroup() 342 * @see #get(String sid) 343 * @see #getNumGroups() 344 * @see #remove(String sid) 345 * @see #remove(long n) 346 */ public 347 Group get(long n) { 348 long cPtr = libsbmlJNI.ListOfGroups_get__SWIG_0(swigCPtr, this, n); 349 return (cPtr == 0) ? null : new Group(cPtr, false); 350 } 351 352 353/** 354 * Get a {@link Group} from the {@link ListOfGroups} based on its identifier. 355 <p> 356 * @param sid a string representing the identifier of the {@link Group} to retrieve. 357 <p> 358 * @return the {@link Group} in this {@link ListOfGroups} with the given id or null if no 359 * such {@link Group} exists. 360 <p> 361 * @see #addGroup(Group g) 362 * @see #createGroup() 363 * @see #get(long n) 364 * @see #getNumGroups() 365 * @see #remove(String sid) 366 * @see #remove(long n) 367 */ public 368 Group get(String sid) { 369 long cPtr = libsbmlJNI.ListOfGroups_get__SWIG_2(swigCPtr, this, sid); 370 return (cPtr == 0) ? null : new Group(cPtr, false); 371 } 372 373 374/** 375 * Removes the nth {@link Group} from this {@link ListOfGroups} and returns a pointer to it. 376 <p> 377 * @param n a long integer representing the index of the {@link Group} to remove. 378 <p> 379 * @return a pointer to the nth {@link Group} in this {@link ListOfGroups}. 380 <p> 381 * @note The caller owns the returned object and is responsible for deleting 382 * it. 383 <p> 384 * @see #addGroup(Group g) 385 * @see #createGroup() 386 * @see #get(String sid) 387 * @see #get(long n) 388 * @see #getNumGroups() 389 * @see #remove(String sid) 390 */ public 391 Group remove(long n) { 392 long cPtr = libsbmlJNI.ListOfGroups_remove__SWIG_0(swigCPtr, this, n); 393 return (cPtr == 0) ? null : new Group(cPtr, true); 394 } 395 396 397/** 398 * Removes the {@link Group} from this {@link ListOfGroups} based on its identifier and 399 * returns a pointer to it. 400 <p> 401 * @param sid a string representing the identifier of the {@link Group} to remove. 402 <p> 403 * @return the {@link Group} in this {@link ListOfGroups} based on the identifier or null if 404 * no such {@link Group} exists. 405 <p> 406 * @note The caller owns the returned object and is responsible for deleting 407 * it. 408 <p> 409 * @see #addGroup(Group g) 410 * @see #createGroup() 411 * @see #get(String sid) 412 * @see #get(long n) 413 * @see #getNumGroups() 414 * @see #remove(long n) 415 */ public 416 Group remove(String sid) { 417 long cPtr = libsbmlJNI.ListOfGroups_remove__SWIG_1(swigCPtr, this, sid); 418 return (cPtr == 0) ? null : new Group(cPtr, true); 419 } 420 421 422/** 423 * Adds a copy of the given {@link Group} to this {@link ListOfGroups}. 424 <p> 425 * @param g the {@link Group} object to add. 426 <p> 427 * <p> 428 * @return integer value indicating success/failure of the 429 * function. The possible values 430 * returned by this function are: 431 * <ul> 432 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 433 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 434 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 435 * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH} 436 * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH} 437 * <li> {@link libsbmlConstants#LIBSBML_NAMESPACES_MISMATCH LIBSBML_NAMESPACES_MISMATCH} 438 * 439 * </ul> <p> 440 * <p> 441 * @note This method should be used with some caution. The fact that this 442 * method <em>copies</em> the object passed to it means that the caller will be 443 * left holding a physically different object instance than the one contained 444 * inside this object. Changes made to the original object instance (such as 445 * resetting attribute values) will <em>not affect the instance in this 446 * object</em>. In addition, the caller should make sure to free the 447 * original object if it is no longer being used, or else a memory leak will 448 * result. Please see other methods on this class (particularly a 449 * corresponding method whose name begins with the word <code>create</code>) 450 * for alternatives that do not lead to these issues. 451 <p> 452 * @see #createGroup() 453 * @see #get(String sid) 454 * @see #get(long n) 455 * @see #getNumGroups() 456 * @see #remove(String sid) 457 * @see #remove(long n) 458 */ public 459 int addGroup(Group g) { 460 return libsbmlJNI.ListOfGroups_addGroup(swigCPtr, this, Group.getCPtr(g), g); 461 } 462 463 464/** 465 * Get the number of {@link Group} objects in this {@link ListOfGroups}. 466 <p> 467 * @return the number of {@link Group} objects in this {@link ListOfGroups}. 468 <p> 469 * @see #createGroup() 470 * @see #get(String sid) 471 * @see #get(long n) 472 * @see #remove(String sid) 473 * @see #remove(long n) 474 */ public 475 long getNumGroups() { 476 return libsbmlJNI.ListOfGroups_getNumGroups(swigCPtr, this); 477 } 478 479 480/** 481 * Creates a new {@link Group} object, adds it to this {@link ListOfGroups} object and 482 * returns the {@link Group} object created. 483 <p> 484 * @return a new {@link Group} object instance. 485 <p> 486 * @see #get(String sid) 487 * @see #get(long n) 488 * @see #getNumGroups() 489 * @see #remove(String sid) 490 * @see #remove(long n) 491 */ public 492 Group createGroup() { 493 long cPtr = libsbmlJNI.ListOfGroups_createGroup(swigCPtr, this); 494 return (cPtr == 0) ? null : new Group(cPtr, false); 495 } 496 497 498/** 499 * Returns the XML element name of this {@link ListOfGroups} object. 500 <p> 501 * For {@link ListOfGroups}, the XML element name is always <code>'listOfGroups'.</code> 502 <p> 503 * @return the name of this element, i.e. <code>'listOfGroups'.</code> 504 */ public 505 String getElementName() { 506 return libsbmlJNI.ListOfGroups_getElementName(swigCPtr, this); 507 } 508 509 510/** 511 * Returns the libSBML type code for this {@link ListOfGroups} object. 512 <p> 513 * <p> 514 * LibSBML attaches an identifying code to every kind of SBML object. These 515 * are integer constants known as <em>SBML type codes</em>. The names of all 516 * the codes begin with the characters <code>SBML_</code>. 517 * In the Java language interface for libSBML, the 518 * type codes are defined as static integer constants in the interface class 519 * {@link libsbmlConstants}. Note that different Level 3 520 * package plug-ins may use overlapping type codes; to identify the package 521 * to which a given object belongs, call the <code>getPackageName()</code> 522 * method on the object. 523 <p> 524 * @return the SBML type code for this object: 525 * {@link libsbmlConstants#SBML_LIST_OF SBML_LIST_OF}. 526 <p> 527 * <p> 528 * @warning <span class='warning'>The specific integer values of the possible 529 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 530 * packages, To fully identify the correct code, <strong>it is necessary to 531 * invoke both getTypeCode() and getPackageName()</strong>.</span> 532 */ public 533 int getTypeCode() { 534 return libsbmlJNI.ListOfGroups_getTypeCode(swigCPtr, this); 535 } 536 537 538/** 539 * Returns the libSBML type code for the SBML objects contained in this 540 * {@link ListOfGroups} object. 541 <p> 542 * <p> 543 * LibSBML attaches an identifying code to every kind of SBML object. These 544 * are integer constants known as <em>SBML type codes</em>. The names of all 545 * the codes begin with the characters <code>SBML_</code>. 546 * In the Java language interface for libSBML, the 547 * type codes are defined as static integer constants in the interface class 548 * {@link libsbmlConstants}. Note that different Level 3 549 * package plug-ins may use overlapping type codes; to identify the package 550 * to which a given object belongs, call the <code>getPackageName()</code> 551 * method on the object. 552 <p> 553 * @return the SBML typecode for the objects contained in this ListOfGroups: 554 * {@link libsbmlConstants#SBML_GROUPS_GROUP SBML_GROUPS_GROUP}. 555 <p> 556 * <p> 557 * @warning <span class='warning'>The specific integer values of the possible 558 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 559 * packages, To fully identify the correct code, <strong>it is necessary to 560 * invoke both getTypeCode() and getPackageName()</strong>.</span> 561 <p> 562 * @see #getElementName() 563 * @see #getPackageName() 564 */ public 565 int getItemTypeCode() { 566 return libsbmlJNI.ListOfGroups_getItemTypeCode(swigCPtr, this); 567 } 568 569}