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