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 * Implementation of SBML's Constraint construct.
014 * <p>
015 * The {@link Constraint} object class was introduced in SBML Level&nbsp;2
016 * Version&nbsp;2 as a mechanism for stating the assumptions under which a
017 * model is designed to operate.  The <em>constraints</em> are statements
018 * about permissible values of different quantities in a model.
019 * Constraints are not used to compute dynamical values for simulation or
020 * analysis, but rather, they serve an advisory role for
021 * simulation/analysis tools.
022 * <p>
023 * SBML's {@link Constraint} object class has one required attribute, 'id', to
024 * give the parameter a unique identifier by which other parts of an SBML
025 * model definition can refer to it.  A {@link Constraint} object can also have an
026 * optional 'name' attribute of type <code>string.</code>  Identifiers and names must
027 * be used according to the guidelines described in the SBML specification
028 * (e.g., Section 3.3 in the Level&nbsp;2 Version 4 specification).  
029 * <p>
030 * {@link Constraint} has one required subelement, 'math', containing a MathML
031 * formula defining the condition of the constraint.  This formula must
032 * return a boolean value of <code>true</code> when the model is a <em>valid</em>
033 * state.  The formula can be an arbitrary expression referencing the
034 * variables and other entities in an SBML model.  The evaluation of 'math'
035 * and behavior of constraints are described in more detail below.
036 * <p>
037 * A {@link Constraint} structure also has an optional subelement called 'message'.
038 * This can contain a message in XHTML format that may be displayed to the
039 * user when the condition of the formula in the 'math' subelement
040 * evaluates to a value of <code>false.</code>  Software tools are not required to
041 * display the message, but it is recommended that they do so as a matter
042 * of best practice.  The XHTML content within a 'message' subelement must
043 * follow the same restrictions as for the 'notes' element on {@link SBase}
044 * described in in the SBML Level&nbsp;2 specification; please consult the
045 * <a target='_blank' href='http://sbml.org/Documents/Specifications'>SBML
046 * specification document</a> corresponding to the SBML Level and Version
047 * of your model for more information about the requirements for 'notes'
048 * content.
049 * <p>
050 * {@link Constraint} was introduced in SBML Level&nbsp;2 Version&nbsp;2.  It is
051 * not available in earlier versions of Level&nbsp;2 nor in any version of
052 * Level&nbsp;1.
053 * <p>
054 * <h2>Semantics of Constraints</h2>
055 * <p>
056 * In the context of a simulation, a {@link Constraint} has effect at all times
057 * <em>t &#8805; 0</em>.  Each {@link Constraint}'s 'math' subelement is first
058 * evaluated after any {@link InitialAssignment} definitions in a model at <em>t =
059 * 0</em> and can conceivably trigger at that point.  (In other words, a
060 * simulation could fail a constraint immediately.)
061 * <p>
062 * {@link Constraint} structures <em>cannot and should not</em> be used to compute
063 * the dynamical behavior of a model as part of, for example, simulation.
064 * Constraints may be used as input to non-dynamical analysis, for instance
065 * by expressing flux constraints for flux balance analysis.
066 * <p>
067 * The results of a simulation of a model containing a constraint are
068 * invalid from any simulation time at and after a point when the function
069 * given by the 'math' subelement returns a value of <code>false.</code>  Invalid
070 * simulation results do not make a prediction of the behavior of the
071 * biochemical reaction network represented by the model.  The precise
072 * behavior of simulation tools is left undefined with respect to
073 * constraints.  If invalid results are detected with respect to a given
074 * constraint, the 'message' subelement may optionally be displayed to the
075 * user.  The simulation tool may also halt the simulation or clearly
076 * delimit in output data the simulation time point at which the simulation
077 * results become invalid.
078 * <p>
079 * SBML does not impose restrictions on duplicate {@link Constraint} definitions or
080 * the order of evaluation of {@link Constraint} objects in a model.  It is
081 * possible for a model to define multiple constraints all with the same
082 * mathematical expression.  Since the failure of any constraint indicates
083 * that the model simulation has entered an invalid state, a system is not
084 * required to attempt to detect whether other constraints in the model
085 * have failed once any one constraint has failed.
086 * <p>
087 * <!---------------------------------------------------------------------- -->
088 * <p>
089 */
090
091public class Constraint extends SBase {
092   private long swigCPtr;
093
094   protected Constraint(long cPtr, boolean cMemoryOwn)
095   {
096     super(libsbmlJNI.Constraint_SWIGUpcast(cPtr), cMemoryOwn);
097     swigCPtr = cPtr;
098   }
099
100   protected static long getCPtr(Constraint obj)
101   {
102     return (obj == null) ? 0 : obj.swigCPtr;
103   }
104
105   protected static long getCPtrAndDisown (Constraint obj)
106   {
107     long ptr = 0;
108
109     if (obj != null)
110     {
111       ptr             = obj.swigCPtr;
112       obj.swigCMemOwn = false;
113     }
114
115     return ptr;
116   }
117
118  protected void finalize() {
119    delete();
120  }
121
122  public synchronized void delete() {
123    if (swigCPtr != 0) {
124      if (swigCMemOwn) {
125        swigCMemOwn = false;
126        libsbmlJNI.delete_Constraint(swigCPtr);
127      }
128      swigCPtr = 0;
129    }
130    super.delete();
131  }
132
133  
134/**
135   * Creates a new {@link Constraint} using the given SBML <code>level</code> and <code>version</code>
136   * values.
137   * <p>
138   * @param level a long integer, the SBML Level to assign to this {@link Constraint}
139   * <p>
140   * @param version a long integer, the SBML Version to assign to this
141   * {@link Constraint}
142   * <p>
143   * @throws SBMLConstructorException 
144   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
145   * of SBML object, are either invalid or mismatched with respect to the
146   * parent {@link SBMLDocument} object.
147   * <p>
148   * @note Upon the addition of a {@link Constraint} object to an {@link SBMLDocument}
149   * (e.g., using {@link Model#addConstraint(Constraint c)}), the
150   * SBML Level, SBML Version and XML namespace of the document 
151   * <em>override</em> the values used when creating the {@link Constraint} object via this
152   * constructor.  This is necessary to ensure that an SBML document is a
153   * consistent structure.  Nevertheless, the ability to supply the values
154   * at the time of creation of a {@link Constraint} is an important aid to
155   * producing valid SBML.  Knowledge of the intented SBML Level and
156   * Version determine whether it is valid to assign a particular value to
157   * an attribute, or whether it is valid to add an object to an existing
158   * {@link SBMLDocument}.
159   */ public
160 Constraint(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
161    this(libsbmlJNI.new_Constraint__SWIG_0(level, version), true);
162  }
163
164  
165/**
166   * Creates a new {@link Constraint} using the given {@link SBMLNamespaces} object
167   * <code>sbmlns</code>.
168   * <p>
169   * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
170   * information.  It is used to communicate the SBML Level, Version, and
171   * (in Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.
172   * A common approach to using this class constructor is to create an
173   * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to
174   * object constructors such as this one when needed.
175   * <p>
176   * @param sbmlns an {@link SBMLNamespaces} object.
177   * <p>
178   * @throws SBMLConstructorException 
179   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
180   * of SBML object, are either invalid or mismatched with respect to the
181   * parent {@link SBMLDocument} object.
182   * <p>
183   * @note Upon the addition of a {@link Constraint} object to an {@link SBMLDocument}
184   * (e.g., using {@link Model#addConstraint(Constraint c)}), the
185   * SBML XML namespace of the document <em>overrides</em> the value used when
186   * creating the {@link Constraint} object via this constructor.  This is
187   * necessary to ensure that an SBML document is a consistent structure.
188   * Nevertheless, the ability to supply the values at the time of creation
189   * of a {@link Constraint} is an important aid to producing valid SBML.
190   * Knowledge of the intented SBML Level and Version determine whether it
191   * is valid to assign a particular value to an attribute, or whether it
192   * is valid to add an object to an existing {@link SBMLDocument}.
193   */ public
194 Constraint(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
195    this(libsbmlJNI.new_Constraint__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
196  }
197
198  
199/**
200   * Copy constructor; creates a copy of this {@link Constraint}.
201   * <p>
202   * @param orig the object to copy.
203   * <p>
204   * @throws SBMLConstructorException 
205   * Thrown if the argument <code>orig</code> is <code>null.</code>
206   */ public
207 Constraint(Constraint orig) throws org.sbml.libsbml.SBMLConstructorException {
208    this(libsbmlJNI.new_Constraint__SWIG_2(Constraint.getCPtr(orig), orig), true);
209  }
210
211  
212/**
213   * Creates and returns a deep copy of this {@link Constraint}.
214   * <p>
215   * @return a (deep) copy of this {@link Constraint}.
216   */ public
217 Constraint cloneObject() {
218    long cPtr = libsbmlJNI.Constraint_cloneObject(swigCPtr, this);
219    return (cPtr == 0) ? null : new Constraint(cPtr, true);
220  }
221
222  
223/**
224   * Get the message, if any, associated with this {@link Constraint}
225   * <p>
226   * @return the message for this {@link Constraint}, as an {@link XMLNode}.
227   */ public
228 XMLNode getMessage() {
229    long cPtr = libsbmlJNI.Constraint_getMessage(swigCPtr, this);
230    return (cPtr == 0) ? null : new XMLNode(cPtr, false);
231  }
232
233  
234/**
235   * Get the message string, if any, associated with this {@link Constraint}
236   * <p>
237   * @return the message for this {@link Constraint}, as a string.
238   */ public
239 String getMessageString() {
240    return libsbmlJNI.Constraint_getMessageString(swigCPtr, this);
241  }
242
243  
244/**
245   * Get the mathematical expression of this {@link Constraint}
246   * <p>
247   * @return the math for this {@link Constraint}, as an {@link ASTNode}.
248   */ public
249 ASTNode getMath() {
250    long cPtr = libsbmlJNI.Constraint_getMath(swigCPtr, this);
251    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
252  }
253
254  
255/**
256   * Predicate returning <code>true</code> if a
257   * message is defined for this {@link Constraint}.
258   * <p>
259   * @return <code>true</code> if the message of this {@link Constraint} is set,
260   * <code>false</code> otherwise.
261   */ public
262 boolean isSetMessage() {
263    return libsbmlJNI.Constraint_isSetMessage(swigCPtr, this);
264  }
265
266  
267/**
268   * Predicate returning <code>true</code> if a
269   * mathematical formula is defined for this {@link Constraint}.
270   * <p>
271   * @return <code>true</code> if the 'math' subelement for this {@link Constraint} is
272   * set, <code>false</code> otherwise.
273   */ public
274 boolean isSetMath() {
275    return libsbmlJNI.Constraint_isSetMath(swigCPtr, this);
276  }
277
278  
279/**
280   * Sets the message of this {@link Constraint}.
281   * <p>
282   * The {@link XMLNode} tree passed in <code>xhtml</code> is copied.
283   * <p>
284   * @param xhtml an XML tree containing XHTML content.
285   * <p>
286   * @return integer value indicating success/failure of the
287   * function.   The possible values
288   * returned by this function are:
289   * <ul>
290   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
291   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
292   * </ul>
293   */ public
294 int setMessage(XMLNode xhtml) {
295    return libsbmlJNI.Constraint_setMessage(swigCPtr, this, XMLNode.getCPtr(xhtml), xhtml);
296  }
297
298  
299/**
300   * Sets the mathematical expression of this {@link Constraint} to a copy of the
301   * AST given as <code>math</code>.
302   * <p>
303   * @param math an {@link ASTNode} expression to be assigned as the 'math'
304   * subelement of this {@link Constraint}
305   * <p>
306   * @return integer value indicating success/failure of the
307   * function.   The possible values
308   * returned by this function are:
309   * <ul>
310   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
311   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
312   * </ul>
313   */ public
314 int setMath(ASTNode math) {
315    return libsbmlJNI.Constraint_setMath(swigCPtr, this, ASTNode.getCPtr(math), math);
316  }
317
318  
319/**
320   * Unsets the 'message' subelement of this {@link Constraint}.
321   * <p>
322   * @return integer value indicating success/failure of the
323   * function.   The possible values
324   * returned by this function are:
325   * <ul>
326   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
327   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
328   * </ul>
329   */ public
330 int unsetMessage() {
331    return libsbmlJNI.Constraint_unsetMessage(swigCPtr, this);
332  }
333
334  
335/**
336   * Renames all the SIdRef attributes on this element, including any found in MathML
337   */ public
338 void renameSIdRefs(String oldid, String newid) {
339    libsbmlJNI.Constraint_renameSIdRefs(swigCPtr, this, oldid, newid);
340  }
341
342  
343/**
344   * Renames all the UnitSIdRef attributes on this element
345   */ public
346 void renameUnitSIdRefs(String oldid, String newid) {
347    libsbmlJNI.Constraint_renameUnitSIdRefs(swigCPtr, this, oldid, newid);
348  }
349
350  
351/**
352   * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 
353   * <p>
354   * @internal
355   */ public
356 void replaceSIDWithFunction(String id, ASTNode function) {
357    libsbmlJNI.Constraint_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
358  }
359
360  
361/**
362   * Returns the libSBML type code for this SBML object.
363   * <p>
364   * LibSBML attaches an identifying code to every
365   * kind of SBML object.  These are known as <em>SBML type codes</em>.  In
366   * other languages, the set of type codes is stored in an enumeration; in
367   * the Java language interface for libSBML, the type codes are defined as
368   * static integer constants in the interface class {@link
369   * libsbmlConstants}.  The names of the type codes all begin with the
370   * characters <code>SBML_.</code> 
371   * <p>
372   * @return the SBML type code for this object, or {@link  libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default).
373   * <p>
374   * @see #getElementName()
375   */ public
376 int getTypeCode() {
377    return libsbmlJNI.Constraint_getTypeCode(swigCPtr, this);
378  }
379
380  
381/**
382   * Returns the XML element name of this object, which for {@link Constraint}, is
383   * always <code>'constraint'.</code>
384   * <p>
385   * @return the name of this element, i.e., <code>'constraint'.</code>
386   */ public
387 String getElementName() {
388    return libsbmlJNI.Constraint_getElementName(swigCPtr, this);
389  }
390
391  
392/**
393   * Predicate returning <code>true</code> if
394   * all the required elements for this {@link Constraint} object
395   * have been set.
396   * <p>
397   * @note The required elements for a {@link Constraint} object are:
398   * <ul>
399   * <li> 'math'
400   * </ul>
401   * <p>
402   * @return a boolean value indicating whether all the required
403   * elements for this object have been defined.
404   */ public
405 boolean hasRequiredElements() {
406    return libsbmlJNI.Constraint_hasRequiredElements(swigCPtr, this);
407  }
408
409}