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