001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
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&nbsp;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&nbsp;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  
534/**
535  * Returns <code>true</code> if {@link XMLErrorLog} contains an errorId
536  <p>
537  * @param errorId the error identifier of the error to be found.
538  */ public
539 boolean contains(long errorId) {
540    return libsbmlJNI.XMLErrorLog_contains(swigCPtr, this, errorId);
541  }
542
543}