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 * Abstract class for references to species in reactions. 013 <p> 014 * As mentioned in the description of {@link Reaction}, every species that enters 015 * into a given reaction must appear in that reaction's lists of reactants, 016 * products and/or modifiers. In an SBML model, all species that may 017 * participate in any reaction are listed in the 'listOfSpecies' element of 018 * the top-level {@link Model} object. Lists of products, reactants and modifiers 019 * in {@link Reaction} objects do not introduce new species, but rather, they refer 020 * back to those listed in the model's top-level 'listOfSpecies'. For 021 * reactants and products, the connection is made using {@link SpeciesReference} 022 * objects; for modifiers, it is made using {@link ModifierSpeciesReference} 023 * objects. {@link SimpleSpeciesReference} is an abstract type that serves as the 024 * parent class of both {@link SpeciesReference} and {@link ModifierSpeciesReference}. It 025 * is used simply to hold the attributes and elements that are common to 026 * the latter two structures. 027 <p> 028 * The {@link SimpleSpeciesReference} structure has a mandatory attribute, 029 * 'species', which must be a text string conforming to the identifer 030 * syntax permitted in SBML. This attribute is inherited by the 031 * {@link SpeciesReference} and {@link ModifierSpeciesReference} subclasses derived from 032 * {@link SimpleSpeciesReference}. The value of the 'species' attribute must be 033 * the identifier of a species defined in the enclosing {@link Model}. The species 034 * is thereby declared as participating in the reaction being defined. The 035 * precise role of that species as a reactant, product, or modifier in the 036 * reaction is determined by the subclass of {@link SimpleSpeciesReference} (i.e., 037 * either {@link SpeciesReference} or {@link ModifierSpeciesReference}) in which the 038 * identifier appears. 039 <p> 040 * {@link SimpleSpeciesReference} also contains an optional attribute, 'id', 041 * allowing instances to be referenced from other structures. No SBML 042 * structures currently do this; however, such structures are anticipated 043 * in future SBML Levels. 044 */ 045 046public class SimpleSpeciesReference extends SBase { 047 private long swigCPtr; 048 049 protected SimpleSpeciesReference(long cPtr, boolean cMemoryOwn) 050 { 051 super(libsbmlJNI.SimpleSpeciesReference_SWIGUpcast(cPtr), cMemoryOwn); 052 swigCPtr = cPtr; 053 } 054 055 protected static long getCPtr(SimpleSpeciesReference obj) 056 { 057 return (obj == null) ? 0 : obj.swigCPtr; 058 } 059 060 protected static long getCPtrAndDisown (SimpleSpeciesReference obj) 061 { 062 long ptr = 0; 063 064 if (obj != null) 065 { 066 ptr = obj.swigCPtr; 067 obj.swigCMemOwn = false; 068 } 069 070 return ptr; 071 } 072 073 protected void finalize() { 074 delete(); 075 } 076 077 public synchronized void delete() { 078 if (swigCPtr != 0) { 079 if (swigCMemOwn) { 080 swigCMemOwn = false; 081 libsbmlJNI.delete_SimpleSpeciesReference(swigCPtr); 082 } 083 swigCPtr = 0; 084 } 085 super.delete(); 086 } 087 088 089/** 090 * Returns the value of the 'id' attribute of this {@link SimpleSpeciesReference}. 091 <p> 092 * @note Because of the inconsistent behavior of this function with 093 * respect to assignments and rules, it is now recommended to 094 * use the getIdAttribute() function instead. 095 <p> 096 * <p> 097 * The identifier given by an object's 'id' attribute value 098 * is used to identify the object within the SBML model definition. 099 * Other objects can refer to the component using this identifier. The 100 * data type of 'id' is always <code>SId</code> or a type derived 101 * from that, such as <code>UnitSId</code>, depending on the object in 102 * question. All data types are defined as follows: 103 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 104 * letter .= 'a'..'z','A'..'Z' 105 * digit .= '0'..'9' 106 * idChar .= letter | digit | '_' 107 * SId .= ( letter | '_' ) idChar* 108 * </pre> 109 * The characters <code>(</code> and <code>)</code> are used for grouping, 110 * the character <code>*</code> 'zero or more times', and the character 111 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers 112 * is determined by an exact character sequence match; i.e., comparisons must 113 * be performed in a case-sensitive manner. This applies to all uses of 114 * <code>SId</code>, <code>SIdRef</code>, and derived types. 115 <p> 116 * Users need to be aware of some important API issues that are the result of 117 * the history of SBML and libSBML. Prior to SBML Level 3 118 * Version 2, SBML defined 'id' and 'name' attributes on only a subset 119 * of SBML objects. To simplify the work of programmers, libSBML's API 120 * provided get, set, check, and unset on the {@link SBase} object class itself 121 * instead of on individual subobject classes. This made the 122 * get/set/etc. methods uniformly available on all objects in the libSBML 123 * API. LibSBML simply returned empty strings or otherwise did not act when 124 * the methods were applied to SBML objects that were not defined by the SBML 125 * specification to have 'id' or 'name' attributes. Additional complications 126 * arose with the rule and assignment objects: {@link InitialAssignment}, 127 * {@link EventAssignment}, {@link AssignmentRule}, and {@link RateRule}. In early versions of SBML, 128 * the rule object hierarchy was different, and in addition, then as now, 129 * they possess different attributes: 'variable' (for the rules and event 130 * assignments), 'symbol' (for initial assignments), or neither (for 131 * algebraic rules). Prior to SBML Level 3 Version 2, getId() 132 * would always return an empty string, and isSetId() would always return 133 * <code>false</code> for objects of these classes. 134 <p> 135 * With the addition of 'id' and 'name' attributes on {@link SBase} in Level 3 136 * Version 2, it became necessary to introduce a new way to interact 137 * with the attributes more consistently in libSBML to avoid breaking 138 * backward compatibility in the behavior of the original 'id' methods. For 139 * this reason, libSBML provides four functions (getIdAttribute(), 140 * setIdAttribute(String), isSetIdAttribute(), and 141 * unsetIdAttribute()) that always act on the actual 'id' attribute inherited 142 * from {@link SBase}, regardless of the object's type. <strong>These new methods 143 * should be used instead of the older getId()/setId()/etc. methods</strong> 144 * unless the old behavior is somehow necessary. Regardless of the Level and 145 * Version of the SBML, these functions allow client applications to use more 146 * generalized code in some situations (for instance, when manipulating 147 * objects that are all known to have identifiers). If the object in 148 * question does not posess an 'id' attribute according to the SBML 149 * specification for the Level and Version in use, libSBML will not allow the 150 * identifier to be set, nor will it read or write 'id' attributes for those 151 * objects. 152 <p> 153 * @return the id of this {@link SimpleSpeciesReference}. 154 <p> 155 * @see #getIdAttribute() 156 * @see #setIdAttribute(String sid) 157 * @see #isSetIdAttribute() 158 * @see #unsetIdAttribute() 159 */ public 160 String getId() { 161 return libsbmlJNI.SimpleSpeciesReference_getId(swigCPtr, this); 162 } 163 164 165/** 166 * Returns the value of the 'name' attribute of this {@link SimpleSpeciesReference} object. 167 <p> 168 * <p> 169 * <p> 170 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 171 * moved to {@link SBase} directly, instead of being defined individually for many 172 * (but not all) objects. LibSBML has for a long time provided functions 173 * defined on {@link SBase} itself to get, set, and unset those attributes, which 174 * would fail or otherwise return empty strings if executed on any object 175 * for which those attributes were not defined. Now that all {@link SBase} objects 176 * define those attributes, those functions now succeed for any object with 177 * the appropriate level and version. 178 <p> 179 * The 'name' attribute is 180 * optional and is not intended to be used for cross-referencing purposes 181 * within a model. Its purpose instead is to provide a human-readable 182 * label for the component. The data type of 'name' is the type 183 * <code>string</code> defined in XML Schema. SBML imposes no 184 * restrictions as to the content of 'name' attributes beyond those 185 * restrictions defined by the <code>string</code> type in XML Schema. 186 <p> 187 * The recommended practice for handling 'name' is as follows. If a 188 * software tool has the capability for displaying the content of 'name' 189 * attributes, it should display this content to the user as a 190 * component's label instead of the component's 'id'. If the user 191 * interface does not have this capability (e.g., because it cannot 192 * display or use special characters in symbol names), or if the 'name' 193 * attribute is missing on a given component, then the user interface 194 * should display the value of the 'id' attribute instead. (Script 195 * language interpreters are especially likely to display 'id' instead of 196 * 'name'.) 197 <p> 198 * As a consequence of the above, authors of systems that automatically 199 * generate the values of 'id' attributes should be aware some systems 200 * may display the 'id''s to the user. Authors therefore may wish to 201 * take some care to have their software create 'id' values that are: (a) 202 * reasonably easy for humans to type and read; and (b) likely to be 203 * meaningful, for example by making the 'id' attribute be an abbreviated 204 * form of the name attribute value. 205 <p> 206 * An additional point worth mentioning is although there are 207 * restrictions on the uniqueness of 'id' values, there are no 208 * restrictions on the uniqueness of 'name' values in a model. This 209 * allows software applications leeway in assigning component identifiers. 210 <p> 211 * Regardless of the level and version of the SBML, these functions allow 212 * client applications to use more generalized code in some situations 213 * (for instance, when manipulating objects that are all known to have 214 * names). If the object in question does not posess a 'name' attribute 215 * according to the SBML specification for the Level and Version in use, 216 * libSBML will not allow the name to be set, nor will it read or 217 * write 'name' attributes for those objects. 218 <p> 219 * @return the name of this SBML object, or the empty string if not set or unsettable. 220 <p> 221 * @see #getIdAttribute() 222 * @see #isSetName() 223 * @see #setName(String sid) 224 * @see #unsetName() 225 */ public 226 String getName() { 227 return libsbmlJNI.SimpleSpeciesReference_getName(swigCPtr, this); 228 } 229 230 231/** 232 * Get the value of the 'species' attribute. 233 <p> 234 * @return the value of the attribute 'species' for this 235 * {@link SimpleSpeciesReference}. 236 */ public 237 String getSpecies() { 238 return libsbmlJNI.SimpleSpeciesReference_getSpecies(swigCPtr, this); 239 } 240 241 242/** 243 * Predicate returning <code>true</code> if this 244 * {@link SimpleSpeciesReference}'s 'id' attribute is set. 245 <p> 246 * <p> 247 * <p> 248 * The identifier given by an object's 'id' attribute value 249 * is used to identify the object within the SBML model definition. 250 * Other objects can refer to the component using this identifier. The 251 * data type of 'id' is always <code>SId</code> or a type derived 252 * from that, such as <code>UnitSId</code>, depending on the object in 253 * question. All data types are defined as follows: 254 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 255 * letter .= 'a'..'z','A'..'Z' 256 * digit .= '0'..'9' 257 * idChar .= letter | digit | '_' 258 * SId .= ( letter | '_' ) idChar* 259 * </pre> 260 * The characters <code>(</code> and <code>)</code> are used for grouping, 261 * the character <code>*</code> 'zero or more times', and the character 262 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers 263 * is determined by an exact character sequence match; i.e., comparisons must 264 * be performed in a case-sensitive manner. This applies to all uses of 265 * <code>SId</code>, <code>SIdRef</code>, and derived types. 266 <p> 267 * Users need to be aware of some important API issues that are the result of 268 * the history of SBML and libSBML. Prior to SBML Level 3 269 * Version 2, SBML defined 'id' and 'name' attributes on only a subset 270 * of SBML objects. To simplify the work of programmers, libSBML's API 271 * provided get, set, check, and unset on the {@link SBase} object class itself 272 * instead of on individual subobject classes. This made the 273 * get/set/etc. methods uniformly available on all objects in the libSBML 274 * API. LibSBML simply returned empty strings or otherwise did not act when 275 * the methods were applied to SBML objects that were not defined by the SBML 276 * specification to have 'id' or 'name' attributes. Additional complications 277 * arose with the rule and assignment objects: {@link InitialAssignment}, 278 * {@link EventAssignment}, {@link AssignmentRule}, and {@link RateRule}. In early versions of SBML, 279 * the rule object hierarchy was different, and in addition, then as now, 280 * they possess different attributes: 'variable' (for the rules and event 281 * assignments), 'symbol' (for initial assignments), or neither (for 282 * algebraic rules). Prior to SBML Level 3 Version 2, getId() 283 * would always return an empty string, and isSetId() would always return 284 * <code>false</code> for objects of these classes. 285 <p> 286 * With the addition of 'id' and 'name' attributes on {@link SBase} in Level 3 287 * Version 2, it became necessary to introduce a new way to interact 288 * with the attributes more consistently in libSBML to avoid breaking 289 * backward compatibility in the behavior of the original 'id' methods. For 290 * this reason, libSBML provides four functions (getIdAttribute(), 291 * setIdAttribute(String), isSetIdAttribute(), and 292 * unsetIdAttribute()) that always act on the actual 'id' attribute inherited 293 * from {@link SBase}, regardless of the object's type. <strong>These new methods 294 * should be used instead of the older getId()/setId()/etc. methods</strong> 295 * unless the old behavior is somehow necessary. Regardless of the Level and 296 * Version of the SBML, these functions allow client applications to use more 297 * generalized code in some situations (for instance, when manipulating 298 * objects that are all known to have identifiers). If the object in 299 * question does not posess an 'id' attribute according to the SBML 300 * specification for the Level and Version in use, libSBML will not allow the 301 * identifier to be set, nor will it read or write 'id' attributes for those 302 * objects. 303 <p> 304 * @return <code>true</code> if the 'id' attribute of this SBML object is 305 * set, <code>false</code> otherwise. 306 <p> 307 * @note Because of the inconsistent behavior of this function with 308 * respect to assignments and rules, it is recommended that callers 309 * use isSetIdAttribute() instead. 310 <p> 311 * @see #getIdAttribute() 312 * @see #setIdAttribute(String sid) 313 * @see #unsetIdAttribute() 314 * @see #isSetIdAttribute() 315 */ public 316 boolean isSetId() { 317 return libsbmlJNI.SimpleSpeciesReference_isSetId(swigCPtr, this); 318 } 319 320 321/** 322 * Predicate returning <code>true</code> if this 323 * {@link SimpleSpeciesReference}'s 'name' attribute is set. 324 <p> 325 * <p> 326 * <p> 327 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 328 * moved to {@link SBase} directly, instead of being defined individually for many 329 * (but not all) objects. LibSBML has for a long time provided functions 330 * defined on {@link SBase} itself to get, set, and unset those attributes, which 331 * would fail or otherwise return empty strings if executed on any object 332 * for which those attributes were not defined. Now that all {@link SBase} objects 333 * define those attributes, those functions now succeed for any object with 334 * the appropriate level and version. 335 <p> 336 * The 'name' attribute is 337 * optional and is not intended to be used for cross-referencing purposes 338 * within a model. Its purpose instead is to provide a human-readable 339 * label for the component. The data type of 'name' is the type 340 * <code>string</code> defined in XML Schema. SBML imposes no 341 * restrictions as to the content of 'name' attributes beyond those 342 * restrictions defined by the <code>string</code> type in XML Schema. 343 <p> 344 * The recommended practice for handling 'name' is as follows. If a 345 * software tool has the capability for displaying the content of 'name' 346 * attributes, it should display this content to the user as a 347 * component's label instead of the component's 'id'. If the user 348 * interface does not have this capability (e.g., because it cannot 349 * display or use special characters in symbol names), or if the 'name' 350 * attribute is missing on a given component, then the user interface 351 * should display the value of the 'id' attribute instead. (Script 352 * language interpreters are especially likely to display 'id' instead of 353 * 'name'.) 354 <p> 355 * As a consequence of the above, authors of systems that automatically 356 * generate the values of 'id' attributes should be aware some systems 357 * may display the 'id''s to the user. Authors therefore may wish to 358 * take some care to have their software create 'id' values that are: (a) 359 * reasonably easy for humans to type and read; and (b) likely to be 360 * meaningful, for example by making the 'id' attribute be an abbreviated 361 * form of the name attribute value. 362 <p> 363 * An additional point worth mentioning is although there are 364 * restrictions on the uniqueness of 'id' values, there are no 365 * restrictions on the uniqueness of 'name' values in a model. This 366 * allows software applications leeway in assigning component identifiers. 367 <p> 368 * Regardless of the level and version of the SBML, these functions allow 369 * client applications to use more generalized code in some situations 370 * (for instance, when manipulating objects that are all known to have 371 * names). If the object in question does not posess a 'name' attribute 372 * according to the SBML specification for the Level and Version in use, 373 * libSBML will not allow the name to be set, nor will it read or 374 * write 'name' attributes for those objects. 375 <p> 376 * @return <code>true</code> if the 'name' attribute of this SBML object is 377 * set, <code>false</code> otherwise. 378 <p> 379 * @see #getName() 380 * @see #setName(String sid) 381 * @see #unsetName() 382 */ public 383 boolean isSetName() { 384 return libsbmlJNI.SimpleSpeciesReference_isSetName(swigCPtr, this); 385 } 386 387 388/** 389 * Predicate returning <code>true</code> if this 390 * {@link SimpleSpeciesReference}'s 'species' attribute is set. 391 <p> 392 * @return <code>true</code> if the 'species' attribute of this 393 * {@link SimpleSpeciesReference} is set, <code>false</code> otherwise. 394 */ public 395 boolean isSetSpecies() { 396 return libsbmlJNI.SimpleSpeciesReference_isSetSpecies(swigCPtr, this); 397 } 398 399 400/** 401 * Sets the 'species' attribute of this {@link SimpleSpeciesReference}. 402 <p> 403 * The identifier string passed in <code>sid</code> is copied. 404 <p> 405 * @param sid the identifier of a species defined in the enclosing 406 * {@link Model}'s {@link ListOfSpecies}. 407 <p> 408 * <p> 409 * @return integer value indicating success/failure of the 410 * function. The possible values 411 * returned by this function are: 412 * <ul> 413 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 414 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 415 * </ul> 416 */ public 417 int setSpecies(String sid) { 418 return libsbmlJNI.SimpleSpeciesReference_setSpecies(swigCPtr, this, sid); 419 } 420 421 422/** 423 * Sets the value of the 'id' attribute of this {@link SimpleSpeciesReference}. 424 <p> 425 * <p> 426 * The string <code>sid</code> is copied. 427 <p> 428 * <p> 429 * The identifier given by an object's 'id' attribute value 430 * is used to identify the object within the SBML model definition. 431 * Other objects can refer to the component using this identifier. The 432 * data type of 'id' is always <code>SId</code> or a type derived 433 * from that, such as <code>UnitSId</code>, depending on the object in 434 * question. All data types are defined as follows: 435 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 436 * letter .= 'a'..'z','A'..'Z' 437 * digit .= '0'..'9' 438 * idChar .= letter | digit | '_' 439 * SId .= ( letter | '_' ) idChar* 440 * </pre> 441 * The characters <code>(</code> and <code>)</code> are used for grouping, 442 * the character <code>*</code> 'zero or more times', and the character 443 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers 444 * is determined by an exact character sequence match; i.e., comparisons must 445 * be performed in a case-sensitive manner. This applies to all uses of 446 * <code>SId</code>, <code>SIdRef</code>, and derived types. 447 <p> 448 * Users need to be aware of some important API issues that are the result of 449 * the history of SBML and libSBML. Prior to SBML Level 3 450 * Version 2, SBML defined 'id' and 'name' attributes on only a subset 451 * of SBML objects. To simplify the work of programmers, libSBML's API 452 * provided get, set, check, and unset on the {@link SBase} object class itself 453 * instead of on individual subobject classes. This made the 454 * get/set/etc. methods uniformly available on all objects in the libSBML 455 * API. LibSBML simply returned empty strings or otherwise did not act when 456 * the methods were applied to SBML objects that were not defined by the SBML 457 * specification to have 'id' or 'name' attributes. Additional complications 458 * arose with the rule and assignment objects: {@link InitialAssignment}, 459 * {@link EventAssignment}, {@link AssignmentRule}, and {@link RateRule}. In early versions of SBML, 460 * the rule object hierarchy was different, and in addition, then as now, 461 * they possess different attributes: 'variable' (for the rules and event 462 * assignments), 'symbol' (for initial assignments), or neither (for 463 * algebraic rules). Prior to SBML Level 3 Version 2, getId() 464 * would always return an empty string, and isSetId() would always return 465 * <code>false</code> for objects of these classes. 466 <p> 467 * With the addition of 'id' and 'name' attributes on {@link SBase} in Level 3 468 * Version 2, it became necessary to introduce a new way to interact 469 * with the attributes more consistently in libSBML to avoid breaking 470 * backward compatibility in the behavior of the original 'id' methods. For 471 * this reason, libSBML provides four functions (getIdAttribute(), 472 * setIdAttribute(String), isSetIdAttribute(), and 473 * unsetIdAttribute()) that always act on the actual 'id' attribute inherited 474 * from {@link SBase}, regardless of the object's type. <strong>These new methods 475 * should be used instead of the older getId()/setId()/etc. methods</strong> 476 * unless the old behavior is somehow necessary. Regardless of the Level and 477 * Version of the SBML, these functions allow client applications to use more 478 * generalized code in some situations (for instance, when manipulating 479 * objects that are all known to have identifiers). If the object in 480 * question does not posess an 'id' attribute according to the SBML 481 * specification for the Level and Version in use, libSBML will not allow the 482 * identifier to be set, nor will it read or write 'id' attributes for those 483 * objects. 484 <p> 485 * @param sid the string to use as the identifier of this object. 486 <p> 487 * <p> 488 * @return integer value indicating success/failure of the 489 * function. The possible values 490 * returned by this function are: 491 * <ul> 492 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 493 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 494 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 495 * 496 * </ul> <p> 497 * @see #getIdAttribute() 498 * @see #setIdAttribute(String sid) 499 * @see #isSetIdAttribute() 500 * @see #unsetIdAttribute() 501 */ public 502 int setId(String sid) { 503 return libsbmlJNI.SimpleSpeciesReference_setId(swigCPtr, this, sid); 504 } 505 506 507/** 508 * Sets the value of the 'name' attribute of this {@link SimpleSpeciesReference}. 509 <p> 510 * <p> 511 * The string in <code>name</code> is copied. 512 <p> 513 * @param name the new name for the SBML object. 514 <p> 515 * <p> 516 * @return integer value indicating success/failure of the 517 * function. The possible values 518 * returned by this function are: 519 * <ul> 520 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 521 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 522 * 523 * </ul> 524 */ public 525 int setName(String name) { 526 return libsbmlJNI.SimpleSpeciesReference_setName(swigCPtr, this, name); 527 } 528 529 530/** 531 * Unsets the value of the 'id' attribute of this {@link SimpleSpeciesReference}. 532 <p> 533 * <p> 534 * <p> 535 * The identifier given by an object's 'id' attribute value 536 * is used to identify the object within the SBML model definition. 537 * Other objects can refer to the component using this identifier. The 538 * data type of 'id' is always <code>SId</code> or a type derived 539 * from that, such as <code>UnitSId</code>, depending on the object in 540 * question. All data types are defined as follows: 541 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 542 * letter .= 'a'..'z','A'..'Z' 543 * digit .= '0'..'9' 544 * idChar .= letter | digit | '_' 545 * SId .= ( letter | '_' ) idChar* 546 * </pre> 547 * The characters <code>(</code> and <code>)</code> are used for grouping, 548 * the character <code>*</code> 'zero or more times', and the character 549 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers 550 * is determined by an exact character sequence match; i.e., comparisons must 551 * be performed in a case-sensitive manner. This applies to all uses of 552 * <code>SId</code>, <code>SIdRef</code>, and derived types. 553 <p> 554 * Users need to be aware of some important API issues that are the result of 555 * the history of SBML and libSBML. Prior to SBML Level 3 556 * Version 2, SBML defined 'id' and 'name' attributes on only a subset 557 * of SBML objects. To simplify the work of programmers, libSBML's API 558 * provided get, set, check, and unset on the {@link SBase} object class itself 559 * instead of on individual subobject classes. This made the 560 * get/set/etc. methods uniformly available on all objects in the libSBML 561 * API. LibSBML simply returned empty strings or otherwise did not act when 562 * the methods were applied to SBML objects that were not defined by the SBML 563 * specification to have 'id' or 'name' attributes. Additional complications 564 * arose with the rule and assignment objects: {@link InitialAssignment}, 565 * {@link EventAssignment}, {@link AssignmentRule}, and {@link RateRule}. In early versions of SBML, 566 * the rule object hierarchy was different, and in addition, then as now, 567 * they possess different attributes: 'variable' (for the rules and event 568 * assignments), 'symbol' (for initial assignments), or neither (for 569 * algebraic rules). Prior to SBML Level 3 Version 2, getId() 570 * would always return an empty string, and isSetId() would always return 571 * <code>false</code> for objects of these classes. 572 <p> 573 * With the addition of 'id' and 'name' attributes on {@link SBase} in Level 3 574 * Version 2, it became necessary to introduce a new way to interact 575 * with the attributes more consistently in libSBML to avoid breaking 576 * backward compatibility in the behavior of the original 'id' methods. For 577 * this reason, libSBML provides four functions (getIdAttribute(), 578 * setIdAttribute(String), isSetIdAttribute(), and 579 * unsetIdAttribute()) that always act on the actual 'id' attribute inherited 580 * from {@link SBase}, regardless of the object's type. <strong>These new methods 581 * should be used instead of the older getId()/setId()/etc. methods</strong> 582 * unless the old behavior is somehow necessary. Regardless of the Level and 583 * Version of the SBML, these functions allow client applications to use more 584 * generalized code in some situations (for instance, when manipulating 585 * objects that are all known to have identifiers). If the object in 586 * question does not posess an 'id' attribute according to the SBML 587 * specification for the Level and Version in use, libSBML will not allow the 588 * identifier to be set, nor will it read or write 'id' attributes for those 589 * objects. 590 <p> 591 * <p> 592 * @return integer value indicating success/failure of the 593 * function. The possible values 594 * returned by this function are: 595 * <ul> 596 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 597 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 598 * 599 * </ul> <p> 600 * @see #getIdAttribute() 601 * @see #setIdAttribute(String sid) 602 * @see #isSetIdAttribute() 603 * @see #unsetIdAttribute() 604 */ public 605 int unsetId() { 606 return libsbmlJNI.SimpleSpeciesReference_unsetId(swigCPtr, this); 607 } 608 609 610/** 611 * Unsets the value of the 'name' attribute of this {@link SimpleSpeciesReference}. 612 <p> 613 * <p> 614 * <p> 615 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 616 * moved to {@link SBase} directly, instead of being defined individually for many 617 * (but not all) objects. LibSBML has for a long time provided functions 618 * defined on {@link SBase} itself to get, set, and unset those attributes, which 619 * would fail or otherwise return empty strings if executed on any object 620 * for which those attributes were not defined. Now that all {@link SBase} objects 621 * define those attributes, those functions now succeed for any object with 622 * the appropriate level and version. 623 <p> 624 * The 'name' attribute is 625 * optional and is not intended to be used for cross-referencing purposes 626 * within a model. Its purpose instead is to provide a human-readable 627 * label for the component. The data type of 'name' is the type 628 * <code>string</code> defined in XML Schema. SBML imposes no 629 * restrictions as to the content of 'name' attributes beyond those 630 * restrictions defined by the <code>string</code> type in XML Schema. 631 <p> 632 * The recommended practice for handling 'name' is as follows. If a 633 * software tool has the capability for displaying the content of 'name' 634 * attributes, it should display this content to the user as a 635 * component's label instead of the component's 'id'. If the user 636 * interface does not have this capability (e.g., because it cannot 637 * display or use special characters in symbol names), or if the 'name' 638 * attribute is missing on a given component, then the user interface 639 * should display the value of the 'id' attribute instead. (Script 640 * language interpreters are especially likely to display 'id' instead of 641 * 'name'.) 642 <p> 643 * As a consequence of the above, authors of systems that automatically 644 * generate the values of 'id' attributes should be aware some systems 645 * may display the 'id''s to the user. Authors therefore may wish to 646 * take some care to have their software create 'id' values that are: (a) 647 * reasonably easy for humans to type and read; and (b) likely to be 648 * meaningful, for example by making the 'id' attribute be an abbreviated 649 * form of the name attribute value. 650 <p> 651 * An additional point worth mentioning is although there are 652 * restrictions on the uniqueness of 'id' values, there are no 653 * restrictions on the uniqueness of 'name' values in a model. This 654 * allows software applications leeway in assigning component identifiers. 655 <p> 656 * Regardless of the level and version of the SBML, these functions allow 657 * client applications to use more generalized code in some situations 658 * (for instance, when manipulating objects that are all known to have 659 * names). If the object in question does not posess a 'name' attribute 660 * according to the SBML specification for the Level and Version in use, 661 * libSBML will not allow the name to be set, nor will it read or 662 * write 'name' attributes for those objects. 663 <p> 664 * <p> 665 * @return integer value indicating success/failure of the 666 * function. The possible values 667 * returned by this function are: 668 * <ul> 669 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 670 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 671 * 672 * </ul> <p> 673 * @see #getName() 674 * @see #setName(String sid) 675 * @see #isSetName() 676 */ public 677 int unsetName() { 678 return libsbmlJNI.SimpleSpeciesReference_unsetName(swigCPtr, this); 679 } 680 681 682/** 683 * Unsets the value of the 'species' attribute of this {@link SimpleSpeciesReference}. 684 <p> 685 * <p> 686 * @return integer value indicating success/failure of the 687 * function. The possible values 688 * returned by this function are: 689 * <ul> 690 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 691 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 692 * </ul> 693 */ public 694 int unsetSpecies() { 695 return libsbmlJNI.SimpleSpeciesReference_unsetSpecies(swigCPtr, this); 696 } 697 698 699/** 700 * Predicate returning <code>true</code> if this 701 * is a {@link ModifierSpeciesReference}. 702 <p> 703 * @return <code>true</code> if this {@link SimpleSpeciesReference}'s subclass is 704 * ModiferSpeciesReference, <code>false</code> if it is a plain {@link SpeciesReference}. 705 */ public 706 boolean isModifier() { 707 return libsbmlJNI.SimpleSpeciesReference_isModifier(swigCPtr, this); 708 } 709 710 711/** 712 * <p> 713 * Replaces all uses of a given <code>SIdRef</code> type attribute value with another 714 * value. 715 <p> 716 * <p> 717 * In SBML, object identifiers are of a data type called <code>SId</code>. 718 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 719 * introduced for attribute values that refer to <code>SId</code> values; in 720 * previous Levels of SBML, this data type did not exist and attributes were 721 * simply described to as 'referring to an identifier', but the effective 722 * data type was the same as <code>SIdRef</code> in Level 3. These and 723 * other methods of libSBML refer to the type <code>SIdRef</code> for all 724 * Levels of SBML, even if the corresponding SBML specification did not 725 * explicitly name the data type. 726 <p> 727 * This method works by looking at all attributes and (if appropriate) 728 * mathematical formulas in MathML content, comparing the referenced 729 * identifiers to the value of <code>oldid</code>. If any matches are found, the 730 * matching values are replaced with <code>newid</code>. The method does <em>not</em> 731 * descend into child elements. 732 <p> 733 * @param oldid the old identifier. 734 * @param newid the new identifier. 735 */ public 736 void renameSIdRefs(String oldid, String newid) { 737 libsbmlJNI.SimpleSpeciesReference_renameSIdRefs(swigCPtr, this, oldid, newid); 738 } 739 740}