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 *  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, boolean)},
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   */ public
126 SBMLValidator(SBMLValidator orig) {
127    this(libsbmlJNI.new_SBMLValidator__SWIG_1(SBMLValidator.getCPtr(orig), orig), true);
128    libsbmlJNI.SBMLValidator_director_connect(this, swigCPtr, swigCMemOwn, true);
129  }
130
131  
132/**
133   * Creates and returns a deep copy of this {@link SBMLValidator} object.
134   <p>
135   * @return the (deep) copy of this {@link SBMLValidator} object.
136   */ public
137 SBMLValidator cloneObject() {
138    long cPtr = (getClass() == SBMLValidator.class) ? libsbmlJNI.SBMLValidator_cloneObject(swigCPtr, this) : libsbmlJNI.SBMLValidator_cloneObjectSwigExplicitSBMLValidator(swigCPtr, this);
139    return (cPtr == 0) ? null : new SBMLValidator(cPtr, true);
140  }
141
142  
143/**
144   * Returns the current SBML document in use by this validator.
145   <p>
146   * @return the current SBML document.
147   <p>
148   * @see #setDocument(SBMLDocument)
149   */ public
150 SBMLDocument getDocument() {
151    long cPtr = (getClass() == SBMLValidator.class) ? libsbmlJNI.SBMLValidator_getDocument__SWIG_0(swigCPtr, this) : libsbmlJNI.SBMLValidator_getDocumentSwigExplicitSBMLValidator__SWIG_0(swigCPtr, this);
152    return (cPtr == 0) ? null : new SBMLDocument(cPtr, false);
153  }
154
155  
156/** 
157   * Sets the current SBML document to the given {@link SBMLDocument} object.
158   <p>
159   * @param doc the document to use for this validation.
160   <p>
161   * <p>
162 * @return integer value indicating success/failure of the
163 * function.   This particular
164 * function only does one thing irrespective of user input or 
165 * object state, and thus will only return a single value:
166   * <ul>
167   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
168   *
169   * </ul> <p>
170   * @see #getDocument()
171   */ public
172 int setDocument(SBMLDocument doc) {
173    return (getClass() == SBMLValidator.class) ? libsbmlJNI.SBMLValidator_setDocument(swigCPtr, this, SBMLDocument.getCPtr(doc), doc) : libsbmlJNI.SBMLValidator_setDocumentSwigExplicitSBMLValidator(swigCPtr, this, SBMLDocument.getCPtr(doc), doc);
174  }
175
176  
177/** 
178   * Runs this validator on the current SBML document.
179   <p>
180   * @return an integer value indicating the success/failure of the
181   * validation.   The possible values returned by this
182   * function are determined by the specific subclasses of this class.
183   */ public
184 long validate() {
185    return (getClass() == SBMLValidator.class) ? libsbmlJNI.SBMLValidator_validate__SWIG_0(swigCPtr, this) : libsbmlJNI.SBMLValidator_validateSwigExplicitSBMLValidator__SWIG_0(swigCPtr, this);
186  }
187
188  
189/**
190   * Clears this validator's list of failures.
191   <p>
192   * If you are validating multiple SBML documents with the same validator,
193   * call this method after you have processed the list of failures from
194   * the last validation run and before validating the next document.
195   */ public
196 void clearFailures() {
197    if (getClass() == SBMLValidator.class) libsbmlJNI.SBMLValidator_clearFailures(swigCPtr, this); else libsbmlJNI.SBMLValidator_clearFailuresSwigExplicitSBMLValidator(swigCPtr, this);
198  }
199
200  
201/**
202   * Adds the given failure to this list of Validators failures.
203   <p>
204   * @param err an {@link SBMLError} object representing an error or warning.
205   */ public
206 void logFailure(SBMLError err) {
207    libsbmlJNI.SBMLValidator_logFailure(swigCPtr, this, SBMLError.getCPtr(err), err);
208  }
209
210  
211/**
212   * Validates the given {@link SBMLDocument} object.
213   <p>
214   * This is identical to calling setDocument(SBMLDocument )
215   * followed by validate().
216   <p>
217   * @param d the SBML document to validate.
218   <p>
219   * @return the number of validation failures that occurred.  The objects
220   * describing the actual failures can be retrieved using getFailures().
221   */ public
222 long validate(SBMLDocument d) {
223    return libsbmlJNI.SBMLValidator_validate__SWIG_1(swigCPtr, this, SBMLDocument.getCPtr(d), d);
224  }
225
226  
227/**
228   * Validates the SBML document located at the given <code>filename</code>.
229   <p>
230   * This is a convenience method that saves callers the trouble of
231   * using {@link SBMLReader} to read the document first.
232   <p>
233   * @param filename the path to the file to be read and validated.
234   <p>
235   * @return the number of validation failures that occurred.  The objects
236   * describing the actual failures can be retrieved using getFailures().
237   */ public
238 long validate(String filename) {
239    return libsbmlJNI.SBMLValidator_validate__SWIG_2(swigCPtr, this, libsbml.getAbsolutePath(filename));
240  }
241
242  
243/**
244   * Returns the list of errors or warnings logged during parsing,
245   * consistency checking, or attempted translation of this model.
246   <p>
247   * Note that this refers to the {@link SBMLDocument} object's error log (i.e.,
248   * the list returned by {@link SBMLDocument#getErrorLog()}).  <em>That</em> list of
249   * errors and warnings is <em>separate</em> from the validation failures
250   * tracked by this validator (i.e., the list returned by getFailures()).
251   <p>
252   * @return the {@link SBMLErrorLog} used for the {@link SBMLDocument}.
253   */ public
254 SBMLErrorLog getErrorLog() {
255    long cPtr = libsbmlJNI.SBMLValidator_getErrorLog(swigCPtr, this);
256    return (cPtr == 0) ? null : new SBMLErrorLog(cPtr, false);
257  }
258
259  
260/**
261   * Returns the {@link Model} object stored in the {@link SBMLDocument}.
262   <p>
263   * It is important to note that this method <em>does not create</em> a
264   * {@link Model} instance.  The model in the {@link SBMLDocument} must have been created
265   * at some prior time, for example using {@link SBMLDocument#createModel()} 
266   * or {@link SBMLDocument#setModel(Model)}.
267   * This method returns <code>null</code> if a model does not yet exist.
268   <p>
269   * @return the {@link Model} contained in this validator's {@link SBMLDocument} object.
270   <p>
271   * @see SBMLDocument#setModel(Model)
272   * @see SBMLDocument#createModel()
273   */ public
274 Model getModel() {
275    long cPtr = libsbmlJNI.SBMLValidator_getModel__SWIG_0(swigCPtr, this);
276    return (cPtr == 0) ? null : new Model(cPtr, false);
277  }
278
279  
280/** 
281   * Returns the number of failures encountered in the last validation run.
282   <p>
283   * This method returns the number of failures logged by this validator.
284   * This number only reflects <em>this</em> validator's actions; the number may
285   * not be the same as the number of errors and warnings logged on the
286   * {@link SBMLDocument} object's error log (i.e., the object returned by
287   * {@link SBMLDocument#getErrorLog()}), because other parts of libSBML may log
288   * errors and warnings beyond those found by this validator.
289   <p>
290   * @return the number of errors logged by this validator.
291   */ public
292 long getNumFailures() {
293    return libsbmlJNI.SBMLValidator_getNumFailures(swigCPtr, this);
294  }
295
296  
297/** 
298   * Returns the failure object at index n in this validator's list of
299   * failures logged during the last run.
300   <p>
301   * Callers should use getNumFailures() first, to find out the number
302   * of entries in this validator's list of failures.
303   <p>
304   * @param n an integer indicating the index of the object to return from
305   * the failures list; index values start at 0.
306   <p>
307   * @return the failure at the given index number.
308   <p>
309   * @see #getNumFailures()
310   */ public
311 SBMLError getFailure(long n) {
312    long cPtr = libsbmlJNI.SBMLValidator_getFailure(swigCPtr, this, n);
313    return (cPtr == 0) ? null : new SBMLError(cPtr, false);
314  }
315
316}