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