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 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}