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