001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.11 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 * 013 * Log of errors and other events encountered while processing an XML 014 * file or data stream. 015 * <p> 016 * <p style='color: #777; font-style: italic'> 017This class of objects is defined by libSBML only and has no direct 018equivalent in terms of SBML components. This class is not prescribed by 019the SBML specifications, although it is used to implement features 020defined in SBML. 021</p> 022 023 * <p> 024 * The error log is a list. The XML layer of libSBML maintains an error 025 * log associated with a given XML document or data stream. When an 026 * operation results in an error, or when there is something wrong with the 027 * XML content, the problem is reported as an {@link XMLError} object stored in the 028 * {@link XMLErrorLog} list. Potential problems range from low-level issues (such 029 * as the inability to open a file) to XML syntax errors (such as 030 * mismatched tags or other problems). 031 * <p> 032 * A typical approach for using this error log is to first use 033 * {@link XMLErrorLog#getNumErrors()} 034 * to inquire how many {@link XMLError} object instances it contains, and then to 035 * iterate over the list of objects one at a time using 036 * getError(long n) const. Indexing in the list begins at 0. 037 * <p> 038 * In normal circumstances, programs using libSBML will actually obtain an 039 * {@link SBMLErrorLog} rather than an {@link XMLErrorLog}. The former is subclassed from 040 * {@link XMLErrorLog} and simply wraps commands for working with {@link SBMLError} objects 041 * rather than the low-level {@link XMLError} objects. Classes such as 042 * {@link SBMLDocument} use the higher-level {@link SBMLErrorLog}. 043 */ 044 045public class XMLErrorLog { 046 private long swigCPtr; 047 protected boolean swigCMemOwn; 048 049 protected XMLErrorLog(long cPtr, boolean cMemoryOwn) 050 { 051 swigCMemOwn = cMemoryOwn; 052 swigCPtr = cPtr; 053 } 054 055 protected static long getCPtr(XMLErrorLog obj) 056 { 057 return (obj == null) ? 0 : obj.swigCPtr; 058 } 059 060 protected static long getCPtrAndDisown (XMLErrorLog 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_XMLErrorLog(swigCPtr); 082 } 083 swigCPtr = 0; 084 } 085 } 086 087 /** 088 * Equality comparison method for XMLErrorLog. 089 * <p> 090 * Because the Java methods for libSBML are actually wrappers around code 091 * implemented in C++ and C, certain operations will not behave as 092 * expected. Equality comparison is one such case. An instance of a 093 * libSBML object class is actually a <em>proxy object</em> 094 * wrapping the real underlying C/C++ object. The normal <code>==</code> 095 * equality operator in Java will <em>only compare the Java proxy objects</em>, 096 * not the underlying native object. The result is almost never what you 097 * want in practical situations. Unfortunately, Java does not provide a 098 * way to override <code>==</code>. 099 * <p> 100 * The alternative that must be followed is to use the 101 * <code>equals()</code> method. The <code>equals</code> method on this 102 * class overrides the default java.lang.Object one, and performs an 103 * intelligent comparison of instances of objects of this class. The 104 * result is an assessment of whether two libSBML Java objects are truly 105 * the same underlying native-code objects. 106 * <p> 107 * The use of this method in practice is the same as the use of any other 108 * Java <code>equals</code> method. For example, 109 * <em>a</em><code>.equals(</code><em>b</em><code>)</code> returns 110 * <code>true</code> if <em>a</em> and <em>b</em> are references to the 111 * same underlying object. 112 * 113 * @param sb a reference to an object to which the current object 114 * instance will be compared 115 * 116 * @return <code>true</code> if <code>sb</code> refers to the same underlying 117 * native object as this one, <code>false</code> otherwise 118 */ 119 public boolean equals(Object sb) 120 { 121 if ( this == sb ) 122 { 123 return true; 124 } 125 return swigCPtr == getCPtr((XMLErrorLog)(sb)); 126 } 127 128 /** 129 * Returns a hashcode for this XMLErrorLog object. 130 * 131 * @return a hash code usable by Java methods that need them. 132 */ 133 public int hashCode() 134 { 135 return (int)(swigCPtr^(swigCPtr>>>32)); 136 } 137 138 139/** 140 * Returns the number of errors that have been logged. 141 * <p> 142 * To retrieve individual errors from the log, callers may use 143 * {@link XMLErrorLog#getError(long n)} . 144 * <p> 145 * @return the number of errors that have been logged. 146 */ public 147 long getNumErrors() { 148 return libsbmlJNI.XMLErrorLog_getNumErrors(swigCPtr, this); 149 } 150 151 152/** 153 * Returns the <i>n</i>th {@link XMLError} object in this log. 154 * <p> 155 * Index <code>n</code> is counted from 0. Callers should first inquire about the 156 * number of items in the log by using the method 157 * {@link XMLErrorLog#getNumErrors()}. 158 * Attempts to use an error index number that exceeds the actual number 159 * of errors in the log will result in a <code>null</code> being returned. 160 * <p> 161 * @param n the index number of the error to retrieve (with 0 being the 162 * first error). 163 * <p> 164 * @return the <i>n</i>th {@link XMLError} in this log, or <code>null</code> if <code>n</code> is 165 * greater than or equal to 166 * {@link XMLErrorLog#getNumErrors()}. 167 * <p> 168 * @see #getNumErrors() 169 */ public 170 XMLError getError(long n) { 171 long cPtr = libsbmlJNI.XMLErrorLog_getError(swigCPtr, this, n); 172 return (cPtr == 0) ? null : new XMLError(cPtr, false); 173 } 174 175 176/** 177 * Deletes all errors from this log. 178 */ public 179 void clearLog() { 180 libsbmlJNI.XMLErrorLog_clearLog(swigCPtr, this); 181 } 182 183 184/** 185 * Creates a new empty {@link XMLErrorLog}. 186 * @internal 187 */ public 188 XMLErrorLog() { 189 this(libsbmlJNI.new_XMLErrorLog(), true); 190 } 191 192 193/** 194 * Logs the given {@link XMLError}. 195 * <p> 196 * @param error {@link XMLError}, the error to be logged. 197 * @internal 198 */ public 199 void add(XMLError error) { 200 libsbmlJNI.XMLErrorLog_add(swigCPtr, this, XMLError.getCPtr(error), error); 201 } 202 203 204/** 205 * Writes all errors contained in this log to a string and returns it. 206 * <p> 207 * This method uses printErrors() to format the diagnostic messages. 208 * Please consult that method for information about the organization 209 * of the messages in the string returned by this method. 210 * <p> 211 * @return a string containing all logged errors and warnings. 212 * <p> 213 * @see #printErrors() 214 */ public 215 String toString() { 216 return libsbmlJNI.XMLErrorLog_toString(swigCPtr, this); 217 } 218 219 220/** 221 * Prints all the errors or warnings stored in this error log 222 * <p> 223 * It prints the text to the stream given by the optional parameter 224 * <code>stream</code>. If no parameter is given, it prints the output to the 225 * standard error stream. 226 * <p> 227 * If no errors have occurred, i.e., <code>getNumErrors() == 0</code>, no 228 * output will be sent to the stream. 229 * <p> 230 * The format of the output is: 231 * <div class='fragment'><pre> 232 N error(s): 233 line NNN: (id) message 234 </pre></div> 235 * <p> 236 * @param stream the ostream or ostringstream object indicating where 237 * the output should be printed. 238 * <p> 239 * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. --> 240</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd> 241The native C++ implementation of this method defines a default argument 242value. In the documentation generated for different libSBML language 243bindings, you may or may not see corresponding arguments in the method 244declarations. For example, in Java and C#, a default argument is handled by 245declaring two separate methods, with one of them having the argument and 246the other one lacking the argument. However, the libSBML documentation will 247be <em>identical</em> for both methods. Consequently, if you are reading 248this and do not see an argument even though one is described, please look 249for descriptions of other variants of this method near where this one 250appears in the documentation. 251</dd></dl> 252 253 */ public 254 void printErrors(OStream stream) { 255 libsbmlJNI.XMLErrorLog_printErrors__SWIG_0(swigCPtr, this, SWIGTYPE_p_std__ostream.getCPtr(stream.get_ostream()), stream); 256 } 257 258 259/** 260 * Prints all the errors or warnings stored in this error log 261 * <p> 262 * It prints the text to the stream given by the optional parameter 263 * <code>stream</code>. If no parameter is given, it prints the output to the 264 * standard error stream. 265 * <p> 266 * If no errors have occurred, i.e., <code>getNumErrors() == 0</code>, no 267 * output will be sent to the stream. 268 * <p> 269 * The format of the output is: 270 * <div class='fragment'><pre> 271 N error(s): 272 line NNN: (id) message 273 </pre></div> 274 * <p> 275 * @param stream the ostream or ostringstream object indicating where 276 * the output should be printed. 277 * <p> 278 * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. --> 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}