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