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 MIRIAM-compliant model history data.
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 SBML specification beginning with Level&nbsp;2 Version&nbsp;2 defines
023 * a standard approach to recording optional model history and model creator
024 * information in a form that complies with MIRIAM (<a target='_blank'
025 * href='http://www.nature.com/nbt/journal/v23/n12/abs/nbt1156.html'>'Minimum
026 * Information Requested in the Annotation of biochemical Models'</a>,
027 * <i>Nature Biotechnology</i>, vol. 23, no. 12, Dec. 2005).  LibSBML
028 * provides the {@link ModelHistory} class as a convenient high-level interface for
029 * working with model history data.
030 <p>
031 * {@link Model} histories in SBML consist of one or more <em>model creators</em>,
032 * a single date of <em>creation</em>, and one or more <em>modification</em> dates.
033 * The overall XML form of this data takes the following form:
034 <p>
035 <pre class='fragment'>
036 &lt;dc:creator&gt;
037   &lt;rdf:Bag&gt;
038     &lt;rdf:li rdf:parseType='Resource'&gt;
039       <span style='background-color: #d0eed0'>+++</span>
040       &lt;vCard:N rdf:parseType='Resource'&gt;
041         &lt;vCard:Family&gt;<span style='background-color: #bbb'>family name</span>&lt;/vCard:Family&gt;
042         &lt;vCard:Given&gt;<span style='background-color: #bbb'>given name</span>&lt;/vCard:Given&gt;
043       &lt;/vCard:N&gt;
044       <span style='background-color: #d0eed0'>+++</span>
045       <span style='border-bottom: 2px dotted #888'>&lt;vCard:EMAIL&gt;<span style='background-color: #bbb'>email address</span>&lt;/vCard:EMAIL&gt;</span>
046       <span style='background-color: #d0eed0'>+++</span>
047       <span style='border-bottom: 2px dotted #888'>&lt;vCard:ORG rdf:parseType='Resource'&gt;</span>
048        <span style='border-bottom: 2px dotted #888'>&lt;vCard:Orgname&gt;<span style='background-color: #bbb'>organization name</span>&lt;/vCard:Orgname&gt;</span>
049       <span style='border-bottom: 2px dotted #888'>&lt;/vCard:ORG&gt;</span>
050       <span style='background-color: #d0eed0'>+++</span>
051     &lt;/rdf:li&gt;
052     <span style='background-color: #edd'>...</span>
053   &lt;/rdf:Bag&gt;
054 &lt;/dc:creator&gt;
055 &lt;dcterms:created rdf:parseType='Resource'&gt;
056   &lt;dcterms:W3CDTF&gt;<span style='background-color: #bbb'>creation date</span>&lt;/dcterms:W3CDTF&gt;
057 &lt;/dcterms:created&gt;
058 &lt;dcterms:modified rdf:parseType='Resource'&gt;
059   &lt;dcterms:W3CDTF&gt;<span style='background-color: #bbb'>modification date</span>&lt;/dcterms:W3CDTF&gt;
060 &lt;/dcterms:modified&gt;
061 <span style='background-color: #edd'>...</span>
062 </pre>
063 <p>
064 * In the template above, the <span style='border-bottom: 2px dotted #888'>underlined</span>
065 * portions are optional, the symbol
066 * <span class='code' style='background-color: #d0eed0'>+++</span> is a placeholder
067 * for either no content or valid XML content that is not defined by
068 * the annotation scheme, and the ellipses
069 * <span class='code' style='background-color: #edd'>...</span>
070 * are placeholders for zero or more elements of the same form as the
071 * immediately preceding element.  The various placeholders for content, namely
072 * <span class='code' style='background-color: #bbb'>family name</span>,
073 * <span class='code' style='background-color: #bbb'>given name</span>,
074 * <span class='code' style='background-color: #bbb'>email address</span>,
075 * <span class='code' style='background-color: #bbb'>organization</span>,
076 * <span class='code' style='background-color: #bbb'>creation date</span>, and
077 * <span class='code' style='background-color: #bbb'>modification date</span>
078 * are data that can be filled in using the various methods on
079 * the {@link ModelHistory} class described below.
080 <p>
081 * @see ModelCreator
082 * @see Date
083 */
084
085public class ModelHistory {
086   private long swigCPtr;
087   protected boolean swigCMemOwn;
088
089   protected ModelHistory(long cPtr, boolean cMemoryOwn)
090   {
091     swigCMemOwn = cMemoryOwn;
092     swigCPtr    = cPtr;
093   }
094
095   protected static long getCPtr(ModelHistory obj)
096   {
097     return (obj == null) ? 0 : obj.swigCPtr;
098   }
099
100   protected static long getCPtrAndDisown (ModelHistory obj)
101   {
102     long ptr = 0;
103
104     if (obj != null)
105     {
106       ptr             = obj.swigCPtr;
107       obj.swigCMemOwn = false;
108     }
109
110     return ptr;
111   }
112
113  protected void finalize() {
114    delete();
115  }
116
117  public synchronized void delete() {
118    if (swigCPtr != 0) {
119      if (swigCMemOwn) {
120        swigCMemOwn = false;
121        libsbmlJNI.delete_ModelHistory(swigCPtr);
122      }
123      swigCPtr = 0;
124    }
125  }
126
127  /**
128   * Equality comparison method for ModelHistory.
129   * <p>
130   * Because the Java methods for libSBML are actually wrappers around code
131   * implemented in C++ and C, certain operations will not behave as
132   * expected.  Equality comparison is one such case.  An instance of a
133   * libSBML object class is actually a <em>proxy object</em>
134   * wrapping the real underlying C/C++ object.  The normal <code>==</code>
135   * equality operator in Java will <em>only compare the Java proxy objects</em>,
136   * not the underlying native object.  The result is almost never what you
137   * want in practical situations.  Unfortunately, Java does not provide a
138   * way to override <code>==</code>.
139   *  <p>
140   * The alternative that must be followed is to use the
141   * <code>equals()</code> method.  The <code>equals</code> method on this
142   * class overrides the default java.lang.Object one, and performs an
143   * intelligent comparison of instances of objects of this class.  The
144   * result is an assessment of whether two libSBML Java objects are truly 
145   * the same underlying native-code objects.
146   *  <p>
147   * The use of this method in practice is the same as the use of any other
148   * Java <code>equals</code> method.  For example,
149   * <em>a</em><code>.equals(</code><em>b</em><code>)</code> returns
150   * <code>true</code> if <em>a</em> and <em>b</em> are references to the
151   * same underlying object.
152   *
153   * @param sb a reference to an object to which the current object
154   * instance will be compared
155   *
156   * @return <code>true</code> if <code>sb</code> refers to the same underlying 
157   * native object as this one, <code>false</code> otherwise
158   */
159  public boolean equals(Object sb)
160  {
161    if ( this == sb ) 
162    {
163      return true;
164    }
165    return swigCPtr == getCPtr((ModelHistory)(sb));
166  }
167
168  /**
169   * Returns a hashcode for this ModelHistory object.
170   *
171   * @return a hash code usable by Java methods that need them.
172   */
173  public int hashCode()
174  {
175    return (int)(swigCPtr^(swigCPtr>>>32));
176  }
177
178  
179/**
180   * Creates a new {@link ModelHistory} object.
181   */ public
182 ModelHistory() {
183    this(libsbmlJNI.new_ModelHistory__SWIG_0(), true);
184  }
185
186  
187/**
188   * Copy constructor; creates a copy of this {@link ModelHistory} object.
189   <p>
190   * @param orig the object to copy.
191   <p>
192   * @throws SBMLConstructorException 
193   * Thrown if the argument <code>orig</code> is <code>null.</code>
194   */ public
195 ModelHistory(ModelHistory orig) {
196    this(libsbmlJNI.new_ModelHistory__SWIG_1(ModelHistory.getCPtr(orig), orig), true);
197  }
198
199  
200/**
201   * Creates and returns a copy of this {@link ModelHistory} object
202   <p>
203   * @return a (deep) copy of this {@link ModelHistory} object.
204   */ public
205 ModelHistory cloneObject() {
206    long cPtr = libsbmlJNI.ModelHistory_cloneObject(swigCPtr, this);
207    return (cPtr == 0) ? null : new ModelHistory(cPtr, true);
208  }
209
210  
211/**
212   * Returns the 'creation date' portion of this {@link ModelHistory} object.
213   <p>
214   * @return a {@link Date} object representing the creation date stored in
215   * this {@link ModelHistory} object.
216   */ public
217 Date getCreatedDate() {
218    long cPtr = libsbmlJNI.ModelHistory_getCreatedDate(swigCPtr, this);
219    return (cPtr == 0) ? null : new Date(cPtr, false);
220  }
221
222  
223/**
224   * Returns the 'modified date' portion of this {@link ModelHistory} object.
225   <p>
226   * Note that in the MIRIAM format for annotations, there can be multiple
227   * modification dates.  The libSBML {@link ModelHistory} class supports this by
228   * storing a list of 'modified date' values.  If this {@link ModelHistory} object
229   * contains more than one 'modified date' value in the list, this method
230   * will return the first one in the list.
231   <p>
232   * @return a {@link Date} object representing the date of modification
233   * stored in this {@link ModelHistory} object.
234   */ public
235 Date getModifiedDate() {
236    long cPtr = libsbmlJNI.ModelHistory_getModifiedDate__SWIG_0(swigCPtr, this);
237    return (cPtr == 0) ? null : new Date(cPtr, false);
238  }
239
240  
241/**
242   * Predicate returning <code>true</code> or <code>false</code> depending on whether this
243   * {@link ModelHistory}'s 'creation date' is set.
244   <p>
245   * @return <code>true</code> if the creation date value of this {@link ModelHistory} is
246   * set, <code>false</code> otherwise.
247   */ public
248 boolean isSetCreatedDate() {
249    return libsbmlJNI.ModelHistory_isSetCreatedDate(swigCPtr, this);
250  }
251
252  
253/**
254   * Predicate returning <code>true</code> or <code>false</code> depending on whether this
255   * {@link ModelHistory}'s 'modified date' is set.
256   <p>
257   * @return <code>true</code> if the modification date value of this {@link ModelHistory}
258   * object is set, <code>false</code> otherwise.
259   */ public
260 boolean isSetModifiedDate() {
261    return libsbmlJNI.ModelHistory_isSetModifiedDate(swigCPtr, this);
262  }
263
264  
265/**
266   * Sets the creation date of this {@link ModelHistory} object.
267   <p>
268   * @param date a {@link Date} object representing the date to which the 'created
269   * date' portion of this {@link ModelHistory} should be set.
270   <p>
271   * @return integer value indicating success/failure of the
272   * function.   The possible values
273   * returned by this function are:
274   * <ul>
275   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
276   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
277   * </ul>
278   */ public
279 int setCreatedDate(Date date) {
280    return libsbmlJNI.ModelHistory_setCreatedDate(swigCPtr, this, Date.getCPtr(date), date);
281  }
282
283  
284/**
285   * Sets the modification date of this {@link ModelHistory} object.
286   <p>
287   * @param date a {@link Date} object representing the date to which the 'modified
288   * date' portion of this {@link ModelHistory} should be set.
289   <p>
290   * @return integer value indicating success/failure of the
291   * function.   The possible values
292   * returned by this function are:
293   * <ul>
294   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
295   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
296   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
297   * </ul>
298   */ public
299 int setModifiedDate(Date date) {
300    return libsbmlJNI.ModelHistory_setModifiedDate(swigCPtr, this, Date.getCPtr(date), date);
301  }
302
303  
304/**
305   * Adds a copy of a {@link Date} object to the list of 'modified date' values
306   * stored in this {@link ModelHistory} object.
307   <p>
308   * In the MIRIAM format for annotations, there can be multiple
309   * modification dates.  The libSBML {@link ModelHistory} class supports this by
310   * storing a list of 'modified date' values.
311   <p>
312   * @param date a {@link Date} object representing the 'modified date' that should
313   * be added to this {@link ModelHistory} 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   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
322   * </ul>
323   */ public
324 int addModifiedDate(Date date) {
325    return libsbmlJNI.ModelHistory_addModifiedDate(swigCPtr, this, Date.getCPtr(date), date);
326  }
327
328  
329/**
330   * Returns the list of 'modified date' values (as {@link Date} objects) stored in
331   * this {@link ModelHistory} object.
332   <p>
333   * In the MIRIAM format for annotations, there can be multiple
334   * modification dates.  The libSBML {@link ModelHistory} class supports this by
335   * storing a list of 'modified date' values.
336   <p>
337   * @return the list of modification dates for this {@link ModelHistory} object.
338   */ public
339  DateList  getListModifiedDates() { 
340  long cPtr = libsbmlJNI.ModelHistory_getListModifiedDates(swigCPtr, this);
341  return (cPtr == 0) ? null : new  DateList(cPtr, true);
342}
343
344  
345/**
346   * Get the nth {@link Date} object in the list of 'modified date' values stored
347   * in this {@link ModelHistory} object.
348   <p>
349   * In the MIRIAM format for annotations, there can be multiple
350   * modification dates.  The libSBML {@link ModelHistory} class supports this by
351   * storing a list of 'modified date' values.
352   <p>
353   * @return the nth {@link Date} in the list of ModifiedDates of this
354   * {@link ModelHistory}.
355   */ public
356 Date getModifiedDate(long n) {
357    long cPtr = libsbmlJNI.ModelHistory_getModifiedDate__SWIG_1(swigCPtr, this, n);
358    return (cPtr == 0) ? null : new Date(cPtr, false);
359  }
360
361  
362/**
363   * Get the number of {@link Date} objects in this {@link ModelHistory} object's list of
364   * 'modified dates'.
365   <p>
366   * In the MIRIAM format for annotations, there can be multiple
367   * modification dates.  The libSBML {@link ModelHistory} class supports this by
368   * storing a list of 'modified date' values.
369   <p>
370   * @return the number of ModifiedDates in this {@link ModelHistory}.
371   */ public
372 long getNumModifiedDates() {
373    return libsbmlJNI.ModelHistory_getNumModifiedDates(swigCPtr, this);
374  }
375
376  
377/**
378   * Adds a copy of a {@link ModelCreator} object to the list of 'model creator'
379   * values stored in this {@link ModelHistory} object.
380   <p>
381   * In the MIRIAM format for annotations, there can be multiple model
382   * creators.  The libSBML {@link ModelHistory} class supports this by storing a
383   * list of 'model creator' values.
384   <p>
385   * @param mc the {@link ModelCreator} to add
386   <p>
387   * @return integer value indicating success/failure of the
388   * function.   The possible values
389   * returned by this function are:
390   * <ul>
391   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
392   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
393   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
394   * </ul>
395   */ public
396 int addCreator(ModelCreator mc) {
397    return libsbmlJNI.ModelHistory_addCreator(swigCPtr, this, ModelCreator.getCPtr(mc), mc);
398  }
399
400  
401/**
402   * Returns the list of {@link ModelCreator} objects stored in this {@link ModelHistory}
403   * object.
404   <p>
405   * In the MIRIAM format for annotations, there can be multiple model
406   * creators.  The libSBML {@link ModelHistory} class supports this by storing a
407   * list of 'model creator' values.
408   <p>
409   * @return the list of {@link ModelCreator} objects.
410   */ public
411  ModelCreatorList  getListCreators() { 
412  long cPtr = libsbmlJNI.ModelHistory_getListCreators(swigCPtr, this);
413  return (cPtr == 0) ? null : new  ModelCreatorList(cPtr, true);
414}
415
416  
417/**
418   * Get the nth {@link ModelCreator} object stored in this {@link ModelHistory} object.
419   <p>
420   * In the MIRIAM format for annotations, there can be multiple model
421   * creators.  The libSBML {@link ModelHistory} class supports this by storing a
422   * list of 'model creator' values.
423   <p>
424   * @return the nth {@link ModelCreator} object.
425   */ public
426 ModelCreator getCreator(long n) {
427    long cPtr = libsbmlJNI.ModelHistory_getCreator(swigCPtr, this, n);
428    return (cPtr == 0) ? null : new ModelCreator(cPtr, false);
429  }
430
431  
432/**
433   * Get the number of {@link ModelCreator} objects stored in this {@link ModelHistory}
434   * object.
435   <p>
436   * In the MIRIAM format for annotations, there can be multiple model
437   * creators.  The libSBML {@link ModelHistory} class supports this by storing a
438   * list of 'model creator' values.
439   <p>
440   * @return the number of ModelCreators objects.
441   */ public
442 long getNumCreators() {
443    return libsbmlJNI.ModelHistory_getNumCreators(swigCPtr, this);
444  }
445
446  
447/**
448   * Predicate returning <code>true</code> if all the required elements for this
449   * {@link ModelHistory} object have been set.
450   <p>
451   * The required elements for a {@link ModelHistory} object are 'created
452   * name', 'modified date', and at least one 'model creator'.
453   <p>
454   * @return a boolean value indicating whether all the required
455   * elements for this object have been defined.
456   */ public
457 boolean hasRequiredAttributes() {
458    return libsbmlJNI.ModelHistory_hasRequiredAttributes(swigCPtr, this);
459  }
460
461  
462/** * @internal */ public
463 boolean hasBeenModified() {
464    return libsbmlJNI.ModelHistory_hasBeenModified(swigCPtr, this);
465  }
466
467  
468/** * @internal */ public
469 void resetModifiedFlags() {
470    libsbmlJNI.ModelHistory_resetModifiedFlags(swigCPtr, this);
471  }
472
473}