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 * Base class for SBML validators
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 * LibSBML implements facilities for verifying that a given SBML document
024 * is valid according to the SBML specifications; it also exposes the
025 * validation interface so that user programs and SBML Level&nbsp;3 package
026 * authors may use the facilities to implement new validators.  There are
027 * two main interfaces to libSBML's validation facilities, based on the
028 * classes Validator and SBMLValidator.
029 * <p>
030 * The Validator class is the basis of the system for validating an SBML
031 * document against the validation rules defined in the SBML
032 * specifications.  The scheme used by Validator relies is compact and uses
033 * the <em>visitor</em> programming pattern, but it relies on C/C++ features and
034 * is not directly accessible from language bindings.  SBMLValidator offers
035 * a framework for straightforward class-based extensibility, so that user
036 * code can subclass SBMLValidator to implement new validation systems,
037 * different validators can be introduced or turned off at run-time, and
038 * interfaces can be provided in the libSBML language bindings.
039 * SBMLValidator can call Validator functionality internally (as is the
040 * case in the current implementation of SBMLInternalValidator) or use
041 * entirely different implementation approaches, as necessary.
042 * <p>
043 * Users of libSBML may already be familiar with the facilities encompassed
044 * by the validation system, in the form of the consistency-checking methods
045 * defined on {@link SBMLDocument}.  The methods {@link SBMLDocument#setConsistencyChecks(int categ, boolean onoff)},
046 * {@link SBMLDocument#checkConsistency()}, {@link SBMLDocument#checkInternalConsistency()}
047 * and other method of that sort are in fact implemented via SBMLValidator,
048 * specifically as methods on the class SBMLInternalValidator.
049 * <p>
050 * Authors may use SBMLValidator as the base class for their own validator
051 * extensions to libSBML.  The class SBMLInternalValidator may serve as a
052 * code example for how to implement such things.
053 */
054
055public class SBMLValidator {
056   private long swigCPtr;
057   protected boolean swigCMemOwn;
058
059   protected SBMLValidator(long cPtr, boolean cMemoryOwn)
060   {
061     swigCMemOwn = cMemoryOwn;
062     swigCPtr    = cPtr;
063   }
064
065   protected static long getCPtr(SBMLValidator obj)
066   {
067     return (obj == null) ? 0 : obj.swigCPtr;
068   }
069
070   protected static long getCPtrAndDisown (SBMLValidator obj)
071   {
072     long ptr = 0;
073
074     if (obj != null)
075     {
076       ptr             = obj.swigCPtr;
077       obj.swigCMemOwn = false;
078     }
079
080     return ptr;
081   }
082
083  protected void finalize() {
084    delete();
085  }
086
087  public synchronized void delete() {
088    if (swigCPtr != 0) {
089      if (swigCMemOwn) {
090        swigCMemOwn = false;
091        libsbmlJNI.delete_SBMLValidator(swigCPtr);
092      }
093      swigCPtr = 0;
094    }
095  }
096
097  protected void swigDirectorDisconnect() {
098    swigCMemOwn = false;
099    delete();
100  }
101
102  public void swigReleaseOwnership() {
103    swigCMemOwn = false;
104    libsbmlJNI.SBMLValidator_change_ownership(this, swigCPtr, false);
105  }
106
107  public void swigTakeOwnership() {
108    swigCMemOwn = true;
109    libsbmlJNI.SBMLValidator_change_ownership(this, swigCPtr, true);
110  }
111
112  
113/**
114   * Creates a new SBMLValidator.
115   */ public
116 SBMLValidator() {
117    this(libsbmlJNI.new_SBMLValidator__SWIG_0(), true);
118    libsbmlJNI.SBMLValidator_director_connect(this, swigCPtr, swigCMemOwn, true);
119  }
120
121  
122/**
123   * Copy constructor; creates a copy of an SBMLValidator object.
124   * <p>
125   * @param orig the object to copy.
126   * <p>
127   * @throws SBMLConstructorException 
128   * Thrown if the argument <code>orig</code> is <code>null.</code>
129   */ public
130 SBMLValidator(SBMLValidator orig) {
131    this(libsbmlJNI.new_SBMLValidator__SWIG_1(SBMLValidator.getCPtr(orig), orig), true);
132    libsbmlJNI.SBMLValidator_director_connect(this, swigCPtr, swigCMemOwn, true);
133  }
134
135  
136/**
137   * Creates and returns a deep copy of this SBMLValidator.
138   * <p>
139   * @return a (deep) copy of this SBMLValidator.
140   */ public
141 SBMLValidator cloneObject() {
142    long cPtr = (getClass() == SBMLValidator.class) ? libsbmlJNI.SBMLValidator_cloneObject(swigCPtr, this) : libsbmlJNI.SBMLValidator_cloneObjectSwigExplicitSBMLValidator(swigCPtr, this);
143    return (cPtr == 0) ? null : new SBMLValidator(cPtr, true);
144  }
145
146  
147/**
148   * Returns the current SBML document in use by this validator.
149   * <p>
150   * @return the current SBML document
151   * <p>
152   * @see #setDocument(SBMLDocument doc)
153   */ public
154 SBMLDocument getDocument() {
155    long cPtr = (getClass() == SBMLValidator.class) ? libsbmlJNI.SBMLValidator_getDocument__SWIG_0(swigCPtr, this) : libsbmlJNI.SBMLValidator_getDocumentSwigExplicitSBMLValidator__SWIG_0(swigCPtr, this);
156    return (cPtr == 0) ? null : new SBMLDocument(cPtr, false);
157  }
158
159  
160/** 
161   * Sets the current SBML document to the given {@link SBMLDocument} object.
162   * <p>
163   * @param doc the document to use for this validation
164   * <p>
165   * @return an integer value indicating the success/failure of the
166   * validation.   The possible values returned by this
167   * function are
168   * <ul>
169   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
170   * </ul>
171   * <p>
172   * @see #getDocument()
173   */ public
174 int setDocument(SBMLDocument doc) {
175    return (getClass() == SBMLValidator.class) ? libsbmlJNI.SBMLValidator_setDocument(swigCPtr, this, SBMLDocument.getCPtr(doc), doc) : libsbmlJNI.SBMLValidator_setDocumentSwigExplicitSBMLValidator(swigCPtr, this, SBMLDocument.getCPtr(doc), doc);
176  }
177
178  
179/** 
180   * Runs this validator on the current SBML document.
181   * <p>
182   * @return an integer value indicating the success/failure of the
183   * validation.   The possible values returned by this
184   * function are determined by the specific subclasses of this class.
185   */ public
186 long validate() {
187    return (getClass() == SBMLValidator.class) ? libsbmlJNI.SBMLValidator_validate__SWIG_0(swigCPtr, this) : libsbmlJNI.SBMLValidator_validateSwigExplicitSBMLValidator__SWIG_0(swigCPtr, this);
188  }
189
190  
191/**
192   * Clears this validator's list of failures.
193   * <p>
194   * If you are validating multiple SBML documents with the same validator,
195   * call this method after you have processed the list of failures from
196   * the last validation run and before validating the next document.
197   * <p>
198   * <p>
199   */ public
200 void clearFailures() {
201    if (getClass() == SBMLValidator.class) libsbmlJNI.SBMLValidator_clearFailures(swigCPtr, this); else libsbmlJNI.SBMLValidator_clearFailuresSwigExplicitSBMLValidator(swigCPtr, this);
202  }
203
204  
205/**
206   * Adds the given failure to this list of Validators failures.
207   * <p>
208   * @param err an {@link SBMLError} object representing an error or warning
209   * <p>
210   * <p>
211   */ public
212 void logFailure(SBMLError err) {
213    libsbmlJNI.SBMLValidator_logFailure(swigCPtr, this, SBMLError.getCPtr(err), err);
214  }
215
216  
217/**
218   * Validates the given {@link SBMLDocument} object.
219   * <p>
220   * This is identical to calling setDocument(SBMLDocument d )
221   * followed by validate().
222   * <p>
223   * @param d the SBML document to validate
224   * <p>
225   * @return the number of validation failures that occurred.  The objects
226   * describing the actual failures can be retrieved using getFailures().
227   */ public
228 long validate(SBMLDocument d) {
229    return libsbmlJNI.SBMLValidator_validate__SWIG_1(swigCPtr, this, SBMLDocument.getCPtr(d), d);
230  }
231
232  
233/**
234   * Validates the SBML document located at the given <code>filename</code>.
235   * <p>
236   * This is a convenience method that saves callers the trouble of
237   * using {@link SBMLReader} to read the document first.
238   * <p>
239   * @param filename the path to the file to be read and validated.
240   * <p>
241   * @return the number of validation failures that occurred.  The objects
242   * describing the actual failures can be retrieved using getFailures().
243   */ public
244 long validate(String filename) {
245    return libsbmlJNI.SBMLValidator_validate__SWIG_2(swigCPtr, this, libsbml.getAbsolutePath(filename));
246  }
247
248  
249/**
250   * Returns the list of errors or warnings logged during parsing,
251   * consistency checking, or attempted translation of this model.
252   * <p>
253   * Note that this refers to the {@link SBMLDocument} object's error log (i.e.,
254   * the list returned by {@link SBMLDocument#getErrorLog()}).  <em>That</em> list of
255   * errors and warnings is <em>separate</em> from the validation failures
256   * tracked by this validator (i.e., the list returned by getFailures()).
257   * <p>
258   * @return the {@link SBMLErrorLog} used for the {@link SBMLDocument}
259   * <p>
260   * <p>
261   */ public
262 SBMLErrorLog getErrorLog() {
263    long cPtr = libsbmlJNI.SBMLValidator_getErrorLog(swigCPtr, this);
264    return (cPtr == 0) ? null : new SBMLErrorLog(cPtr, false);
265  }
266
267  
268/**
269   * Returns the {@link Model} object stored in the {@link SBMLDocument}.
270   * <p>
271   * It is important to note that this method <em>does not create</em> a
272   * {@link Model} instance.  The model in the {@link SBMLDocument} must have been created
273   * at some prior time, for example using {@link SBMLDocument#createModel()} 
274   * or {@link SBMLDocument#setModel(Model m)}.
275   * This method returns <code>null</code> if a model does not yet exist.
276   * <p>
277   * @return the {@link Model} contained in this validator's {@link SBMLDocument} object.
278   * <p>
279   * @see SBMLDocument#setModel(Model m)
280   * @see SBMLDocument#createModel()
281   */ public
282 Model getModel() {
283    long cPtr = libsbmlJNI.SBMLValidator_getModel__SWIG_0(swigCPtr, this);
284    return (cPtr == 0) ? null : new Model(cPtr, false);
285  }
286
287  
288/** 
289   * Returns the number of failures encountered in the last validation run.
290   * <p>
291   * This method returns the number of failures logged by this validator.
292   * This number only reflects <em>this</em> validator's actions; the number may
293   * not be the same as the number of errors and warnings logged on the
294   * {@link SBMLDocument} object's error log (i.e., the object returned by
295   * {@link SBMLDocument#getErrorLog()}), because other parts of libSBML may log
296   * errors and warnings beyond those found by this validator.
297   * <p>
298   * @return the number of errors logged by this validator. 
299   */ public
300 long getNumFailures() {
301    return libsbmlJNI.SBMLValidator_getNumFailures(swigCPtr, this);
302  }
303
304  
305/** 
306   * Returns the failure object at index n in this validator's list of
307   * failures logged during the last run.
308   * <p>
309   * Callers should use getNumFailures() first, to find out the number
310   * of entries in this validator's list of failures.
311   * <p>
312   * @param n an integer indicating the index of the object to return from
313   * the failures list; index values start at 0.
314   * <p>
315   * @return the failure at the given index number.
316   * <p>
317   * @see #getNumFailures()
318   */ public
319 SBMLError getFailure(long n) {
320    long cPtr = libsbmlJNI.SBMLValidator_getFailure(swigCPtr, this, n);
321    return (cPtr == 0) ? null : new SBMLError(cPtr, false);
322  }
323
324}