001: package org.garret.perst;
002:
003: import java.util.*;
004:
005: /**
006: * Interface for one-to-many relation. There are two types of relations:
007: * embedded (when references to the relarted obejcts are stored in relation
008: * owner obejct itself) and stanalone (when relation is separate object, which contains
009: * the reference to the relation owner and relation members). Both kinds of relations
010: * implements Link interface. Embedded relation is created by Storage.createLink method
011: * and standalone relation is represented by Relation persistent class created by
012: * Storage.createRelation method.
013: */
014: public interface Link<T extends IPersistent> extends ITable<T>,
015: List<T>, RandomAccess {
016: /**
017: * Get number of the linked objects
018: * @return the number of related objects
019: */
020: public int size();
021:
022: /**
023: * Set number of the linked objects
024: * @param newSize new number of linked objects (if it is greater than original number,
025: * than extra elements will be set to null)
026: */
027: public void setSize(int newSize);
028:
029: /**
030: * Returns <tt>true</tt> if there are no related object
031: *
032: * @return <tt>true</tt> if there are no related object
033: */
034: boolean isEmpty();
035:
036: /**
037: * Get related object by index
038: * @param i index of the object in the relation
039: * @return referenced object
040: */
041: public T get(int i);
042:
043: /**
044: * Get related object by index without loading it.
045: * Returned object can be used only to get it OID or to compare with other objects using
046: * <code>equals</code> method
047: * @param i index of the object in the relation
048: * @return stub representing referenced object
049: */
050: public IPersistent getRaw(int i);
051:
052: /**
053: * Replace i-th element of the relation
054: * @param i index in the relartion
055: * @param obj object to be included in the relation
056: * @return the element previously at the specified position.
057: */
058: public T set(int i, T obj);
059:
060: /**
061: * Assign value to i-th element of the relation.
062: * Unlike Link.set methos this method doesn't return previous value of the element
063: * and so is faster if previous element value is not needed (it has not to be fetched from the database)
064: * @param i index in the relartion
065: * @param obj object to be included in the relation
066: */
067: public void setObject(int i, T obj);
068:
069: /**
070: * Remove object with specified index from the relation
071: * Unlike Link.remove methos this method doesn't return removed element and so is faster
072: * if it is not needed (it has not to be fetched from the database)
073: * @param i index in the relartion
074: */
075: public void removeObject(int i);
076:
077: /**
078: * Remove object from the relation
079: * @param o removed object
080: * @return <code>true</code> if relation is changed as the result of this operation
081: */
082: public boolean remove(Object o);
083:
084: /**
085: * Insert new object in the relation
086: * @param i insert poistion, should be in [0,size()]
087: * @param obj object inserted in the relation
088: */
089: public void insert(int i, T obj);
090:
091: /**
092: * Add new object to the relation
093: * @param obj object inserted in the relation
094: */
095: public boolean add(T obj);
096:
097: /**
098: * Add all elements of the array to the relation
099: * @param arr array of obects which should be added to the relation
100: */
101: public void addAll(T[] arr);
102:
103: /**
104: * Add specified elements of the array to the relation
105: * @param arr array of obects which should be added to the relation
106: * @param from index of the first element in the array to be added to the relation
107: * @param length number of elements in the array to be added in the relation
108: */
109: public void addAll(T[] arr, int from, int length);
110:
111: /**
112: * Add all object members of the other relation to this relation
113: * @param link another relation
114: */
115: public boolean addAll(Link<T> link);
116:
117: /**
118: * Return array with relation members. Members are not loaded and
119: * size of the array can be greater than actual number of members.
120: * @return array of object with relation members used in implementation of Link class
121: */
122: public IPersistent[] toRawArray();
123:
124: /**
125: * Get relation members as array of object
126: * @return array of object with relation members
127: */
128: public IPersistent[] toPersistentArray();
129:
130: /**
131: * Get all relation members as array.
132: * The runtime type of the returned array is that of the specified array.
133: * If the index fits in the specified array, it is returned therein.
134: * Otherwise, a new array is allocated with the runtime type of the
135: * specified array and the size of this index.<p>
136: *
137: * If this index fits in the specified array with room to spare
138: * (i.e., the array has more elements than this index), the element
139: * in the array immediately following the end of the index is set to
140: * <tt>null</tt>. This is useful in determining the length of this
141: * index <i>only</i> if the caller knows that this index does
142: * not contain any <tt>null</tt> elements.)<p>
143: * @return array of object with relation members
144: */
145: public <T> T[] toArray(T[] arr);
146:
147: /**
148: * Checks if relation contains specified object instance
149: * @param obj specified object
150: * @return <code>true</code> if object is present in the collection, <code>false</code> otherwise
151: */
152: public boolean containsObject(T obj);
153:
154: /**
155: * Check if there is linked object which is equal to the specified object.
156: * More formally, returns <tt>true</tt> if and only if this
157: * collection contains at least one element <tt>e</tt> such that
158: * <tt>(obj==null ? e==null : obj.equals(e))</tt>.<p>
159: * @param obj object to be searched in the index. Object should contain indexed field.
160: * @return <code>true</code> if collection contains object equals to the specified
161: */
162: public boolean contains(Object obj);
163:
164: /**
165: * Check if i-th element of Link is the same as specified obj
166: * @param i element index
167: * @param obj object to compare with
168: * @return <code>true</code> if i-th element of Link reference the same object as "obj"
169: */
170: public boolean containsElement(int i, T obj);
171:
172: /**
173: * Get index of the specified object instance in the relation.
174: * This method use comparison by object identity (instead of equals() method) and
175: * is significantly faster than List.indexOf() method
176: * @param obj specified object instance
177: * @return zero based index of the object or -1 if object is not in the relation
178: */
179: public int indexOfObject(Object obj);
180:
181: /**
182: * Get index of the specified object instance in the relation
183: * This method use comparison by object identity (instead of equals() method) and
184: * is significantly faster than List.indexOf() method
185: * @param obj specified object instance
186: * @return zero based index of the object or -1 if object is not in the relation
187: */
188: public int lastIndexOfObject(Object obj);
189:
190: /**
191: * Remove all members from the relation
192: */
193: public void clear();
194:
195: /**
196: * Get iterator through link members
197: * This iterator supports remove() method.
198: * @return iterator through linked objects
199: */
200: public Iterator<T> iterator();
201:
202: /**
203: * Replace all direct references to linked objects with stubs.
204: * This method is needed tyo avoid memory exhaustion in case when
205: * there is a large numebr of objectys in databasse, mutually
206: * refefencing each other (each object can directly or indirectly
207: * be accessed from other objects).
208: */
209: public void unpin();
210:
211: /**
212: * Replace references to elements with direct references.
213: * It will impove spped of manipulations with links, but it can cause
214: * recursive loading in memory large number of objects and as a result - memory
215: * overflow, because garbage collector will not be able to collect them
216: */
217: public void pin();
218: }
|