001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.0.7 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 * An interface to an XML input stream. 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 * SBML content is serialized using XML; the resulting data can be stored and 023 * read to/from a file or data stream. Low-level XML parsers such as Xerces 024 * provide facilities to read XML data. To permit the use of different XML 025 * parsers (Xerces, Expat or libxml2), libSBML implements an abstraction 026 * layer. {@link XMLInputStream} and {@link XMLOutputStream} are two parts of that 027 * abstraction layer. 028 <p> 029 * {@link XMLInputStream} is an interface to a file or text string containing XML. 030 * It wraps the content to be read, as well as the low-level XML parser to be 031 * used and an {@link XMLErrorLog} to record errors and other issues (if any arise). 032 * Internally, the content will be in the form of either a pointer to a file 033 * name or a character string; {@link XMLInputStream} knows the form of the content 034 * and acts appropriately. Other libSBML object classes use {@link XMLInputStream} 035 * as their interface for all read operations on the XML data. 036 * {@link XMLInputStream} provides the functionality to extract data in the form of 037 * {@link XMLToken} objects. It logs any errors encountered while reading. It also 038 * keeps track of whether a read operation has failed irrecoverably or 039 * determines whether it is safe to continue reading. 040 <p> 041 * {@link SBMLNamespaces} objects can be associated with an {@link XMLInputStream}; this 042 * facilitates logging errors related to reading XML attributes and elements 043 * that may only be relevant to particular Level and Version combinations of 044 * SBML. 045 <p> 046 * @note The convenience of the {@link XMLInputStream} and {@link XMLOutputStream} 047 * abstraction may be useful for developers interested in creating parsers 048 * for other XML formats besides SBML. It can provide developers with a 049 * layer above more basic XML parsers, as well as some useful programmatic 050 * elements such as {@link XMLToken}, {@link XMLError}, etc. 051 <p> 052 * @see XMLOutputStream 053 */ 054 055public class XMLInputStream { 056 private long swigCPtr; 057 protected boolean swigCMemOwn; 058 059 protected XMLInputStream(long cPtr, boolean cMemoryOwn) 060 { 061 swigCMemOwn = cMemoryOwn; 062 swigCPtr = cPtr; 063 } 064 065 protected static long getCPtr(XMLInputStream obj) 066 { 067 return (obj == null) ? 0 : obj.swigCPtr; 068 } 069 070 protected static long getCPtrAndDisown (XMLInputStream obj) 071 { 072 long ptr = 0; 073 074 if (obj != null) 075 { 076 ptr = obj.swigCPtr; 077 obj.swigCMemOwn = false; 078 } 079 080 return ptr; 081 } 082 083 protected void finalize() { 084 delete(); 085 } 086 087 public synchronized void delete() { 088 if (swigCPtr != 0) { 089 if (swigCMemOwn) { 090 swigCMemOwn = false; 091 libsbmlJNI.delete_XMLInputStream(swigCPtr); 092 } 093 swigCPtr = 0; 094 } 095 } 096 097 098/** 099 * Creates a new {@link XMLInputStream}. 100 <p> 101 * @param content the source of the stream. 102 <p> 103 * @param isFile a boolean flag to indicate whether <code>content</code> is a file 104 * name. If <code>true</code>, <code>content</code> is assumed to be the file from which the 105 * XML content is to be read. If <code>false</code>, <code>content</code> is taken to be a 106 * string that <em>is</em> the content to be read. 107 <p> 108 * @param library the name of the parser library to use. 109 <p> 110 * @param errorLog the {@link XMLErrorLog} object to use. 111 <p> 112 * 113</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 114The native C++ implementation of this method defines a default argument 115value. In the documentation generated for different libSBML language 116bindings, you may or may not see corresponding arguments in the method 117declarations. For example, in Java and C#, a default argument is handled by 118declaring two separate methods, with one of them having the argument and 119the other one lacking the argument. However, the libSBML documentation will 120be <em>identical</em> for both methods. Consequently, if you are reading 121this and do not see an argument even though one is described, please look 122for descriptions of other variants of this method near where this one 123appears in the documentation. 124</dd></dl> 125 126 */ public 127 XMLInputStream(String content, boolean isFile, String library, XMLErrorLog errorLog) { 128 this(libsbmlJNI.new_XMLInputStream__SWIG_0(content, isFile, library, XMLErrorLog.getCPtr(errorLog), errorLog), true); 129 } 130 131 132/** 133 * Creates a new {@link XMLInputStream}. 134 <p> 135 * @param content the source of the stream. 136 <p> 137 * @param isFile a boolean flag to indicate whether <code>content</code> is a file 138 * name. If <code>true</code>, <code>content</code> is assumed to be the file from which the 139 * XML content is to be read. If <code>false</code>, <code>content</code> is taken to be a 140 * string that <em>is</em> the content to be read. 141 <p> 142 * @param library the name of the parser library to use. 143 <p> 144 * @param errorLog the {@link XMLErrorLog} object to use. 145 <p> 146 * 147</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 148The native C++ implementation of this method defines a default argument 149value. In the documentation generated for different libSBML language 150bindings, you may or may not see corresponding arguments in the method 151declarations. For example, in Java and C#, a default argument is handled by 152declaring two separate methods, with one of them having the argument and 153the other one lacking the argument. However, the libSBML documentation will 154be <em>identical</em> for both methods. Consequently, if you are reading 155this and do not see an argument even though one is described, please look 156for descriptions of other variants of this method near where this one 157appears in the documentation. 158</dd></dl> 159 160 */ public 161 XMLInputStream(String content, boolean isFile, String library) { 162 this(libsbmlJNI.new_XMLInputStream__SWIG_1(content, isFile, library), true); 163 } 164 165 166/** 167 * Creates a new {@link XMLInputStream}. 168 <p> 169 * @param content the source of the stream. 170 <p> 171 * @param isFile a boolean flag to indicate whether <code>content</code> is a file 172 * name. If <code>true</code>, <code>content</code> is assumed to be the file from which the 173 * XML content is to be read. If <code>false</code>, <code>content</code> is taken to be a 174 * string that <em>is</em> the content to be read. 175 <p> 176 * @param library the name of the parser library to use. 177 <p> 178 * @param errorLog the {@link XMLErrorLog} object to use. 179 <p> 180 * 181</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 182The native C++ implementation of this method defines a default argument 183value. In the documentation generated for different libSBML language 184bindings, you may or may not see corresponding arguments in the method 185declarations. For example, in Java and C#, a default argument is handled by 186declaring two separate methods, with one of them having the argument and 187the other one lacking the argument. However, the libSBML documentation will 188be <em>identical</em> for both methods. Consequently, if you are reading 189this and do not see an argument even though one is described, please look 190for descriptions of other variants of this method near where this one 191appears in the documentation. 192</dd></dl> 193 194 */ public 195 XMLInputStream(String content, boolean isFile) { 196 this(libsbmlJNI.new_XMLInputStream__SWIG_2(content, isFile), true); 197 } 198 199 200/** 201 * Creates a new {@link XMLInputStream}. 202 <p> 203 * @param content the source of the stream. 204 <p> 205 * @param isFile a boolean flag to indicate whether <code>content</code> is a file 206 * name. If <code>true</code>, <code>content</code> is assumed to be the file from which the 207 * XML content is to be read. If <code>false</code>, <code>content</code> is taken to be a 208 * string that <em>is</em> the content to be read. 209 <p> 210 * @param library the name of the parser library to use. 211 <p> 212 * @param errorLog the {@link XMLErrorLog} object to use. 213 <p> 214 * 215</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 216The native C++ implementation of this method defines a default argument 217value. In the documentation generated for different libSBML language 218bindings, you may or may not see corresponding arguments in the method 219declarations. For example, in Java and C#, a default argument is handled by 220declaring two separate methods, with one of them having the argument and 221the other one lacking the argument. However, the libSBML documentation will 222be <em>identical</em> for both methods. Consequently, if you are reading 223this and do not see an argument even though one is described, please look 224for descriptions of other variants of this method near where this one 225appears in the documentation. 226</dd></dl> 227 228 */ public 229 XMLInputStream(String content) { 230 this(libsbmlJNI.new_XMLInputStream__SWIG_3(content), true); 231 } 232 233 234/** 235 * Returns the encoding of the XML stream. 236 <p> 237 * <p> 238 The <em>encoding</em> is indicated by the <code>xml</code> declaration at the 239 * beginning of an XML document or data stream. The form of this declaration 240 * is 241 * <pre class='fragment'> 242<?xml version='1.0' encoding='UTF-8'?> 243</pre> 244 * Note that the SBML specifications require the use of UTF-8 encoding, so 245 * for SBML documents, the value returned by this method will always be 246 * the string <code>'UTF-8'</code>. 247 <p> 248 * @return the encoding of the XML stream. 249 <p> 250 * @see #getVersion() 251 */ public 252 String getEncoding() { 253 return libsbmlJNI.XMLInputStream_getEncoding(swigCPtr, this); 254 } 255 256 257/** 258 * Returns the version of the XML stream. 259 <p> 260 * <p> 261 The <em>version</em> is indicated by the <code>xml</code> declaration at the 262 * beginning of an XML document or data stream. The form of this declaration 263 * is 264 * <pre class='fragment'> 265 <?xml version='1.0' encoding='UTF-8'?> 266</pre> 267 * Note that the SBML specifications require the use of version 1.0, so 268 * for SBML documents, the value returned by this method will always be 269 * the string <code>'1.0'</code>. 270 <p> 271 * @return the version of the XML stream. 272 <p> 273 * @see #getEncoding() 274 */ public 275 String getVersion() { 276 return libsbmlJNI.XMLInputStream_getVersion(swigCPtr, this); 277 } 278 279 280/** 281 * Returns the {@link XMLErrorLog} used to log parsing problems. 282 <p> 283 * @return the {@link XMLErrorLog} used to log XML parse errors and other 284 * validation errors (and messages). 285 */ public 286 XMLErrorLog getErrorLog() { 287 long cPtr = libsbmlJNI.XMLInputStream_getErrorLog(swigCPtr, this); 288 return (cPtr == 0) ? null : new XMLErrorLog(cPtr, false); 289 } 290 291 292/** 293 * Returns <code>true</code> if end of file (stream) has been reached. 294 <p> 295 * @return <code>true</code> if end of file (stream) has been reached, <code>false</code> 296 * otherwise. 297 */ public 298 boolean isEOF() { 299 return libsbmlJNI.XMLInputStream_isEOF(swigCPtr, this); 300 } 301 302 303/** 304 * Returns <code>true</code> if a fatal error occurred while reading from this 305 * stream. 306 <p> 307 * @return <code>true</code> if a fatal error occurred while reading from this 308 * stream. 309 */ public 310 boolean isError() { 311 return libsbmlJNI.XMLInputStream_isError(swigCPtr, this); 312 } 313 314 315/** 316 * Returns <code>true</code> if the stream is in a good state. 317 <p> 318 * The definition of 'good state' is that isEOF() and isError() both return 319 * <code>false.</code> 320 <p> 321 * @return <code>true</code> if the stream is in a good state, <code>false</code> otherwise. 322 */ public 323 boolean isGood() { 324 return libsbmlJNI.XMLInputStream_isGood(swigCPtr, this); 325 } 326 327 328/** 329 * Returns the next token on this XML input stream. 330 <p> 331 * The token is consumed in the process. 332 <p> 333 * @return the next {@link XMLToken}, or an EOF token (i.e., 334 * <code>XMLToken.isEOF() == true</code>). 335 <p> 336 * @see #peek() 337 */ public 338 XMLToken next() { 339 return new XMLToken(libsbmlJNI.XMLInputStream_next(swigCPtr, this), true); 340 } 341 342 343/** 344 * Returns the next token <em>without</em> consuming it. 345 <p> 346 * A subsequent call to either peek() or next() will return the same token. 347 <p> 348 * @return the next {@link XMLToken} or EOF (XMLToken.isEOF() == true). 349 <p> 350 * @see #next() 351 */ public 352 XMLToken peek() { 353 return new XMLToken(libsbmlJNI.XMLInputStream_peek(swigCPtr, this), false); 354 } 355 356 357/** 358 * Consume zero or more tokens up to and including the corresponding end 359 * element or EOF. 360 <p> 361 * @param element the element whose end will be sought in the input stream. 362 */ public 363 void skipPastEnd(XMLToken element) { 364 libsbmlJNI.XMLInputStream_skipPastEnd(swigCPtr, this, XMLToken.getCPtr(element), element); 365 } 366 367 368/** 369 * Consume zero or more tokens up to but not including the next XML element 370 * or EOF. 371 */ public 372 void skipText() { 373 libsbmlJNI.XMLInputStream_skipText(swigCPtr, this); 374 } 375 376 377/** 378 * Sets the {@link XMLErrorLog} this stream will use to log errors. 379 <p> 380 * <p> 381 * @return integer value indicating success/failure of the 382 * function. The possible values 383 * returned by this function are: 384 * <ul> 385 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 386 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 387 * </ul> 388 */ public 389 int setErrorLog(XMLErrorLog log) { 390 return libsbmlJNI.XMLInputStream_setErrorLog(swigCPtr, this, XMLErrorLog.getCPtr(log), log); 391 } 392 393 394/** 395 * Prints a string representation of the underlying token stream. 396 <p> 397 * @return a string representing the underlying XML token stream. 398 <p> 399 * @note This method is intended for debugging purposes. 400 */ public 401 String toString() { 402 return libsbmlJNI.XMLInputStream_toString(swigCPtr, this); 403 } 404 405 406/** 407 * Returns the {@link SBMLNamespaces} object attached to this {@link XMLInputStream}. 408 <p> 409 * @return the {@link SBMLNamespaces} object or <code>null</code> if none has been set. 410 */ public 411 SBMLNamespaces getSBMLNamespaces() { 412 return libsbml.DowncastSBMLNamespaces(libsbmlJNI.XMLInputStream_getSBMLNamespaces(swigCPtr, this), false); 413} 414 415 416/** 417 * Sets the SBML namespaces associated with this XML input stream. 418 <p> 419 * This allows this stream to reference the available SBML namespaces being 420 * read. 421 <p> 422 * @param sbmlns the list of namespaces to use. 423 */ public 424 void setSBMLNamespaces(SBMLNamespaces sbmlns) { 425 libsbmlJNI.XMLInputStream_setSBMLNamespaces(swigCPtr, this, SBMLNamespaces.getCPtr(sbmlns), sbmlns); 426 } 427 428 429/** 430 * Returns the number of child tokens of the given element in this stream. 431 <p> 432 * This method allows information from the input stream to be determined 433 * without the need to actually read and consume the tokens in the stream. 434 * It returns the number of child elements of the element represented by 435 * the <code>elementName</code>, i.e., the number of child elements encountered 436 * before the closing tag for the <code>elementName</code> supplied. 437 <p> 438 * If no <code>elementName</code> is supplied or it is an empty string, then as a 439 * special case, this method assumes the element is a MathML 440 * <code>apply</code> element followed by a function name. 441 <p> 442 * @param elementName a string representing the name of the element for 443 * which the number of children are to be determined. 444 <p> 445 * @return a long integer giving the number of children of the 446 * <code>elementName</code> specified. 447 <p> 448 * @note This method assumes the stream has been read up to and including 449 * the element <code>elementName</code>. 450 <p> 451 * 452</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 453The native C++ implementation of this method defines a default argument 454value. In the documentation generated for different libSBML language 455bindings, you may or may not see corresponding arguments in the method 456declarations. For example, in Java and C#, a default argument is handled by 457declaring two separate methods, with one of them having the argument and 458the other one lacking the argument. However, the libSBML documentation will 459be <em>identical</em> for both methods. Consequently, if you are reading 460this and do not see an argument even though one is described, please look 461for descriptions of other variants of this method near where this one 462appears in the documentation. 463</dd></dl> 464 465 */ public 466 long determineNumberChildren(String elementName) { 467 return libsbmlJNI.XMLInputStream_determineNumberChildren__SWIG_0(swigCPtr, this, elementName); 468 } 469 470 471/** 472 * Returns the number of child tokens of the given element in this stream. 473 <p> 474 * This method allows information from the input stream to be determined 475 * without the need to actually read and consume the tokens in the stream. 476 * It returns the number of child elements of the element represented by 477 * the <code>elementName</code>, i.e., the number of child elements encountered 478 * before the closing tag for the <code>elementName</code> supplied. 479 <p> 480 * If no <code>elementName</code> is supplied or it is an empty string, then as a 481 * special case, this method assumes the element is a MathML 482 * <code>apply</code> element followed by a function name. 483 <p> 484 * @param elementName a string representing the name of the element for 485 * which the number of children are to be determined. 486 <p> 487 * @return a long integer giving the number of children of the 488 * <code>elementName</code> specified. 489 <p> 490 * @note This method assumes the stream has been read up to and including 491 * the element <code>elementName</code>. 492 <p> 493 * 494</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 495The native C++ implementation of this method defines a default argument 496value. In the documentation generated for different libSBML language 497bindings, you may or may not see corresponding arguments in the method 498declarations. For example, in Java and C#, a default argument is handled by 499declaring two separate methods, with one of them having the argument and 500the other one lacking the argument. However, the libSBML documentation will 501be <em>identical</em> for both methods. Consequently, if you are reading 502this and do not see an argument even though one is described, please look 503for descriptions of other variants of this method near where this one 504appears in the documentation. 505</dd></dl> 506 507 */ public 508 long determineNumberChildren() { 509 return libsbmlJNI.XMLInputStream_determineNumberChildren__SWIG_1(swigCPtr, this); 510 } 511 512 513/** 514 * Returns the number of child tokens of the specified type within a 515 * given container element. 516 <p> 517 * This method allows information from the input stream to be determined 518 * without the need to actually read and consume the tokens in the stream. 519 * It returns the number of child elements of the <code>childName</code> element 520 * within the element specified by <code>container</code>. In other words, it counts 521 * the number of <code>childName</code> elements encountered before the closing tag 522 * for the <code>container</code> supplied. 523 <p> 524 * @param childName a string representing the name of the child 525 * element whose number is to be determined. 526 <p> 527 * @param container a string representing the name of the element 528 * for which the number of children are to be determined. 529 <p> 530 * @return a long integer giving the number of children of type 531 * <code>childName</code> within the <code>container</code> element. 532 <p> 533 * @note This method assumes the stream has been read up to and including 534 * the element <code>container</code>. 535 */ public 536 long determineNumSpecificChildren(String childName, String container) { 537 return libsbmlJNI.XMLInputStream_determineNumSpecificChildren(swigCPtr, this, childName, container); 538 } 539 540 541/** 542 * Predicate returning <code>true</code> if a child token of the specified type occurs 543 * within a given container element. 544 <p> 545 * This method allows information from the input stream to be determined 546 * without the need to actually read and consume the tokens in the stream. 547 * It returns <code>true</code> if the <code>childName</code> element occurs at any point 548 * within the element specified by <code>container</code>. 549 <p> 550 * @param childName a string representing the name of the child 551 * element whose presence is to be determined. 552 <p> 553 * @param container a string representing the name of the element 554 * for which the presence of the child element is to be determined. 555 <p> 556 * @return boolean <code>true</code> if a child of type <code>childName</code> occurs within 557 * the <code>container</code> element, <code>false</code> otherwise. 558 <p> 559 * @note This method assumes the stream has been read up to and including 560 * the element <code>container</code>. 561 */ public 562 boolean containsChild(String childName, String container) { 563 return libsbmlJNI.XMLInputStream_containsChild(swigCPtr, this, childName, container); 564 } 565 566}