001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.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 *  Methods for checking the validity of SBML identifiers.
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 * This utility class provides static methods for checking the syntax of
023 * identifiers and other text used in an SBML model.  The methods allow
024 * callers to verify that strings such as SBML identifiers and XHTML notes
025 * text conform to the SBML specifications.
026 */
027
028public class SyntaxChecker {
029   private long swigCPtr;
030   protected boolean swigCMemOwn;
031
032   protected SyntaxChecker(long cPtr, boolean cMemoryOwn)
033   {
034     swigCMemOwn = cMemoryOwn;
035     swigCPtr    = cPtr;
036   }
037
038   protected static long getCPtr(SyntaxChecker obj)
039   {
040     return (obj == null) ? 0 : obj.swigCPtr;
041   }
042
043   protected static long getCPtrAndDisown (SyntaxChecker obj)
044   {
045     long ptr = 0;
046
047     if (obj != null)
048     {
049       ptr             = obj.swigCPtr;
050       obj.swigCMemOwn = false;
051     }
052
053     return ptr;
054   }
055
056  protected void finalize() {
057    delete();
058  }
059
060  public synchronized void delete() {
061    if (swigCPtr != 0) {
062      if (swigCMemOwn) {
063        swigCMemOwn = false;
064        libsbmlJNI.delete_SyntaxChecker(swigCPtr);
065      }
066      swigCPtr = 0;
067    }
068  }
069
070  
071/**
072   * Returns <code>true</code> or <code>false</code> depending on whether the argument
073   * string conforms to the syntax of SBML identifiers.
074   <p>
075   * <p>
076 * In SBML, identifiers that are the values of 'id' attributes on objects
077 * must conform to a data type called <code>SId</code> in the SBML
078 * specifications.  LibSBML does not provide an explicit <code>SId</code>
079 * data type; it uses ordinary character strings, which is easier for
080 * applications to support.  (LibSBML does, however, test for identifier
081 * validity at various times, such as when reading in models from files
082 * and data streams.) 
083   <p>
084   * This method provides programs with the ability to test explicitly that
085   * the identifier strings they create conform to the SBML identifier
086   * syntax.
087   <p>
088   * @param sid string to be checked for conformance to SBML identifier
089   * syntax.
090   <p>
091   * @return <code>true</code> if the string conforms to type SBML data type
092   * <code>SId</code>, <code>false</code> otherwise.
093   <p>
094   * The identifier given by an object's 'id' attribute value
095   * is used to identify the object within the SBML model definition.
096   * Other objects can refer to the component using this identifier.  The
097   * data type of 'id' is always <code>SId</code> or a type derived
098   * from that, such as <code>UnitSId</code>, depending on the object in 
099   * question.  All data types are defined as follows:
100   * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'>
101   *   letter .= 'a'..'z','A'..'Z'
102   *   digit  .= '0'..'9'
103   *   idChar .= letter | digit | '_'
104   *   SId    .= ( letter | '_' ) idChar*
105   * </pre>
106   <p>
107   * The equality of <code>SId</code> and <code>SId</code>-derived values
108   * in SBML is determined by an exact character sequence match; i.e.,
109   * comparisons of these identifiers must be performed in a case-sensitive
110   * manner.  This applies to all uses of <code>SId</code>, 
111   * <code>SIdRef</code>, and derived types.
112   <p>
113   * 
114   <p>
115   * @see SyntaxChecker#isValidUnitSId(String sid) 
116   * @see SyntaxChecker#isValidXMLID(String sid) 
117   */ public
118 static boolean isValidSBMLSId(String sid) {
119    return libsbmlJNI.SyntaxChecker_isValidSBMLSId(sid);
120  }
121
122  
123/**
124   * Returns <code>true</code> or <code>false</code> depending on whether the argument string
125   * conforms to the XML data type <code>ID</code>.
126   <p>
127   * <p>
128 * The optional attribute named 'metaid', present on every major SBML
129 * component type, is for supporting metadata annotations using RDF (<a
130 * href='http://www.w3.org/RDF/'>Resource Description Format</a>).  The
131 * attribute value has the data type <a
132 * href='http://www.w3.org/TR/REC-xml/#id'>XML <code>ID</code></a>, the XML
133 * identifier type, which means each 'metaid' value must be globally unique
134 * within an SBML file.  The latter point is important, because the
135 * uniqueness criterion applies across <em>any</em> attribute with type
136 * <code>ID</code> anywhere in the file, not just the 'metaid' attribute used
137 * by SBML&mdash;something to be aware of if your application-specific XML
138 * content inside the 'annotation' subelement happens to use the XML
139 * <code>ID</code> type.  Although SBML itself specifies the use of <a
140 * href='http://www.w3.org/TR/REC-xml/#id'>XML <code>ID</code></a> only for
141 * the 'metaid' attribute, SBML-compatible applications should be careful if
142 * they use XML <code>ID</code>'s in XML portions of a model that are not
143 * defined by SBML, such as in the application-specific content of the
144 * 'annotation' subelement.  Finally, note that LibSBML does not provide an
145 * explicit XML <code>ID</code> data type; it uses ordinary character
146 * strings, which is easier for applications to support. 
147   <p>
148   * This method provides programs with the ability to test explicitly that
149   * the identifier strings they create conform to the SBML identifier
150   * syntax.
151   <p>
152   * @param id string to be checked for conformance to the syntax of
153   * <a target='_blank' href='http://www.w3.org/TR/REC-xml/#id'>XML ID</a>.
154   <p>
155   * @return <code>true</code> if the string is a syntactically-valid value for the
156   * XML type <a target='_blank'
157   * href='http://www.w3.org/TR/REC-xml/#id'>ID</a>, <code>false</code> otherwise.
158   <p>
159   * @note The following is a summary of the definition of the XML&nbsp;1.0 data type
160<a target="_blank" href="http://www.w3.org/TR/REC-xml/#id">ID</a>.  We
161express the syntax using an extended form of BNF notation:
162<p>
163<nobr><code style="margin-left: 2em; letter-spacing: -1px">NCNameChar ::= letter | digit | '.' | '-' | '_' | ':' | CombiningChar | Extender</code><br></nobr>
164<code style="margin-left: 2em; letter-spacing: -1px">ID ::= ( letter | '_' | ':' ) NCNameChar*</code><br>
165<p>
166The characters <code>(</code> and <code>)</code> are used for grouping, the
167character <code>*</code> means "zero or more times", and the character
168<code>|</code> indicates logical "or". The production <code>letter</code>
169consists of the basic upper and lower case alphabetic characters of the
170Latin alphabet along with a large number of related characters defined by
171Unicode&nbsp;2.0; similarly, the production <code>digit</code> consists of
172the numerals <code>0..9</code> along with related Unicode&nbsp;2.0
173characters.  The <code>CombiningChar</code> production is a list of
174characters that add such things as accents to the preceding character. (For
175example, the Unicode character <code>\#x030A</code> when combined with
176<code>a</code> produces <code>a</code>.)  The <code>Extender</code>
177production is a list of characters that extend the shape of the preceding
178character.  Please consult the <a target="_blank"
179href="http://www.w3.org/TR/2004/REC-xml-20040204/">XML&nbsp;1.0
180specification</a> for the complete definitions of <code>letter</code>,
181<code>digit</code>, <code>CombiningChar</code>, and <code>Extender</code>.
182<p>
183
184   <p>
185   * 
186   <p>
187   * @see SyntaxChecker#isValidSBMLSId(String sid) 
188   * @see SyntaxChecker#isValidUnitSId(String sid) 
189   */ public
190 static boolean isValidXMLID(String id) {
191    return libsbmlJNI.SyntaxChecker_isValidXMLID(id);
192  }
193
194  
195/**
196   * Returns <code>true</code> or <code>false</code> depending on whether the <code>uri</code> argument string
197   * conforms to the XML data type <code>anyURI</code>.
198   <p>
199   * Type anyURI is defined by XML Schema 1.0. It is a character string 
200   * data type whose values are interpretable as URIs (Universal Resource 
201   * Identifiers) as described by the W3C document RFC 3986.  LibSBML
202   * does not provide an explicit XML <code>anyURI</code> data type; it uses
203   * ordinary character strings, which is easier for applications to
204   * support.  LibSBML does, however, test for anyURI validity at
205   * various times, such as when reading in models from files and data
206   * streams.
207   <p>
208   * This method provides programs with the ability to test explicitly that
209   * the strings they create conform to the XML anyURI syntax.
210   <p>
211   * @param uri string to be checked for conformance to the syntax of
212   * <a target='_blank' 
213   * href='http://www.w3.org/TR/xmlschema-2/#anyURI'>anyURI</a>.
214   <p>
215   * @return <code>true</code> if the string is a syntactically-valid value for the
216   * XML type <a target='_blank'
217   * href='http://www.w3.org/TR/xmlschema-2/#anyURI'>anyURI</a>, 
218   * <code>false</code> otherwise.
219   <p>
220   * 
221   */ public
222 static boolean isValidXMLanyURI(String uri) {
223    return libsbmlJNI.SyntaxChecker_isValidXMLanyURI(uri);
224  }
225
226  
227/**
228   * Returns <code>true</code> or <code>false</code> depending on whether the argument string
229   * conforms to the syntax of SBML unit identifiers.
230   <p>
231   * In SBML, the identifiers of units (of both the predefined units and
232   * user-defined units) must conform to a data type called
233   * <code>UnitSId</code> in the SBML specifications.  LibSBML does not
234   * provide an explicit <code>UnitSId</code> data type; it uses ordinary
235   * character strings, which is easier for applications to support.
236   * LibSBML does, however, test for identifier validity at various times,
237   * such as when reading in models from files and data streams.
238   <p>
239   * This method provides programs with the ability to test explicitly that
240   * the identifier strings they create conform to the SBML identifier
241   * syntax.
242   <p>
243   * @param units string to be checked for conformance to SBML unit
244   * identifier syntax.
245   <p>
246   * @return <code>true</code> if the string conforms to type SBML data type
247   * <code>UnitSId</code>, <code>false</code> otherwise.
248   <p>
249   * @note The following is a summary of the definition of the SBML identifier type
250<code>UnitSId</code>, which defines the permitted syntax of identifiers.
251We express the syntax using an extended form of BNF notation:
252<p>
253<code style="margin-left: 2em">letter ::= 'a'..'z','A'..'Z'</code><br>
254<code style="margin-left: 2em">digit  ::= '0'..'9'</code><br>
255<code style="margin-left: 2em">idChar ::= letter | digit | '_'</code><br>
256<code style="margin-left: 2em">SId    ::= ( letter | '_' ) idChar*</code><br>
257<p>
258The characters <code>(</code> and <code>)</code> are used for grouping, the
259character <code>*</code> "zero or more times", and the character
260<code>|</code> indicates logical "or".  The equality of SBML unit
261identifiers is determined by an exact character sequence match; i.e.,
262comparisons must be performed in a case-sensitive manner.  In addition,
263there are a few conditions for the uniqueness of unit identifiers in an
264SBML model.  Please consult the SBML specifications for the exact
265formulations.
266<p>
267
268   <p>
269   * 
270   <p>
271   * @see SyntaxChecker#isValidSBMLSId(String sid) 
272   * @see SyntaxChecker#isValidXMLID(String sid) 
273   */ public
274 static boolean isValidUnitSId(String units) {
275    return libsbmlJNI.SyntaxChecker_isValidUnitSId(units);
276  }
277
278  
279/**
280   * Returns <code>true</code> or <code>false</code> depending on whether the given {@link XMLNode}
281   * object contains valid XHTML content.
282   <p>
283   * <p>
284 * The optional SBML element named 'notes', present on every major SBML
285 * component type (and in SBML Level&nbsp;3, the 'message' subelement of
286 * {@link Constraint}), is intended as a place for storing optional information
287 * intended to be seen by humans.  An example use of the 'notes' element
288 * would be to contain formatted user comments about the model element in
289 * which the 'notes' element is enclosed.  Every object derived directly or
290 * indirectly from type {@link SBase} can have a separate value for 'notes', allowing
291 * users considerable freedom when adding comments to their models.
292 <p>
293 * The format of 'notes' elements conform to the definition of <a
294 * target='_blank' href='http://www.w3.org/TR/xhtml1/'>XHTML&nbsp;1.0</a>.
295 * However, the content cannot be <em>entirely</em> free-form; it must satisfy
296 * certain requirements defined in the <a target='_blank'
297 * href='http://sbml.org/Documents/Specifications'>SBML specifications</a>
298 * for specific SBML Levels.  To help verify the formatting of 'notes'
299 * content, libSBML provides the static utility method
300 * {@link SyntaxChecker#hasExpectedXHTMLSyntax(XMLNode)}; this
301 * method implements a verification process that lets callers check whether
302 * the content of a given {@link XMLNode} object conforms to the SBML requirements
303 * for 'notes' and 'message' structure.  Developers are urged to consult the
304 * appropriate <a target='_blank'
305 * href='http://sbml.org/Documents/Specifications'>SBML specification
306 * document</a> for the Level and Version of their model for more in-depth
307 * explanations of using 'notes' in SBML.  The SBML Level&nbsp;2 and&nbsp;3
308 * specifications have considerable detail about how 'notes' element content
309 * must be structured.
310   <p>
311   * An aspect of XHTML validity is that the content is declared to be in
312   * the XML namespace for XHTML&nbsp;1.0.  There is more than one way in
313   * which this can be done in XML.  In particular, a model might not
314   * contain the declaration within the 'notes' or 'message' subelement
315   * itself, but might instead place the declaration on an enclosing
316   * element and use an XML namespace prefix within the 'notes' element to
317   * refer to it.  In other words, the following is valid:
318   * <pre class='fragment'>
319&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'
320      xmlns:xhtml='http://www.w3.org/1999/xhtml'&gt;
321  &lt;model&gt;
322    &lt;notes&gt;
323      &lt;xhtml:body&gt;
324        &lt;xhtml:center&gt;&lt;xhtml:h2&gt;A Simple Mitotic Oscillator&lt;/xhtml:h2&gt;&lt;/xhtml:center&gt;
325        &lt;xhtml:p&gt;A minimal cascade model for the mitotic oscillator.&lt;/xhtml:p&gt;
326      &lt;/xhtml:body&gt;
327    &lt;/notes&gt;
328  ... rest of model ...
329&lt;/sbml&gt;
330</pre>
331   * Contrast the above with the following, self-contained version, which
332   * places the XML namespace declaration within the <code>&lt;notes&gt;</code>
333   * element itself:
334   * <pre class='fragment'>
335&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'&gt;
336  &lt;model&gt;
337    &lt;notes&gt;
338      &lt;html xmlns='http://www.w3.org/1999/xhtml'&gt;
339        &lt;head&gt;
340          &lt;title/&gt;
341        &lt;/head&gt;
342        &lt;body&gt;
343          &lt;center&gt;&lt;h2&gt;A Simple Mitotic Oscillator&lt;/h2&gt;&lt;/center&gt;
344          A minimal cascade model for the mitotic oscillator.&lt;/p&gt;
345        &lt;/body&gt;
346      &lt;/html&gt;
347    &lt;/notes&gt;
348  ... rest of model ...
349&lt;/sbml&gt;
350</pre>
351   <p>
352   * Both of the above are valid XML.  The purpose of the <code>sbmlns</code>
353   * argument to this method is to allow callers to check the validity of
354   * 'notes' and 'message' subelements whose XML namespace declarations
355   * have been put elsewhere in the manner illustrated above.  Callers can
356   * can pass in the {@link SBMLNamespaces} object of a higher-level model
357   * component if the {@link XMLNode} object does not itself have the XML namespace
358   * declaration for XHTML&nbsp;1.0.
359   <p>
360   * @param xhtml the {@link XMLNode} to be checked for conformance.
361   * @param sbmlns the {@link SBMLNamespaces} associated with the object.
362   <p>
363   * @return <code>true</code> if the {@link XMLNode} content conforms, <code>false</code> otherwise.
364   <p>
365   * 
366   <p>
367   * 
368</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
369The native C++ implementation of this method defines a default argument
370value. In the documentation generated for different libSBML language
371bindings, you may or may not see corresponding arguments in the method
372declarations. For example, in Java and C#, a default argument is handled by
373declaring two separate methods, with one of them having the argument and
374the other one lacking the argument. However, the libSBML documentation will
375be <em>identical</em> for both methods. Consequently, if you are reading
376this and do not see an argument even though one is described, please look
377for descriptions of other variants of this method near where this one
378appears in the documentation.
379</dd></dl>
380 
381   */ public
382 static boolean hasExpectedXHTMLSyntax(XMLNode xhtml, SBMLNamespaces sbmlns) {
383    return libsbmlJNI.SyntaxChecker_hasExpectedXHTMLSyntax__SWIG_0(XMLNode.getCPtr(xhtml), xhtml, SBMLNamespaces.getCPtr(sbmlns), sbmlns);
384  }
385
386  
387/**
388   * Returns <code>true</code> or <code>false</code> depending on whether the given {@link XMLNode}
389   * object contains valid XHTML content.
390   <p>
391   * <p>
392 * The optional SBML element named 'notes', present on every major SBML
393 * component type (and in SBML Level&nbsp;3, the 'message' subelement of
394 * {@link Constraint}), is intended as a place for storing optional information
395 * intended to be seen by humans.  An example use of the 'notes' element
396 * would be to contain formatted user comments about the model element in
397 * which the 'notes' element is enclosed.  Every object derived directly or
398 * indirectly from type {@link SBase} can have a separate value for 'notes', allowing
399 * users considerable freedom when adding comments to their models.
400 <p>
401 * The format of 'notes' elements conform to the definition of <a
402 * target='_blank' href='http://www.w3.org/TR/xhtml1/'>XHTML&nbsp;1.0</a>.
403 * However, the content cannot be <em>entirely</em> free-form; it must satisfy
404 * certain requirements defined in the <a target='_blank'
405 * href='http://sbml.org/Documents/Specifications'>SBML specifications</a>
406 * for specific SBML Levels.  To help verify the formatting of 'notes'
407 * content, libSBML provides the static utility method
408 * {@link SyntaxChecker#hasExpectedXHTMLSyntax(XMLNode)}; this
409 * method implements a verification process that lets callers check whether
410 * the content of a given {@link XMLNode} object conforms to the SBML requirements
411 * for 'notes' and 'message' structure.  Developers are urged to consult the
412 * appropriate <a target='_blank'
413 * href='http://sbml.org/Documents/Specifications'>SBML specification
414 * document</a> for the Level and Version of their model for more in-depth
415 * explanations of using 'notes' in SBML.  The SBML Level&nbsp;2 and&nbsp;3
416 * specifications have considerable detail about how 'notes' element content
417 * must be structured.
418   <p>
419   * An aspect of XHTML validity is that the content is declared to be in
420   * the XML namespace for XHTML&nbsp;1.0.  There is more than one way in
421   * which this can be done in XML.  In particular, a model might not
422   * contain the declaration within the 'notes' or 'message' subelement
423   * itself, but might instead place the declaration on an enclosing
424   * element and use an XML namespace prefix within the 'notes' element to
425   * refer to it.  In other words, the following is valid:
426   * <pre class='fragment'>
427&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'
428      xmlns:xhtml='http://www.w3.org/1999/xhtml'&gt;
429  &lt;model&gt;
430    &lt;notes&gt;
431      &lt;xhtml:body&gt;
432        &lt;xhtml:center&gt;&lt;xhtml:h2&gt;A Simple Mitotic Oscillator&lt;/xhtml:h2&gt;&lt;/xhtml:center&gt;
433        &lt;xhtml:p&gt;A minimal cascade model for the mitotic oscillator.&lt;/xhtml:p&gt;
434      &lt;/xhtml:body&gt;
435    &lt;/notes&gt;
436  ... rest of model ...
437&lt;/sbml&gt;
438</pre>
439   * Contrast the above with the following, self-contained version, which
440   * places the XML namespace declaration within the <code>&lt;notes&gt;</code>
441   * element itself:
442   * <pre class='fragment'>
443&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'&gt;
444  &lt;model&gt;
445    &lt;notes&gt;
446      &lt;html xmlns='http://www.w3.org/1999/xhtml'&gt;
447        &lt;head&gt;
448          &lt;title/&gt;
449        &lt;/head&gt;
450        &lt;body&gt;
451          &lt;center&gt;&lt;h2&gt;A Simple Mitotic Oscillator&lt;/h2&gt;&lt;/center&gt;
452          A minimal cascade model for the mitotic oscillator.&lt;/p&gt;
453        &lt;/body&gt;
454      &lt;/html&gt;
455    &lt;/notes&gt;
456  ... rest of model ...
457&lt;/sbml&gt;
458</pre>
459   <p>
460   * Both of the above are valid XML.  The purpose of the <code>sbmlns</code>
461   * argument to this method is to allow callers to check the validity of
462   * 'notes' and 'message' subelements whose XML namespace declarations
463   * have been put elsewhere in the manner illustrated above.  Callers can
464   * can pass in the {@link SBMLNamespaces} object of a higher-level model
465   * component if the {@link XMLNode} object does not itself have the XML namespace
466   * declaration for XHTML&nbsp;1.0.
467   <p>
468   * @param xhtml the {@link XMLNode} to be checked for conformance.
469   * @param sbmlns the {@link SBMLNamespaces} associated with the object.
470   <p>
471   * @return <code>true</code> if the {@link XMLNode} content conforms, <code>false</code> otherwise.
472   <p>
473   * 
474   <p>
475   * 
476</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
477The native C++ implementation of this method defines a default argument
478value. In the documentation generated for different libSBML language
479bindings, you may or may not see corresponding arguments in the method
480declarations. For example, in Java and C#, a default argument is handled by
481declaring two separate methods, with one of them having the argument and
482the other one lacking the argument. However, the libSBML documentation will
483be <em>identical</em> for both methods. Consequently, if you are reading
484this and do not see an argument even though one is described, please look
485for descriptions of other variants of this method near where this one
486appears in the documentation.
487</dd></dl>
488 
489   */ public
490 static boolean hasExpectedXHTMLSyntax(XMLNode xhtml) {
491    return libsbmlJNI.SyntaxChecker_hasExpectedXHTMLSyntax__SWIG_1(XMLNode.getCPtr(xhtml), xhtml);
492  }
493
494  
495/** * @internal */ public
496 static boolean isValidInternalSId(String sid) {
497    return libsbmlJNI.SyntaxChecker_isValidInternalSId(sid);
498  }
499
500  
501/** * @internal */ public
502 static boolean isValidInternalUnitSId(String sid) {
503    return libsbmlJNI.SyntaxChecker_isValidInternalUnitSId(sid);
504  }
505
506  public SyntaxChecker() {
507    this(libsbmlJNI.new_SyntaxChecker(), true);
508  }
509
510}