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 * Log of diagnostics reported during XML processing. 013 <p> 014 * <p style='color: #777; font-style: italic'> 015This class of objects is defined by libSBML only and has no direct 016equivalent in terms of SBML components. This class is not prescribed by 017the SBML specifications, although it is used to implement features 018defined in SBML. 019</p> 020 021 <p> 022 * The error log is a list. The XML layer of libSBML maintains an error 023 * log associated with a given XML document or data stream. When an 024 * operation results in an error, or when there is something wrong with the 025 * XML content, the problem is reported as an {@link XMLError} object stored in the 026 * {@link XMLErrorLog} list. Potential problems range from low-level issues (such 027 * as the inability to open a file) to XML syntax errors (such as 028 * mismatched tags or other problems). 029 <p> 030 * A typical approach for using this error log is to first use 031 * {@link XMLErrorLog#getNumErrors()} 032 * to inquire how many {@link XMLError} object instances it contains, and then to 033 * iterate over the list of objects one at a time using 034 * getError(long n) . Indexing in the list begins at 0. 035 <p> 036 * In normal circumstances, programs using libSBML will actually obtain an 037 * {@link SBMLErrorLog} rather than an {@link XMLErrorLog}. The former is subclassed from 038 * {@link XMLErrorLog} and simply wraps commands for working with {@link SBMLError} objects 039 * rather than the low-level {@link XMLError} objects. Classes such as 040 * {@link SBMLDocument} use the higher-level {@link SBMLErrorLog}. 041 */ 042 043public class XMLErrorLog { 044 private long swigCPtr; 045 protected boolean swigCMemOwn; 046 047 protected XMLErrorLog(long cPtr, boolean cMemoryOwn) 048 { 049 swigCMemOwn = cMemoryOwn; 050 swigCPtr = cPtr; 051 } 052 053 protected static long getCPtr(XMLErrorLog obj) 054 { 055 return (obj == null) ? 0 : obj.swigCPtr; 056 } 057 058 protected static long getCPtrAndDisown (XMLErrorLog obj) 059 { 060 long ptr = 0; 061 062 if (obj != null) 063 { 064 ptr = obj.swigCPtr; 065 obj.swigCMemOwn = false; 066 } 067 068 return ptr; 069 } 070 071 protected void finalize() { 072 delete(); 073 } 074 075 public synchronized void delete() { 076 if (swigCPtr != 0) { 077 if (swigCMemOwn) { 078 swigCMemOwn = false; 079 libsbmlJNI.delete_XMLErrorLog(swigCPtr); 080 } 081 swigCPtr = 0; 082 } 083 } 084 085 /** 086 * Equality comparison method for XMLErrorLog. 087 * <p> 088 * Because the Java methods for libSBML are actually wrappers around code 089 * implemented in C++ and C, certain operations will not behave as 090 * expected. Equality comparison is one such case. An instance of a 091 * libSBML object class is actually a <em>proxy object</em> 092 * wrapping the real underlying C/C++ object. The normal <code>==</code> 093 * equality operator in Java will <em>only compare the Java proxy objects</em>, 094 * not the underlying native object. The result is almost never what you 095 * want in practical situations. Unfortunately, Java does not provide a 096 * way to override <code>==</code>. 097 * <p> 098 * The alternative that must be followed is to use the 099 * <code>equals()</code> method. The <code>equals</code> method on this 100 * class overrides the default java.lang.Object one, and performs an 101 * intelligent comparison of instances of objects of this class. The 102 * result is an assessment of whether two libSBML Java objects are truly 103 * the same underlying native-code objects. 104 * <p> 105 * The use of this method in practice is the same as the use of any other 106 * Java <code>equals</code> method. For example, 107 * <em>a</em><code>.equals(</code><em>b</em><code>)</code> returns 108 * <code>true</code> if <em>a</em> and <em>b</em> are references to the 109 * same underlying object. 110 * 111 * @param sb a reference to an object to which the current object 112 * instance will be compared 113 * 114 * @return <code>true</code> if <code>sb</code> refers to the same underlying 115 * native object as this one, <code>false</code> otherwise 116 */ 117 public boolean equals(Object sb) 118 { 119 if ( this == sb ) 120 { 121 return true; 122 } 123 return swigCPtr == getCPtr((XMLErrorLog)(sb)); 124 } 125 126 /** 127 * Returns a hashcode for this XMLErrorLog object. 128 * 129 * @return a hash code usable by Java methods that need them. 130 */ 131 public int hashCode() 132 { 133 return (int)(swigCPtr^(swigCPtr>>>32)); 134 } 135 136 137/** 138 * Returns the number of errors that have been logged. 139 <p> 140 * To retrieve individual errors from the log, callers may use 141 * {@link XMLErrorLog#getError(long n)} . 142 <p> 143 * @return the number of errors that have been logged. 144 */ public 145 long getNumErrors() { 146 return libsbmlJNI.XMLErrorLog_getNumErrors(swigCPtr, this); 147 } 148 149 150/** 151 * Returns the <i>n</i>th {@link XMLError} object in this log. 152 <p> 153 * Index <code>n</code> is counted from 0. Callers should first inquire about the 154 * number of items in the log by using the method 155 * {@link XMLErrorLog#getNumErrors()}. 156 * Attempts to use an error index number that exceeds the actual number 157 * of errors in the log will result in a <code>null</code> being returned. 158 <p> 159 * @param n the index number of the error to retrieve (with 0 being the 160 * first error). 161 <p> 162 * @return the <i>n</i>th {@link XMLError} in this log, or <code>null</code> if <code>n</code> is 163 * greater than or equal to 164 * {@link XMLErrorLog#getNumErrors()}. 165 <p> 166 * @see #getNumErrors() 167 */ public 168 XMLError getError(long n) { 169 long cPtr = libsbmlJNI.XMLErrorLog_getError(swigCPtr, this, n); 170 return (cPtr == 0) ? null : new XMLError(cPtr, false); 171 } 172 173 174/** 175 * Deletes all errors from this log. 176 */ public 177 void clearLog() { 178 libsbmlJNI.XMLErrorLog_clearLog(swigCPtr, this); 179 } 180 181 182/** * @internal */ public 183 XMLErrorLog() { 184 this(libsbmlJNI.new_XMLErrorLog__SWIG_0(), true); 185 } 186 187 188/** * @internal */ public 189 XMLErrorLog(XMLErrorLog other) { 190 this(libsbmlJNI.new_XMLErrorLog__SWIG_1(XMLErrorLog.getCPtr(other), other), true); 191 } 192 193 194/** * @internal */ public 195 void add(XMLError error) { 196 libsbmlJNI.XMLErrorLog_add__SWIG_0(swigCPtr, this, XMLError.getCPtr(error), error); 197 } 198 199 200/** * @internal */ public 201 void add(SWIGTYPE_p_std__vectorT_XMLError_p_t errors) { 202 libsbmlJNI.XMLErrorLog_add__SWIG_1(swigCPtr, this, SWIGTYPE_p_std__vectorT_XMLError_p_t.getCPtr(errors)); 203 } 204 205 206/** 207 * Writes all errors contained in this log to a string and returns it. 208 <p> 209 * This method uses printErrors() to format the diagnostic messages. 210 * Please consult that method for information about the organization 211 * of the messages in the string returned by this method. 212 <p> 213 * @return a string containing all logged errors and warnings. 214 <p> 215 * @see #printErrors() 216 */ public 217 String toString() { 218 return libsbmlJNI.XMLErrorLog_toString(swigCPtr, this); 219 } 220 221 222/** 223 * Prints all the errors or warnings stored in this error log. 224 <p> 225 * This method prints the text to the stream given by the optional 226 * parameter <code>stream</code>. If no stream is given, the method prints the 227 * output to the standard error stream. 228 <p> 229 * The format of the output is: 230 * <pre class='fragment'> 231 N error(s): 232 line NNN: (id) message 233 </pre> 234 * If no errors have occurred, i.e., 235 * <code>getNumErrors() == 0</code>, then no output will be produced. 236<p> 237 * @param stream the ostream or ostringstream object indicating where 238 * the output should be printed. 239 <p> 240 * 241</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 242The native C++ implementation of this method defines a default argument 243value. In the documentation generated for different libSBML language 244bindings, you may or may not see corresponding arguments in the method 245declarations. For example, in Java and C#, a default argument is handled by 246declaring two separate methods, with one of them having the argument and 247the other one lacking the argument. However, the libSBML documentation will 248be <em>identical</em> for both methods. Consequently, if you are reading 249this and do not see an argument even though one is described, please look 250for descriptions of other variants of this method near where this one 251appears in the documentation. 252</dd></dl> 253 254 */ public 255 void printErrors(OStream stream) { 256 libsbmlJNI.XMLErrorLog_printErrors__SWIG_0(swigCPtr, this, SWIGTYPE_p_std__ostream.getCPtr(stream.get_ostream()), stream); 257 } 258 259 260/** 261 * Prints all the errors or warnings stored in this error log. 262 <p> 263 * This method prints the text to the stream given by the optional 264 * parameter <code>stream</code>. If no stream is given, the method prints the 265 * output to the standard error stream. 266 <p> 267 * The format of the output is: 268 * <pre class='fragment'> 269 N error(s): 270 line NNN: (id) message 271 </pre> 272 * If no errors have occurred, i.e., 273 * <code>getNumErrors() == 0</code>, then no output will be produced. 274<p> 275 * @param stream the ostream or ostringstream object indicating where 276 * the output should be printed. 277 <p> 278 * 279</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 280The native C++ implementation of this method defines a default argument 281value. In the documentation generated for different libSBML language 282bindings, you may or may not see corresponding arguments in the method 283declarations. For example, in Java and C#, a default argument is handled by 284declaring two separate methods, with one of them having the argument and 285the other one lacking the argument. However, the libSBML documentation will 286be <em>identical</em> for both methods. Consequently, if you are reading 287this and do not see an argument even though one is described, please look 288for descriptions of other variants of this method near where this one 289appears in the documentation. 290</dd></dl> 291 292 */ public 293 void printErrors() { 294 libsbmlJNI.XMLErrorLog_printErrors__SWIG_1(swigCPtr, this); 295 } 296 297 298/** 299 * Prints the errors or warnings with given severity stored in this error log. 300 <p> 301 * This method prints the text to the stream given by the optional 302 * parameter <code>stream</code>. If no stream is given, the method prints the 303 * output to the standard error stream. 304 <p> 305 * The format of the output is: 306 * <pre class='fragment'> 307 N error(s): 308 line NNN: (id) message 309</pre> 310 * If no errors with that severity was found, then no output will be produced. 311 <p> 312 * @param stream the ostream or ostringstream object indicating where 313 * the output should be printed. 314 * @param severity the severity of the errors sought. 315 */ public 316 void printErrors(OStream stream, long severity) { 317 libsbmlJNI.XMLErrorLog_printErrors__SWIG_2(swigCPtr, this, SWIGTYPE_p_std__ostream.getCPtr(stream.get_ostream()), stream, severity); 318 } 319 320 321/** 322 * Returns a boolean indicating whether or not the severity has been 323 * overridden. 324 <p> 325 * <p> 326 * The <em>severity override</em> mechanism in {@link XMLErrorLog} is intended to help 327 * applications handle error conditions in ways that may be more convenient 328 * for those applications. It is possible to use the mechanism to override 329 * the severity code of errors logged by libSBML, and even to disable error 330 * logging completely. An override stays in effect until the override is 331 * changed again by the calling application. 332 <p> 333 * @return <code>true</code> if an error severity override has been set, <code>false</code> 334 * otherwise. 335 <p> 336 * @see #getSeverityOverride() 337 * @see #setSeverityOverride(int) 338 * @see #unsetSeverityOverride() 339 * @see #changeErrorSeverity(int, int, String) 340 */ public 341 boolean isSeverityOverridden() { 342 return libsbmlJNI.XMLErrorLog_isSeverityOverridden(swigCPtr, this); 343 } 344 345 346/** 347 * Usets an existing override. 348 <p> 349 * <p> 350 * The <em>severity override</em> mechanism in {@link XMLErrorLog} is intended to help 351 * applications handle error conditions in ways that may be more convenient 352 * for those applications. It is possible to use the mechanism to override 353 * the severity code of errors logged by libSBML, and even to disable error 354 * logging completely. An override stays in effect until the override is 355 * changed again by the calling application. 356 <p> 357 * @see #getSeverityOverride() 358 * @see #setSeverityOverride(int) 359 * @see #isSeverityOverridden() 360 * @see #changeErrorSeverity(int, int, String) 361 */ public 362 void unsetSeverityOverride() { 363 libsbmlJNI.XMLErrorLog_unsetSeverityOverride(swigCPtr, this); 364 } 365 366 367/** 368 * Returns the current override. 369 <p> 370 * <p> 371 * The <em>severity override</em> mechanism in {@link XMLErrorLog} is intended to help 372 * applications handle error conditions in ways that may be more convenient 373 * for those applications. It is possible to use the mechanism to override 374 * the severity code of errors logged by libSBML, and even to disable error 375 * logging completely. An override stays in effect until the override is 376 * changed again by the calling application. 377 <p> 378 * @return a severity override code. The possible values are drawn 379 * from the 380 * set of integer constants whose names begin with the prefix 381 * <code>LIBSBML_OVERRIDE_</code>: 382 * <ul> 383 * <li> {@link libsbmlConstants#LIBSBML_OVERRIDE_DISABLED LIBSBML_OVERRIDE_DISABLED} 384 * <li> {@link libsbmlConstants#LIBSBML_OVERRIDE_DONT_LOG LIBSBML_OVERRIDE_DONT_LOG} 385 * <li> {@link libsbmlConstants#LIBSBML_OVERRIDE_WARNING LIBSBML_OVERRIDE_WARNING} 386 * 387 * </ul> <p> 388 * @see #isSeverityOverridden() 389 * @see #setSeverityOverride(int) 390 * @see #unsetSeverityOverride() 391 * @see #changeErrorSeverity(int, int, String) 392 */ public 393 int getSeverityOverride() { 394 return libsbmlJNI.XMLErrorLog_getSeverityOverride(swigCPtr, this); 395 } 396 397 398/** 399 * Set the severity override. 400 <p> 401 * <p> 402 * The <em>severity override</em> mechanism in {@link XMLErrorLog} is intended to help 403 * applications handle error conditions in ways that may be more convenient 404 * for those applications. It is possible to use the mechanism to override 405 * the severity code of errors logged by libSBML, and even to disable error 406 * logging completely. An override stays in effect until the override is 407 * changed again by the calling application. 408 <p> 409 * @param severity an override code indicating what to do. If the value is 410 * {@link libsbmlConstants#LIBSBML_OVERRIDE_DISABLED LIBSBML_OVERRIDE_DISABLED} 411 * (the default setting) all errors logged will be given the severity 412 * specified in their usual definition. If the value is 413 * {@link libsbmlConstants#LIBSBML_OVERRIDE_WARNING LIBSBML_OVERRIDE_WARNING}, 414 * then all errors will be logged as warnings. If the value is 415 * {@link libsbmlConstants#LIBSBML_OVERRIDE_DONT_LOG LIBSBML_OVERRIDE_DONT_LOG}, 416 * no error will be logged, regardless of their severity. 417 <p> 418 * @see #isSeverityOverridden() 419 * @see #getSeverityOverride() 420 * @see #unsetSeverityOverride() 421 * @see #changeErrorSeverity(int, int, String) 422 */ public 423 void setSeverityOverride(int severity) { 424 libsbmlJNI.XMLErrorLog_setSeverityOverride(swigCPtr, this, severity); 425 } 426 427 428/** 429 * Changes the severity override for errors in the log that have a given 430 * severity. 431 <p> 432 * This method searches through the list of errors in the log, comparing 433 * each one's severity to the value of <code>originalSeverity</code>. For each error 434 * encountered with that severity logged by the named <code>package</code>, the 435 * severity of the error is reset to <code>targetSeverity</code>. 436 <p> 437 * <p> 438 * The <em>severity override</em> mechanism in {@link XMLErrorLog} is intended to help 439 * applications handle error conditions in ways that may be more convenient 440 * for those applications. It is possible to use the mechanism to override 441 * the severity code of errors logged by libSBML, and even to disable error 442 * logging completely. An override stays in effect until the override is 443 * changed again by the calling application. 444 <p> 445 * @param originalSeverity the severity code to match 446 <p> 447 * @param targetSeverity the severity code to use as the new severity 448 <p> 449 * @param package a string, the name of an SBML Level 3 package 450 * extension to use to narrow the search for errors. A value of <code>'all'</code> 451 * signifies to match against errors logged from any package; a value of a 452 * package nickname such as <code>'comp'</code> signifies to limit consideration to 453 * errors from just that package. If no value is provided, <code>'all'</code> is the 454 * default. 455 <p> 456 * 457</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 458The native C++ implementation of this method defines a default argument 459value. In the documentation generated for different libSBML language 460bindings, you may or may not see corresponding arguments in the method 461declarations. For example, in Java and C#, a default argument is handled by 462declaring two separate methods, with one of them having the argument and 463the other one lacking the argument. However, the libSBML documentation will 464be <em>identical</em> for both methods. Consequently, if you are reading 465this and do not see an argument even though one is described, please look 466for descriptions of other variants of this method near where this one 467appears in the documentation. 468</dd></dl> 469 470 <p> 471 * @see #isSeverityOverridden() 472 * @see #getSeverityOverride() 473 * @see #setSeverityOverride(int) 474 * @see #unsetSeverityOverride() 475 */ public 476 void changeErrorSeverity(int originalSeverity, int targetSeverity, String arg2) { 477 libsbmlJNI.XMLErrorLog_changeErrorSeverity__SWIG_0(swigCPtr, this, originalSeverity, targetSeverity, arg2); 478 } 479 480 481/** 482 * Changes the severity override for errors in the log that have a given 483 * severity. 484 <p> 485 * This method searches through the list of errors in the log, comparing 486 * each one's severity to the value of <code>originalSeverity</code>. For each error 487 * encountered with that severity logged by the named <code>package</code>, the 488 * severity of the error is reset to <code>targetSeverity</code>. 489 <p> 490 * <p> 491 * The <em>severity override</em> mechanism in {@link XMLErrorLog} is intended to help 492 * applications handle error conditions in ways that may be more convenient 493 * for those applications. It is possible to use the mechanism to override 494 * the severity code of errors logged by libSBML, and even to disable error 495 * logging completely. An override stays in effect until the override is 496 * changed again by the calling application. 497 <p> 498 * @param originalSeverity the severity code to match 499 <p> 500 * @param targetSeverity the severity code to use as the new severity 501 <p> 502 * @param package a string, the name of an SBML Level 3 package 503 * extension to use to narrow the search for errors. A value of <code>'all'</code> 504 * signifies to match against errors logged from any package; a value of a 505 * package nickname such as <code>'comp'</code> signifies to limit consideration to 506 * errors from just that package. If no value is provided, <code>'all'</code> is the 507 * default. 508 <p> 509 * 510</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd> 511The native C++ implementation of this method defines a default argument 512value. In the documentation generated for different libSBML language 513bindings, you may or may not see corresponding arguments in the method 514declarations. For example, in Java and C#, a default argument is handled by 515declaring two separate methods, with one of them having the argument and 516the other one lacking the argument. However, the libSBML documentation will 517be <em>identical</em> for both methods. Consequently, if you are reading 518this and do not see an argument even though one is described, please look 519for descriptions of other variants of this method near where this one 520appears in the documentation. 521</dd></dl> 522 523 <p> 524 * @see #isSeverityOverridden() 525 * @see #getSeverityOverride() 526 * @see #setSeverityOverride(int) 527 * @see #unsetSeverityOverride() 528 */ public 529 void changeErrorSeverity(int originalSeverity, int targetSeverity) { 530 libsbmlJNI.XMLErrorLog_changeErrorSeverity__SWIG_1(swigCPtr, this, originalSeverity, targetSeverity); 531 } 532 533}