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