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