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 * Representation of XML Namespaces.
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 * This class serves to organize functionality for tracking XML namespaces
024 * in a document or data stream.  The namespace declarations are stored as
025 * a list of pairs of XML namespace URIs and prefix strings.  These
026 * correspond to the parts of a namespace declaration on an XML element.
027 * For example, in the following XML fragment,
028 * <div class='fragment'><pre>
029&lt;annotation&gt;
030    &lt;mysim:nodecolors xmlns:mysim='urn:lsid:mysim.org'
031         mysim:bgcolor='green' mysim:fgcolor='white'/&gt;
032&lt;/annotation&gt;
033</pre></div>
034 * there is one namespace declaration.  Its URI is
035 * <code>urn:lsid:mysim.org</code> and its prefix is <code>mysim</code>.
036 * This pair could be stored as one item in an {@link XMLNamespaces} list.
037 * <p>
038 * {@link XMLNamespaces} provides various methods for manipulating the list of
039 * prefix-URI pairs.  Individual namespaces stored in a given XMLNamespace
040 * object instance can be retrieved based on their index using
041 * {@link XMLNamespaces#getPrefix(int index)}, or by their characteristics such as
042 * their URI or position in the list.
043 */
044
045public class XMLNamespaces {
046   private long swigCPtr;
047   protected boolean swigCMemOwn;
048
049   protected XMLNamespaces(long cPtr, boolean cMemoryOwn)
050   {
051     swigCMemOwn = cMemoryOwn;
052     swigCPtr    = cPtr;
053   }
054
055   protected static long getCPtr(XMLNamespaces obj)
056   {
057     return (obj == null) ? 0 : obj.swigCPtr;
058   }
059
060   protected static long getCPtrAndDisown (XMLNamespaces obj)
061   {
062     long ptr = 0;
063
064     if (obj != null)
065     {
066       ptr             = obj.swigCPtr;
067       obj.swigCMemOwn = false;
068     }
069
070     return ptr;
071   }
072
073  protected void finalize() {
074    delete();
075  }
076
077  public synchronized void delete() {
078    if (swigCPtr != 0) {
079      if (swigCMemOwn) {
080        swigCMemOwn = false;
081        libsbmlJNI.delete_XMLNamespaces(swigCPtr);
082      }
083      swigCPtr = 0;
084    }
085  }
086
087  /**
088   * Equality comparison method for XMLNamespaces.
089   * <p>
090   * Because the Java methods for libSBML are actually wrappers around code
091   * implemented in C++ and C, certain operations will not behave as
092   * expected.  Equality comparison is one such case.  An instance of a
093   * libSBML object class is actually a <em>proxy object</em>
094   * wrapping the real underlying C/C++ object.  The normal <code>==</code>
095   * equality operator in Java will <em>only compare the Java proxy objects</em>,
096   * not the underlying native object.  The result is almost never what you
097   * want in practical situations.  Unfortunately, Java does not provide a
098   * way to override <code>==</code>.
099   *  <p>
100   * The alternative that must be followed is to use the
101   * <code>equals()</code> method.  The <code>equals</code> method on this
102   * class overrides the default java.lang.Object one, and performs an
103   * intelligent comparison of instances of objects of this class.  The
104   * result is an assessment of whether two libSBML Java objects are truly 
105   * the same underlying native-code objects.
106   *  <p>
107   * The use of this method in practice is the same as the use of any other
108   * Java <code>equals</code> method.  For example,
109   * <em>a</em><code>.equals(</code><em>b</em><code>)</code> returns
110   * <code>true</code> if <em>a</em> and <em>b</em> are references to the
111   * same underlying object.
112   *
113   * @param sb a reference to an object to which the current object
114   * instance will be compared
115   *
116   * @return <code>true</code> if <code>sb</code> refers to the same underlying 
117   * native object as this one, <code>false</code> otherwise
118   */
119  public boolean equals(Object sb)
120  {
121    if ( this == sb ) 
122    {
123      return true;
124    }
125    return swigCPtr == getCPtr((XMLNamespaces)(sb));
126  }
127
128  /**
129   * Returns a hashcode for this XMLNamespaces object.
130   *
131   * @return a hash code usable by Java methods that need them.
132   */
133  public int hashCode()
134  {
135    return (int)(swigCPtr^(swigCPtr>>>32));
136  }
137
138  
139/**
140   * Creates a new empty list of XML namespace declarations.
141   */ public
142 XMLNamespaces() throws org.sbml.libsbml.XMLConstructorException {
143    this(libsbmlJNI.new_XMLNamespaces__SWIG_0(), true);
144  }
145
146  
147/**
148   * Copy constructor; creates a copy of this {@link XMLNamespaces} list.
149   * <p>
150   * @param orig the {@link XMLNamespaces} object to copy
151   * <p>
152   * @throws XMLConstructorException 
153   * Thrown if the argument <code>orig</code> is <code>null.</code>
154   */ public
155 XMLNamespaces(XMLNamespaces orig) throws org.sbml.libsbml.XMLConstructorException {
156    this(libsbmlJNI.new_XMLNamespaces__SWIG_1(XMLNamespaces.getCPtr(orig), orig), true);
157  }
158
159  
160/**
161   * Creates and returns a deep copy of this {@link XMLNamespaces} list.
162   * <p>
163   * @return a (deep) copy of this {@link XMLNamespaces} list.
164   */ public
165 XMLNamespaces cloneObject() {
166    long cPtr = libsbmlJNI.XMLNamespaces_cloneObject(swigCPtr, this);
167    return (cPtr == 0) ? null : new XMLNamespaces(cPtr, true);
168  }
169
170  
171/**
172   * Appends an XML namespace prefix and URI pair to this list of namespace
173   * declarations.
174   * <p>
175   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
176   * prefixes.  If there is an XML namespace with the given <code>uri</code> prefix
177   * in this list, then its corresponding URI will be overwritten by the
178   * new <code>uri</code> unless the uri represents the core sbml namespace.
179   * Calling programs could use one of the other {@link XMLNamespaces}
180   * methods, such as
181   * {@link XMLNamespaces#hasPrefix(String)} and 
182   * {@link XMLNamespaces#hasURI(String)} to
183   * inquire whether a given prefix and/or URI
184   * is already present in this {@link XMLNamespaces} object.
185   * If the <code>uri</code> represents the sbml namespaces then it will not be
186   * overwritten, as this has potentially serious consequences. If it
187   * is necessary to replace the sbml namespace the namespace should be removed
188   * prior to adding the new namespace.
189   * <p>
190   * @param uri a string, the uri for the namespace
191   * @param prefix a string, the prefix for the namespace
192   * <p>
193   * @return integer value indicating success/failure of the
194   * function.   The possible values
195   * returned by this function are:
196   * <ul>
197   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
198   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
199   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
200   * </ul>
201   * <p>
202   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
203</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
204The native C++ implementation of this method defines a default argument
205value. In the documentation generated for different libSBML language
206bindings, you may or may not see corresponding arguments in the method
207declarations. For example, in Java and C#, a default argument is handled by
208declaring two separate methods, with one of them having the argument and
209the other one lacking the argument. However, the libSBML documentation will
210be <em>identical</em> for both methods. Consequently, if you are reading
211this and do not see an argument even though one is described, please look
212for descriptions of other variants of this method near where this one
213appears in the documentation.
214</dd></dl>
215 
216   */ public
217 int add(String uri, String prefix) {
218    return libsbmlJNI.XMLNamespaces_add__SWIG_0(swigCPtr, this, uri, prefix);
219  }
220
221  
222/**
223   * Appends an XML namespace prefix and URI pair to this list of namespace
224   * declarations.
225   * <p>
226   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
227   * prefixes.  If there is an XML namespace with the given <code>uri</code> prefix
228   * in this list, then its corresponding URI will be overwritten by the
229   * new <code>uri</code> unless the uri represents the core sbml namespace.
230   * Calling programs could use one of the other {@link XMLNamespaces}
231   * methods, such as
232   * {@link XMLNamespaces#hasPrefix(String)} and 
233   * {@link XMLNamespaces#hasURI(String)} to
234   * inquire whether a given prefix and/or URI
235   * is already present in this {@link XMLNamespaces} object.
236   * If the <code>uri</code> represents the sbml namespaces then it will not be
237   * overwritten, as this has potentially serious consequences. If it
238   * is necessary to replace the sbml namespace the namespace should be removed
239   * prior to adding the new namespace.
240   * <p>
241   * @param uri a string, the uri for the namespace
242   * @param prefix a string, the prefix for the namespace
243   * <p>
244   * @return integer value indicating success/failure of the
245   * function.   The possible values
246   * returned by this function are:
247   * <ul>
248   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
249   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
250   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
251   * </ul>
252   * <p>
253   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
254</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
255The native C++ implementation of this method defines a default argument
256value. In the documentation generated for different libSBML language
257bindings, you may or may not see corresponding arguments in the method
258declarations. For example, in Java and C#, a default argument is handled by
259declaring two separate methods, with one of them having the argument and
260the other one lacking the argument. However, the libSBML documentation will
261be <em>identical</em> for both methods. Consequently, if you are reading
262this and do not see an argument even though one is described, please look
263for descriptions of other variants of this method near where this one
264appears in the documentation.
265</dd></dl>
266 
267   */ public
268 int add(String uri) {
269    return libsbmlJNI.XMLNamespaces_add__SWIG_1(swigCPtr, this, uri);
270  }
271
272  
273/**
274   * Removes an XML Namespace stored in the given position of this list.
275   * <p>
276   * @param index an integer, position of the namespace to remove.
277   * <p>
278   * @return integer value indicating success/failure of the
279   * function.   The possible values
280   * returned by this function are:
281   * <ul>
282   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
283   * <li> {@link  libsbmlConstants#LIBSBML_INDEX_EXCEEDS_SIZE LIBSBML_INDEX_EXCEEDS_SIZE }
284   * </ul>
285   */ public
286 int remove(int index) {
287    return libsbmlJNI.XMLNamespaces_remove__SWIG_0(swigCPtr, this, index);
288  }
289
290  
291/**
292   * Removes an XML Namespace with the given prefix.
293   * <p>
294   * @param prefix a string, prefix of the required namespace.
295   * <p>
296   * @return integer value indicating success/failure of the
297   * function.   The possible values
298   * returned by this function are:
299   * <ul>
300   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
301   * <li> {@link  libsbmlConstants#LIBSBML_INDEX_EXCEEDS_SIZE LIBSBML_INDEX_EXCEEDS_SIZE }
302   * </ul>
303   * <p>
304   * @see #remove(int index)
305   */ public
306 int remove(String prefix) {
307    return libsbmlJNI.XMLNamespaces_remove__SWIG_1(swigCPtr, this, prefix);
308  }
309
310  
311/**
312   * Clears (deletes) all XML namespace declarations in this {@link XMLNamespaces}
313   * object.
314   * <p>
315   * @return integer value indicating success/failure of the
316   * function. The possible values
317   * returned by this function are:
318   * <ul>
319   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
320   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
321   * </ul>
322   * <p>
323   * @see #remove(int index)
324   */ public
325 int clear() {
326    return libsbmlJNI.XMLNamespaces_clear(swigCPtr, this);
327  }
328
329  
330/**
331   * Look up the index of an XML namespace declaration by URI.
332   * <p>
333   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
334   * prefixes.  If this {@link XMLNamespaces} object contains a pair with the given
335   * URI <code>uri</code>, this method returns its index in the list.
336   * <p>
337   * @param uri a string, the URI of the sought-after namespace.
338   * <p>
339   * @return the index of the given declaration, or <code>-1</code> if not
340   * present.
341   */ public
342 int getIndex(String uri) {
343    return libsbmlJNI.XMLNamespaces_getIndex(swigCPtr, this, uri);
344  }
345
346  
347/**
348   * Tests whether the given uri is contained in this set of namespaces. 
349   * <p>
350   */ public
351 boolean containsUri(String uri) {
352    return libsbmlJNI.XMLNamespaces_containsUri(swigCPtr, this, uri);
353  }
354
355  
356/**
357   * Look up the index of an XML namespace declaration by prefix.
358   * <p>
359   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
360   * prefixes.  If this {@link XMLNamespaces} object contains a pair with the given
361   * prefix <code>prefix</code>, this method returns its index in the list.
362   * <p>
363   * @param prefix a string, the prefix string of the sought-after
364   * namespace
365   * <p>
366   * @return the index of the given declaration, or <code>-1</code> if not
367   * present.
368   */ public
369 int getIndexByPrefix(String prefix) {
370    return libsbmlJNI.XMLNamespaces_getIndexByPrefix(swigCPtr, this, prefix);
371  }
372
373  
374/**
375   * Returns the total number of URI-and-prefix pairs stored in this
376   * particular {@link XMLNamespaces} instance.
377   * <p>
378   * @return the number of namespaces in this list.
379   */ public
380 int getLength() {
381    return libsbmlJNI.XMLNamespaces_getLength(swigCPtr, this);
382  }
383
384  
385/**
386   * Returns the total number of URI-and-prefix pairs stored in this
387   * particular {@link XMLNamespaces} instance.
388   * <p>
389   * @return the number of namespaces in this list.
390   * <p>
391   * This function is an alias for getLength introduced for consistency
392   * with other XML classes.
393   */ public
394 int getNumNamespaces() {
395    return libsbmlJNI.XMLNamespaces_getNumNamespaces(swigCPtr, this);
396  }
397
398  
399/**
400   * Look up the prefix of an XML namespace declaration by its position.
401   * <p>
402   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
403   * prefixes.  This method returns the prefix of the <code>n</code>th
404   * element in that list (if it exists).  Callers should use
405   * {@link XMLAttributes#getLength()} first to find out how many namespaces are
406   * stored in the list.
407   * <p>
408   * @param index an integer, position of the sought-after prefix
409   * <p>
410   * @return the prefix of an XML namespace declaration in this list (by
411   * position), or an empty string if the <code>index</code> is out of range
412   * <p>
413   * @see #getLength()
414   */ public
415 String getPrefix(int index) {
416    return libsbmlJNI.XMLNamespaces_getPrefix__SWIG_0(swigCPtr, this, index);
417  }
418
419  
420/**
421   * Look up the prefix of an XML namespace declaration by its URI.
422   * <p>
423   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
424   * prefixes.  This method returns the prefix for a pair that has the
425   * given <code>uri</code>.
426   * <p>
427   * @param uri a string, the URI of the prefix being sought
428   * <p>
429   * @return the prefix of an XML namespace declaration given its URI, or
430   * an empty string if no such <code>uri</code> exists in this {@link XMLNamespaces} object
431   */ public
432 String getPrefix(String uri) {
433    return libsbmlJNI.XMLNamespaces_getPrefix__SWIG_1(swigCPtr, this, uri);
434  }
435
436  
437/**
438   * Look up the URI of an XML namespace declaration by its position.
439   * <p>
440   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
441   * prefixes.  This method returns the URI of the <code>n</code>th element
442   * in that list (if it exists).  Callers should use
443   * {@link XMLAttributes#getLength()} first to find out how many namespaces are
444   * stored in the list.
445   * <p>
446   * @param index an integer, position of the required URI.
447   * <p>
448   * @return the URI of an XML namespace declaration in this list (by
449   * position), or an empty string if the <code>index</code> is out of range.
450   * <p>
451   * @see #getLength()
452   */ public
453 String getURI(int index) {
454    return libsbmlJNI.XMLNamespaces_getURI__SWIG_0(swigCPtr, this, index);
455  }
456
457  
458/**
459   * Look up the URI of an XML namespace declaration by its prefix.
460   * <p>
461   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
462   * prefixes.  This method returns the namespace URI for a pair that has
463   * the given <code>prefix</code>.
464   * <p>
465   * @param prefix a string, the prefix of the required URI
466   * <p>
467   * @return the URI of an XML namespace declaration having the given 
468   * <code>prefix</code>, or an empty string if no such prefix-and-URI pair exists
469   * in this {@link XMLNamespaces} object
470   * <p>
471   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
472</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
473The native C++ implementation of this method defines a default argument
474value. In the documentation generated for different libSBML language
475bindings, you may or may not see corresponding arguments in the method
476declarations. For example, in Java and C#, a default argument is handled by
477declaring two separate methods, with one of them having the argument and
478the other one lacking the argument. However, the libSBML documentation will
479be <em>identical</em> for both methods. Consequently, if you are reading
480this and do not see an argument even though one is described, please look
481for descriptions of other variants of this method near where this one
482appears in the documentation.
483</dd></dl>
484 
485   * <p>
486   * @see #getURI()
487   */ public
488 String getURI(String prefix) {
489    return libsbmlJNI.XMLNamespaces_getURI__SWIG_1(swigCPtr, this, prefix);
490  }
491
492  
493/**
494   * Look up the URI of an XML namespace declaration by its prefix.
495   * <p>
496   * An {@link XMLNamespaces} object stores a list of pairs of namespaces and their
497   * prefixes.  This method returns the namespace URI for a pair that has
498   * the given <code>prefix</code>.
499   * <p>
500   * @param prefix a string, the prefix of the required URI
501   * <p>
502   * @return the URI of an XML namespace declaration having the given 
503   * <code>prefix</code>, or an empty string if no such prefix-and-URI pair exists
504   * in this {@link XMLNamespaces} object
505   * <p>
506   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
507</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
508The native C++ implementation of this method defines a default argument
509value. In the documentation generated for different libSBML language
510bindings, you may or may not see corresponding arguments in the method
511declarations. For example, in Java and C#, a default argument is handled by
512declaring two separate methods, with one of them having the argument and
513the other one lacking the argument. However, the libSBML documentation will
514be <em>identical</em> for both methods. Consequently, if you are reading
515this and do not see an argument even though one is described, please look
516for descriptions of other variants of this method near where this one
517appears in the documentation.
518</dd></dl>
519 
520   * <p>
521   * @see #getURI()
522   */ public
523 String getURI() {
524    return libsbmlJNI.XMLNamespaces_getURI__SWIG_2(swigCPtr, this);
525  }
526
527  
528/**
529   * Predicate returning <code>true</code> or <code>false</code> depending on whether this
530   * {@link XMLNamespaces} list is empty.
531   * <p>
532   * @return <code>true</code> if this {@link XMLNamespaces} list is empty, <code>false</code> otherwise.
533   */ public
534 boolean isEmpty() {
535    return libsbmlJNI.XMLNamespaces_isEmpty(swigCPtr, this);
536  }
537
538  
539/**
540   * Predicate returning <code>true</code> or <code>false</code> depending on whether an XML
541   * Namespace with the given URI is contained in this {@link XMLNamespaces} list.
542   * <p>
543   * @param uri a string, the uri for the namespace
544   * <p>
545   * @return <code>true</code> if an XML Namespace with the given URI is contained in
546   * this {@link XMLNamespaces} list, <code>false</code> otherwise.
547   */ public
548 boolean hasURI(String uri) {
549    return libsbmlJNI.XMLNamespaces_hasURI(swigCPtr, this, uri);
550  }
551
552  
553/**
554   * Predicate returning <code>true</code> or <code>false</code> depending on whether an XML
555   * Namespace with the given prefix is contained in this {@link XMLNamespaces}
556   * list.
557   * <p>
558   * @param prefix a string, the prefix for the namespace
559   * <p>
560   * @return <code>true</code> if an XML Namespace with the given URI is contained in
561   * this {@link XMLNamespaces} list, <code>false</code> otherwise.
562   */ public
563 boolean hasPrefix(String prefix) {
564    return libsbmlJNI.XMLNamespaces_hasPrefix(swigCPtr, this, prefix);
565  }
566
567  
568/**
569   * Predicate returning <code>true</code> or <code>false</code> depending on whether an XML
570   * Namespace with the given URI and prefix pair is contained in this
571   * {@link XMLNamespaces} list.
572   * <p>
573   * @param uri a string, the URI for the namespace
574   * @param prefix a string, the prefix for the namespace
575   * <p>
576   * @return <code>true</code> if an XML Namespace with the given uri/prefix pair is
577   * contained in this {@link XMLNamespaces} list, <code>false</code> otherwise.
578   */ public
579 boolean hasNS(String uri, String prefix) {
580    return libsbmlJNI.XMLNamespaces_hasNS(swigCPtr, this, uri, prefix);
581  }
582
583}