001 //
002 // This file is generated by MetaBoss Ver 1.4.0001 at Thu Dec 15 22:36:21 EST 2005
003 // MetaBoss is Copyright 2000-2005 © Softaris Pty.Ltd. All Rights Reserved.
004 // Content of this file is Copyright 2000-2005 © Softaris Pty. Ltd. All Rights Reserved.
005 // This content is licensed under Open Source Gnu Public License (GPL)
006 // Full terms and conditions of GPL can be found found at www.gnu.org
007 //
008 package com.almamater.crs.domains.courses;
009
010 import com.metaboss.enterprise.bo.BOObjectCollection;
011 import com.metaboss.enterprise.bo.BOException;
012
013 /** Collection-like object, which provides access to the set of Student entities.
014 * Entity description is: <i>The person enrolled in the university to learn things</i>
015 * <p><b>Associations of this entity are:</b>
016 * <table border="1">
017 * <tr><th>Association Role Name</th><th>Role Type</th><th>Association Description</th><th>Role Description</th></tr>
018 * <tr><td>StudentEnrollsIntoCourse.Course</td><td>{@link com.almamater.crs.domains.courses.BOCourseCollection BOCourseCollection}</td><td>Students are enrolled in Courses</td><td>Courses which the Student is enrolled into</td></tr>
019 * </table>
020 *<P><I><U>Developer hints:</U>
021 *<UL>
022 *<LI>This collection can not be used to add or remove entities from associations - it merely represents a query to be executed against domain.
023 * Consequently collection objects can not be made editable and do not offer any transactional methods (eg. addEntity() removeEntity() etc).</LI>
024 *<LI>Some methods in this collection are very fast. This is because they do not invoke any queries to actual storage.
025 * Other methods do invoke queries to storage and therefore somewhat slower.
026 * General rule is that all "query building" operations (e.g. selectSomething()) are deferred until it is absolutely necessary to run the query.</LI>
027 *<LI>The query itself may be executed inside or outside of transaction. When query is executed inside transaction it does not take into account the unsaved changes made inside transaction.
028 * For example, if entity instance has been modified in the way that it no longer satisfies the query criteria, but changes were not saved prior to executing the query - the query result will contain this entity instance
029 * (the contents of this entity instance will be modified though). If this is a problem, consider doing one of the following:
030 * <UL>
031 * <LI>Use saveChanges() domain method prior to caling the querying method. This will execute all
032 * deferred updates and ensure that query will bring back correct results (note that the whole transaction may still be rolled back latter).
033 * The advantage of this approach is that it is simple to implement. The disadvantage is that the code may be saving changes too often and by doing so not taking full advantage of the batch updates.</LI>
034 * <LI>Use getCachedStudents() domain method after executing the query. This method returns all entity instances loaded into the domain since its creation
035 * (includes all created, modified and queried instances present in memory). Iterate over the obtained list and do explicit filtering (eg. check the value of certain attribute).</LI>
036 * The advantage of this approach is that it does not require saving updates. The disadvantage is that it requires additional Java code which does filtering.</LI>
037 * </UL>
038 *</UL></I>
039 */
040 public interface BOStudentCollection extends BOObjectCollection
041 {
042 /** Getter for the domain object this collection belongs to */
043 public BODomain getDomain() throws BOException;
044
045 /** Constructs the collection consisting of the same elements, but ordered in the requested manner.
046 * This method takes a simple, single ordering instruction and appends it to the previously issued ordering instructions
047 * so the result is a cummulative sort. To cancel sorting and obtain unsorted collection - use null or empty instance of the ordering instruction.
048 * <p>Note that sorting definition 'survives' collection filtering, so the select<SelectorName> and sort operations can be called in any order.
049 * The result will still be all elements satisfying filtering criterias sorted in the requested order.
050 * For example if collection was sorted and than some selector was applied - resulting collection will be filtered down but still sorted.</p>
051 *<P><I><U>Developer hint:</U> This operation is very fast
052 * because does not invoke any queries to storage. It just adds one more filtering condition
053 * to the query details stored in local memory.</I></P>
054
055 * @param pOrderingInstruction - single sorting instruction to add after previously issued ones.
056 * @return collection sorted as requested. */
057 public BOStudentCollection sortStudents(com.almamater.crs.types.system.courses.StudentOrderingInstruction pOrderingInstruction) throws BOException;
058
059 /** Constructs a collection that represents the union of this and the collection passed.
060 *<P><I><U>Developer hint:</U> This operation is very fast
061 * because does not invoke any queries to storage. It just adds one more filtering condition
062 * to the query details stored in local memory.</I></P>
063
064 * @return collection consisting of all elements found in either collection */
065 public BOStudentCollection union(BOStudentCollection pOtherCollection) throws BOException;
066
067 /** Constructs a collection that represents the intersection of this and the collection passed.
068 *<P><I><U>Developer hint:</U> This operation is very fast
069 * because does not invoke any queries to storage. It just adds one more filtering condition
070 * to the query details stored in local memory.</I></P>
071
072 * @return collection consisting of all elements found in both collections */
073 public BOStudentCollection intersection(BOStudentCollection pOtherCollection) throws BOException;
074
075 /** Constructs a collection that represents the difference between this and the collection passed.
076 *<P><I><U>Developer hint:</U> This operation is very fast
077 * because does not invoke any queries to storage. It just adds one more filtering condition
078 * to the query details stored in local memory.</I></P>
079
080 * @return collection consisting of all elements found in this collection and not found in passed collection */
081 public BOStudentCollection difference(BOStudentCollection pOtherCollection) throws BOException;
082
083 /** Constructs a collection that represents a subset of this collection. Subset is defined by position of the first element and its maximum size.
084 *<P><I><U>Developer hint:</U> This operation is very fast
085 * because does not invoke any queries to storage. It just adds one more filtering condition
086 * to the query details stored in local memory.</I></P>
087
088 * @return collection consisting of elements found in this collection starting from specified offset and not exceeding specified maximum size */
089 public BOStudentCollection selectStudents(com.almamater.types.core.CollectionOffset pStartOffset, com.almamater.types.core.SubsetSize pMaximumSize) throws BOException;
090
091 /** Returns the total number of elements in this collection.
092 *<P><I><U>Developer hint:</U> This operation is expensive from the performance point of view
093 * because it executes physical query against the storage.</I></P>
094
095 */
096 public com.almamater.types.core.CollectionSize size() throws BOException;
097
098 /** Returns true if collection is empty or false if collection has one or more elements.
099 *<P><I><U>Developer hint:</U> This operation is expensive from the performance point of view
100 * because it executes physical query against the storage.</I></P>
101
102 */
103 public com.almamater.types.core.BooleanField isEmpty() throws BOException;
104
105 /** Returns true if collection contains given instance of Student or false otherwise.
106 *<P><I><U>Developer hint:</U> This operation is expensive from the performance point of view
107 * because it executes physical query against the storage.</I></P>
108
109 */
110 public boolean contains(BOStudent pStudent) throws BOException;
111
112 /** Returns true if collection contains an instance of Student with given Instance Id or false otherwise.
113 *<P><I><U>Developer hint:</U> This operation is expensive from the performance point of view
114 * because it executes physical query against the storage.</I></P>
115
116 */
117 public boolean contains( com.almamater.crs.types.system.courses.StudentInstanceId pStudentId) throws BOException;
118
119 /** Returns true if collection contains an instance of Student with given primary key or false otherwise.
120 *<P><I><U>Developer hint:</U> This operation is expensive from the performance point of view
121 * because it executes physical query against the storage.</I></P>
122
123 */
124 public boolean contains(com.almamater.types.core.StudentNumber pStudentNo) throws BOException;
125
126 /** Returns entity object with matching Id only if this collection contains it or null otherwise.
127 *<P><I><U>Developer hint:</U> This operation is expensive from the performance point of view
128 * because it executes physical query against the storage.</I></P>
129
130 */
131 public BOStudent get( com.almamater.crs.types.system.courses.StudentInstanceId pStudentId) throws BOException;
132
133 /** Returns an instance of Student with matching primary key key only if this collection contains it or null otherwise.
134 *<P><I><U>Developer hint:</U> This operation is expensive from the performance point of view
135 * because it executes physical query against the storage.</I></P>
136
137 */
138 public BOStudent get(com.almamater.types.core.StudentNumber pStudentNo) throws BOException;
139
140 /** Returns all elements in this collection as an array. This call is non-paging,
141 * which means that it will return all elements every time it is called.
142 * Note that this call triggers actual storage query and may potentially take considerable time if collection is too large.
143 * Caller may choose to use paging version of toStudentsArray() method instead.
144 *<P><I><U>Developer hint:</U> This operation is expensive from the performance point of view
145 * because it executes physical query against the storage.</I></P>
146
147 * @return array of elements. May be zero-size array if this collection has no elements. */
148 public BOStudent[] toStudentsArray() throws BOException;
149
150 /** Returns collection, which represents all Courses associated with Students in this collection.
151 * The description of Course entity is: <i>Courses which the Student is enrolled into</i>
152 *<P><I><U>Developer hint:</U> This operation is very fast
153 * because does not invoke any queries to storage. It just adds one more filtering condition
154 * to the query details stored in local memory.</I></P>
155
156 */
157 public BOCourseCollection getAllCourses() throws BOException;
158 }
|