001 package org.sbml.libsbml;
002
003 /**
004 * Class for managing lists of {@link CVTerm} objects.
005 * <p>
006 * <em style='color: #555'>
007 * This class of objects is defined by libSBML only and has no direct
008 * equivalent in terms of SBML components.
009 * </em>
010 * <p>
011 * This class is necessary because of programming language differences
012 * between Java and the underlying C++ core of libSBML's implementation.
013 * It would of course be preferable to have a common list type for all
014 * lists returned by libSBML (e.g., lists of {@link CVTerm} objects, lists
015 * of {@link CVTerm} objects, etc.). However, this is currently impossible
016 * to achieve given the way the underlying C++ lists are implemented. (The
017 * basic problem concerns the lack of an equivalent to <code>void *</code>
018 * pointers in Java.)
019 * <p>
020 * As a result of this incompatibility, libSBML must implement the Java
021 * versions of the lists in another way. The approach taken is to
022 * define specialized list types for each kind of object that needs
023 * a list; that is, {@link CVTermList} for {@link CVTerm} objects,
024 * {@link CVTermList} for {@link CVTerm} objects, and a few others.
025 * These list objects provide the same kind of functionality that
026 * the underlying C++ generic lists provide (such as <code>get()</code>,
027 * <code>add()</code>, <code>remove()</code>, etc.), yet still
028 * maintain the strong data typing requiring by Java.
029 * <p>
030 * @warning An important consideration in the use of this list is
031 * that the <strong>caller owns the underlying C++ memory for the
032 * list</strong>. It must be explicitly deleted using
033 * {@link #delete()} after the caller no longer needs it.
034 * <p>
035 * @see SBase#getCVTerms()
036 */
037 public class CVTermList {
038
039 /**
040 * Explicit constructor for this list.
041 * <p>
042 * In most circumstances, callers will obtain an {@link CVTermList}
043 * object from a call to a libSBML method that returns the list.
044 * However, the constructor is provided in case callers need to
045 * construct the lists themselves.
046 * <p>
047 * @warning Note that the internal implementation of the list nodes uses
048 * C++ objects. If callers use this constructor to create the list
049 * object deliberately, those objects are in a sense "owned" by the caller
050 * when this constructor is used. Callers need to remember to call
051 * {@link #delete()} on this list object after it is no longer
052 * needed or risk leaking memory.
053 */
054 public CVTermList() { }
055
056
057 /**
058 * Destructor for this list.
059 * <p>
060 * If a caller created this list using the {@link #CVTermList()}
061 * constructor, the caller should use this method to delete this list
062 * object after it is no longer in use.
063 */
064 public synchronized void delete() { }
065
066
067 /**
068 * Adds the given {@link CVTerm} object <code>item</code> to this
069 * list.
070 * <p>
071 * @param item the {@link CVTerm} object to add to add
072 */
073 public void add(CVTerm item) { }
074
075
076 /**
077 * Returns the <em>n</em>th CVTerm object from this list.
078 * <p>
079 * If the index number <code>n</code> is greater than the size of the list
080 * (as indicated by {@link #getSize()}), then this method returns
081 * <code>null</code>.
082 * <p>
083 * @param n the index number of the item to get, with indexing
084 * beginning at number <code>0</code>.
085 * <p>
086 * @return the nth item in this {@link CVTermList} items.
087 * <p>
088 * @see #getSize()
089 */
090 public CVTerm get(long n) { }
091
092
093 /**
094 * Adds the {@link CVTerm} object <code>item</code> to the beginning
095 * of this list.
096 * <p>
097 * @param item a pointer to the item to be prepended.
098 * <p>
099 */
100 public void prepend(CVTerm item) { }
101
102
103 /**
104 * Removes the <em>n</em>th {@link CVTerm} object from this list and
105 * returns it.
106 * <p>
107 * Callers can use {@link #getSize()} to find out the length of the list.
108 * If <code>n > </code>{@link #getSize()}, this method returns
109 * <code>null</code> and does not delete anything.
110 * <p>
111 * @param n the index number of the item to remove
112 * <p>
113 * @return the item indexed by <code>n</code>
114 * </p>
115 * @see #getSize()
116 */
117 public CVTerm remove(long n) { }
118
119
120 /**
121 * Returns the number of items in this list.
122 * <p>
123 * @return the number of elements in this list.
124 */
125 public long getSize() { }
126
127 }