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}