001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 *  Base class for extending {@link SBMLDocument} in packages.
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 * The {@link SBMLDocumentPlugin} class is a specialization of {@link SBasePlugin}
023 * designed specifically for extending {@link SBMLDocument}.  All package
024 * extensions must extend {@link SBMLDocument} to implement support for SBML
025 * Level&nbsp;3 packages; these extensions can be subclasses of this
026 * class or from a derived class of this class.
027 <p>
028 * <p>
029 * <h2>Basic principles of SBML package extensions in libSBML</h2>
030 <p>
031 * SBML Level&nbsp;3's package structure permits modular extensions to the
032 * core SBML format.  In libSBML, support for SBML Level&nbsp;3 packages is
033 * provided through optional <em>package extensions</em> that can be plugged
034 * into libSBML at the time it is built/compiled.  Users of libSBML can thus
035 * choose which extensions are enabled in their software applications.
036 <p>
037 * LibSBML defines a number of classes that developers of package extensions
038 * can use to implement support for an SBML Level&nbsp;3 package.  These
039 * classes make it easier to extend libSBML objects with new attributes
040 * and/or subobjects as needed by a particular Level&nbsp;3 package.
041 * Three overall categories of classes make up libSBML's facilities for
042 * implementing package extensions.  There are (1) classes that serve as base
043 * classes meant to be subclassed, (2) template classes meant to be
044 * instantiated rather than subclassed, and (3) support classes that provide
045 * utility features. A given package implementation for libSBML will take
046 * the form of code using these and other libSBML classes, placed in a
047 * subdirectory of <code>src/sbml/packages/</code>.
048 <p>
049 * The basic libSBML distribution includes a number of package extensions
050 * implementing support for officially-endorsed SBML Level&nbsp;3 packages;
051 * among these are <em>Flux Balance Constraints</em> ('fbc'),
052 * <em>Hierarchical Model Composition</em> ('comp'), <em>Layout</em>
053 * ('layout'), and <em>Qualitative Models</em> ('qual').  They can serve as
054 * working examples for developers working to implement other packages.
055 <p>
056 * Extensions in libSBML can currently only be implemented in C++ or C;
057 * there is no mechanism to implement them first in languages such as
058 * Java or Python.  However, once implemented in C++ or C, language
059 * interfaces can be generated semi-automatically using the framework in
060 * place in libSBML.  (The approach is based on using <a target='_blank'
061 * href='http://www.swig.org'>SWIG</a> and facilities in libSBML's build
062 * system.)
063 */
064
065public class SBMLDocumentPlugin extends SBasePlugin {
066   private long swigCPtr;
067
068   protected SBMLDocumentPlugin(long cPtr, boolean cMemoryOwn)
069   {
070     super(libsbmlJNI.SBMLDocumentPlugin_SWIGUpcast(cPtr), cMemoryOwn);
071     swigCPtr = cPtr;
072   }
073
074   protected static long getCPtr(SBMLDocumentPlugin obj)
075   {
076     return (obj == null) ? 0 : obj.swigCPtr;
077   }
078
079   protected static long getCPtrAndDisown (SBMLDocumentPlugin obj)
080   {
081     long ptr = 0;
082
083     if (obj != null)
084     {
085       ptr             = obj.swigCPtr;
086       obj.swigCMemOwn = false;
087     }
088
089     return ptr;
090   }
091
092  protected void finalize() {
093    delete();
094  }
095
096  public synchronized void delete() {
097    if (swigCPtr != 0) {
098      if (swigCMemOwn) {
099        swigCMemOwn = false;
100        libsbmlJNI.delete_SBMLDocumentPlugin(swigCPtr);
101      }
102      swigCPtr = 0;
103    }
104    super.delete();
105  }
106
107  
108/**
109   * Creates a new {@link SBMLDocumentPlugin} object using the given parameters.
110   <p>
111   * <p>
112 * In the XML representation of an SBML document, XML namespaces are used to
113 * identify the origin of each XML construct used.  XML namespaces are
114 * identified by their unique resource identifiers (URIs).  The core SBML
115 * specifications stipulate the namespaces that must be used for core SBML
116 * constructs; for example, all XML elements that belong to SBML Level&nbsp;3
117 * Version&nbsp;1 Core must be placed in the XML namespace identified by the URI
118 * <code>'http://www.sbml.org/sbml/level3/version1/core'</code>.  Individual
119 * SBML Level&nbsp;3 packages define their own XML namespaces; for example,
120 * all elements belonging to the SBML Level&nbsp;3 Layout Version&nbsp;1
121 * package must be placed in the XML namespace
122 * <code>'http://www.sbml.org/sbml/level3/version1/layout/version1/'</code>.
123   <p>
124   * <p>
125 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
126 * information.  It is used to communicate the SBML Level, Version, and (in
127 * Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.  A
128 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
129 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object
130 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments.
131   <p>
132   * @param uri the URI of the SBML Level&nbsp;3 package implemented by
133   * this libSBML package extension.
134   <p>
135   * @param prefix the XML namespace prefix being used for the package.
136   <p>
137   * @param sbmlns the {@link SBMLNamespaces} object for the package.
138   */ public
139 SBMLDocumentPlugin(String uri, String prefix, SBMLNamespaces sbmlns) {
140    this(libsbmlJNI.new_SBMLDocumentPlugin__SWIG_0(uri, prefix, SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
141  }
142
143  
144/**
145   * Copy constructor.
146   <p>
147   * This creates a copy of this object.
148   <p>
149   * @param orig the {@link SBMLDocumentPlugin} instance to copy.
150   */ public
151 SBMLDocumentPlugin(SBMLDocumentPlugin orig) {
152    this(libsbmlJNI.new_SBMLDocumentPlugin__SWIG_1(SBMLDocumentPlugin.getCPtr(orig), orig), true);
153  }
154
155  
156/**
157   * Creates and returns a deep copy of this {@link SBMLDocumentPlugin} object.
158   <p>
159   * @return the (deep) copy of this {@link SBMLDocumentPlugin} object.
160   */ public
161 SBasePlugin cloneObject() {
162    long cPtr = libsbmlJNI.SBMLDocumentPlugin_cloneObject(swigCPtr, this);
163    return (cPtr == 0) ? null : new SBMLDocumentPlugin(cPtr, true);
164  }
165
166  
167/**
168   * Sets the SBML 'required' attribute value.
169   <p>
170   * <p>
171 * SBML Level&nbsp;3 requires that every package defines an attribute named
172 * 'required' on the root <code>&lt;sbml&gt;</code> element in an SBML file
173 * or data stream.  The attribute, being in the namespace of the Level&nbsp;3
174 * package in question, must be prefixed by the XML namespace prefix
175 * associated with the package.  The value of the 'required' attribute
176 * indicates whether constructs in that package may change the mathematical
177 * interpretation of constructs defined in SBML Level&nbsp;3 Core.  A
178 * 'required' value of <code>true</code> indicates that the package may do so.  The
179 * value of the attribute is set by the Level&nbsp;3 package specification,
180 * and does <em>not</em> depend on the actual presence or absence of particular
181 * package constructs in a given SBML document: in other words, if the
182 * package specification defines any construct that can change the model's
183 * meaning, the value of the 'required' attribute must always be set to 
184 * <code>true</code> in any SBML document that uses the package.
185 <p>
186 * The XML namespace declaration for an SBML Level&nbsp;3 package is an
187 * indication that a model makes use of features defined by that package,
188 * while the 'required' attribute indicates whether the features may be
189 * ignored without compromising the mathematical meaning of the model.  Both
190 * are necessary for a complete reference to an SBML Level&nbsp;3 package.
191   <p>
192   * @param value the value to be assigned to the 'required' attribute.
193   * The 'required' attribute takes a Boolean value, either <code>true</code> or
194   * <code>false.</code>
195   <p>
196   * <p>
197 * @return integer value indicating success/failure of the
198 * function.   The possible values
199 * returned by this function are:
200   * <ul>
201   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
202   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
203   *
204   * </ul> <p>
205   * @see #getRequired()
206   * @see #isSetRequired()
207   * @see #unsetRequired()
208   */ public
209 int setRequired(boolean value) {
210    return libsbmlJNI.SBMLDocumentPlugin_setRequired(swigCPtr, this, value);
211  }
212
213  
214/**
215   * Returns the value of the 'required' attribute.
216   <p>
217   * <p>
218 * SBML Level&nbsp;3 requires that every package defines an attribute named
219 * 'required' on the root <code>&lt;sbml&gt;</code> element in an SBML file
220 * or data stream.  The attribute, being in the namespace of the Level&nbsp;3
221 * package in question, must be prefixed by the XML namespace prefix
222 * associated with the package.  The value of the 'required' attribute
223 * indicates whether constructs in that package may change the mathematical
224 * interpretation of constructs defined in SBML Level&nbsp;3 Core.  A
225 * 'required' value of <code>true</code> indicates that the package may do so.  The
226 * value of the attribute is set by the Level&nbsp;3 package specification,
227 * and does <em>not</em> depend on the actual presence or absence of particular
228 * package constructs in a given SBML document: in other words, if the
229 * package specification defines any construct that can change the model's
230 * meaning, the value of the 'required' attribute must always be set to 
231 * <code>true</code> in any SBML document that uses the package.
232 <p>
233 * The XML namespace declaration for an SBML Level&nbsp;3 package is an
234 * indication that a model makes use of features defined by that package,
235 * while the 'required' attribute indicates whether the features may be
236 * ignored without compromising the mathematical meaning of the model.  Both
237 * are necessary for a complete reference to an SBML Level&nbsp;3 package.
238   <p>
239   * @return the boolean value of 'required' attribute for the SBML package.
240   <p>
241   * @see #setRequired(boolean value)
242   * @see #isSetRequired()
243   * @see #unsetRequired()
244   */ public
245 boolean getRequired() {
246    return libsbmlJNI.SBMLDocumentPlugin_getRequired(swigCPtr, this);
247  }
248
249  
250/**
251   * Returns the value of the 'required' attribute.
252   <p>
253   * <p>
254 * SBML Level&nbsp;3 requires that every package defines an attribute named
255 * 'required' on the root <code>&lt;sbml&gt;</code> element in an SBML file
256 * or data stream.  The attribute, being in the namespace of the Level&nbsp;3
257 * package in question, must be prefixed by the XML namespace prefix
258 * associated with the package.  The value of the 'required' attribute
259 * indicates whether constructs in that package may change the mathematical
260 * interpretation of constructs defined in SBML Level&nbsp;3 Core.  A
261 * 'required' value of <code>true</code> indicates that the package may do so.  The
262 * value of the attribute is set by the Level&nbsp;3 package specification,
263 * and does <em>not</em> depend on the actual presence or absence of particular
264 * package constructs in a given SBML document: in other words, if the
265 * package specification defines any construct that can change the model's
266 * meaning, the value of the 'required' attribute must always be set to 
267 * <code>true</code> in any SBML document that uses the package.
268 <p>
269 * The XML namespace declaration for an SBML Level&nbsp;3 package is an
270 * indication that a model makes use of features defined by that package,
271 * while the 'required' attribute indicates whether the features may be
272 * ignored without compromising the mathematical meaning of the model.  Both
273 * are necessary for a complete reference to an SBML Level&nbsp;3 package.
274   <p>
275   * @return <code>true</code> if the 'required' attribute of this {@link SBMLDocument}
276   * has been set to <code>true</code>, <code>false</code> otherwise.
277   */ public
278 boolean isSetRequired() {
279    return libsbmlJNI.SBMLDocumentPlugin_isSetRequired(swigCPtr, this);
280  }
281
282  
283/**
284   * Unsets the value of the 'required' attribute of this {@link SBMLDocumentPlugin}.
285   <p>
286   * <p>
287 * @return integer value indicating success/failure of the
288 * function.   The possible values
289 * returned by this function are:
290   * <ul>
291   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
292   * </ul>
293   */ public
294 int unsetRequired() {
295    return libsbmlJNI.SBMLDocumentPlugin_unsetRequired(swigCPtr, this);
296  }
297
298  
299/** * @internal */ public
300 boolean isCompFlatteningImplemented() {
301    return libsbmlJNI.SBMLDocumentPlugin_isCompFlatteningImplemented(swigCPtr, this);
302  }
303
304  
305/** * @internal */ public
306 long checkConsistency() {
307    return libsbmlJNI.SBMLDocumentPlugin_checkConsistency(swigCPtr, this);
308  }
309
310}