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&nbsp;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&nbsp;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}