001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/course-management/tags/sakai_2-4-1/cm-api/api/src/java/org/sakaiproject/coursemanagement/api/CourseManagementService.java $
003: * $Id: CourseManagementService.java 21050 2007-02-06 16:12:06Z jholtzman@berkeley.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.coursemanagement.api;
021:
022: import java.util.List;
023: import java.util.Locale;
024: import java.util.Map;
025: import java.util.Set;
026:
027: import org.sakaiproject.coursemanagement.api.exception.IdNotFoundException;
028:
029: /**
030: * A read-only service that queries enterprise course, section, membership, and
031: * enrollment data.
032: *
033: * @author <a href="mailto:jholtzman@berkeley.edu">Josh Holtzman</a>
034: */
035: public interface CourseManagementService {
036:
037: /**
038: * Gets a CourseSet by its eid.
039: *
040: * @param courseSetEid The CourseSet's unique eid
041: * @return The CourseSet
042: * @throws IdNotFoundException If the eid is not associated with any CourseSet
043: */
044: public CourseSet getCourseSet(String courseSetEid)
045: throws IdNotFoundException;
046:
047: /**
048: * Checks whether a CourseSet exists.
049: *
050: * @param eid The enterprise id
051: * @return Whether the object exists
052: */
053: public boolean isCourseSetDefined(String eid);
054:
055: /**
056: * Gets the child CourseSet from a parent CourseSet.
057: *
058: * @param parentCourseSetEid The parent CourseSet eid
059: * @return The Set of child CourseSets
060: */
061: public Set<CourseSet> getChildCourseSets(String parentCourseSetEid)
062: throws IdNotFoundException;
063:
064: /**
065: * Gets all of the top level CourseSets
066: *
067: * @return The Set of CourseSets that have no parent CourseSet
068: */
069: public Set<CourseSet> getCourseSets();
070:
071: /**
072: * Gets the memberships directly contained by this CourseSet.
073: *
074: * @param courseSetEid
075: * @return The set of memberships in this CourseSet. This is not a transitive
076: * set.
077: * @throws IdNotFoundException If the eid is not associated with any CourseSet
078: */
079: public Set<Membership> getCourseSetMemberships(String courseSetEid)
080: throws IdNotFoundException;
081:
082: /**
083: * Gets a CanonicalCourse by its eid.
084: *
085: * @param canonicalCourseEid
086: * @return The CanonicalCourse
087: * @throws IdNotFoundException If the eid is not associated with any CanonicalCourse
088: */
089: public CanonicalCourse getCanonicalCourse(String canonicalCourseEid)
090: throws IdNotFoundException;
091:
092: /**
093: * Checks whether a CanonicalCourse exists.
094: *
095: * @param eid The enterprise id
096: * @return Whether the object exists
097: */
098: public boolean isCanonicalCourseDefined(String eid);
099:
100: /**
101: * Gets the equivalent CanonicalCourses.
102: *
103: * @param canonicalCourseEid The eid of the CanonicalCourse to use in finding equivalents
104: * @return The set of CanonicalCourses that are equivalent (in the Enterprise
105: * view, not in the Java view -- this is independent of CanonicalCourse.equals()).
106: */
107: public Set<CanonicalCourse> getEquivalentCanonicalCourses(
108: String canonicalCourseEid) throws IdNotFoundException;
109:
110: /**
111: * Gets the CanonicalCourses in a CourseSet.
112: *
113: * @param courseSetEid The eid of the CourseSet
114: * @return The set of CanonicalCourses in the CourseSet
115: * @throws IdNotFoundException If the eid is not associated with any CourseSet
116: */
117: public Set<CanonicalCourse> getCanonicalCourses(String courseSetEid)
118: throws IdNotFoundException;
119:
120: /**
121: * Gets the list of all known AcademicSessions, sorted by start date.
122: *
123: * @return
124: */
125: public List<AcademicSession> getAcademicSessions();
126:
127: /**
128: * Gets the list of current AcademicSessions, sorted by start date.
129: *
130: * @return
131: */
132: public List<AcademicSession> getCurrentAcademicSessions();
133:
134: /**
135: * Gets a AcademicSession by its eid.
136: * @param eid
137: * @return The AcademicSession
138: * @throws IdNotFoundException If the eid is not associated with any AcademicSession
139: */
140: public AcademicSession getAcademicSession(String eid)
141: throws IdNotFoundException;
142:
143: /**
144: * Checks whether an AcademicSession exists.
145: *
146: * @param eid The enterprise id
147: * @return Whether the object exists
148: */
149: public boolean isAcademicSessionDefined(String eid);
150:
151: /**
152: * Gets a CourseOffering by its eid.
153: *
154: * @param courseOfferingEid
155: * @return The CourseOffering
156: * @throws IdNotFoundException If the eid is not associated with any CourseOffering
157: */
158: public CourseOffering getCourseOffering(String courseOfferingEid)
159: throws IdNotFoundException;
160:
161: /**
162: * Checks whether a CourseOffering exists.
163: *
164: * @param eid The enterprise id
165: * @return Whether the object exists
166: */
167: public boolean isCourseOfferingDefined(String eid);
168:
169: /**
170: * Gets any equivalent CourseOfferings.
171: *
172: * @param courseOfferingEid The eid of the CourseOffering to use in finding equivalents
173: * @return The set of CourseOfferings that are equivalent (in the Enterprise
174: * view, not in the Java view -- this is independent of CourseOffering.equals()).
175: * @throws IdNotFoundException If the eid is not associated with any CourseOffering
176: */
177: public Set<CourseOffering> getEquivalentCourseOfferings(
178: String courseOfferingEid) throws IdNotFoundException;
179:
180: /**
181: * Gets the memberships directly contained by this CourseOffering.
182: *
183: * @param courseOfferingEid
184: * @return The set of memberships in this CourseOffering. This is not a recursive
185: * set of Memberships.
186: * @throws IdNotFoundException If the eid is not associated with any CourseOffering
187: */
188: public Set<Membership> getCourseOfferingMemberships(
189: String courseOfferingEid) throws IdNotFoundException;
190:
191: /**
192: * Gets the CourseOfferings in a CourseSet.
193: *
194: * @param courseSetEid The eid of the CourseSet
195: * @return The set of CourseOfferings in the CourseSet
196: * @throws IdNotFoundException If the eid is not associated with any CourseSet
197: */
198: public Set<CourseOffering> getCourseOfferingsInCourseSet(
199: String courseSetEid) throws IdNotFoundException;
200:
201: /**
202: * Finds all of the course offerings in a course set that are current for any given
203: * academic session (regardless of the courseOffering's start and end dates).
204: *
205: * @param courseSetEid
206: * @param academicSessionEid
207: * @return The set of course offerings
208: * @throws IdNotFoundException
209: */
210: public Set<CourseOffering> findCourseOfferings(String courseSetEid,
211: String academicSessionEid) throws IdNotFoundException;
212:
213: /**
214: * Finds all course offerings belonging to a canonical course.
215: *
216: * @param canonicalCourseEid The enterprise id of the canonical course
217: * @return The set of course offerings
218: * @throws IdNotFoundException
219: */
220: public Set<CourseOffering> getCourseOfferingsInCanonicalCourse(
221: String canonicalCourseEid) throws IdNotFoundException;
222:
223: /**
224: * Finds all course sets in a given category. Useful for listing the departments
225: * @param category
226: * @return The list of course sets, sorted by title, ascending
227: */
228: public List<CourseSet> findCourseSets(String category);
229:
230: /**
231: * Determines whether a CourseSet has any CanonicalCourses or CourseSets.
232: *
233: * @param courseSetEid
234: * @return
235: */
236: public boolean isEmpty(String courseSetEid);
237:
238: /**
239: * Gets a Section by its eid.
240: *
241: * @param sectionEid
242: * @return The Section
243: * @throws IdNotFoundException If the eid is not associated with any Section
244: */
245: public Section getSection(String sectionEid)
246: throws IdNotFoundException;
247:
248: /**
249: * Checks whether a Section exists.
250: *
251: * @param eid The enterprise id
252: * @return Whether the object exists
253: */
254: public boolean isSectionDefined(String eid);
255:
256: /**
257: * Gets the top-level Sections associated with a CourseOffering
258: *
259: * @param courseOfferingEid
260: * @return The Set of Sections
261: * @throws IdNotFoundException If the eid is not associated with any CourseOffering
262: */
263: public Set<Section> getSections(String courseOfferingEid)
264: throws IdNotFoundException;
265:
266: /**
267: * Gets the list of section categories defined by the institution.
268: *
269: * @return
270: */
271: public List<String> getSectionCategories();
272:
273: /**
274: * Gets the description for a category, identified by the category code, or null
275: * if the category code can not be found.
276: *
277: * @param sectionCategoryCode
278: * @return
279: */
280: public String getSectionCategoryDescription(String categoryCode);
281:
282: /**
283: * Gets the child Sections from a parent Section.
284: *
285: * @param parentSectionEid The parent Section eid
286: * @return The Set of child Sections
287: * @throws IdNotFoundException If the eid is not associated with any parent Section
288: */
289: public Set<Section> getChildSections(String parentSectionEid)
290: throws IdNotFoundException;
291:
292: /**
293: * Gets the members directly contained by this Section.
294: *
295: * @param sectionEid
296: * @return The set of members in this Section. This is not a transitive
297: * set.
298: * @throws IdNotFoundException If the eid is not associated with any Section
299: */
300: public Set<Membership> getSectionMemberships(String sectionEid)
301: throws IdNotFoundException;
302:
303: /**
304: * Gets an EnrollmentSet by its eid.
305: *
306: * @param enrollmentSetEid
307: * @return The EnrollmentSet
308: * @throws IdNotFoundException If the eid is not associated with any EnrollmentSet
309: */
310: public EnrollmentSet getEnrollmentSet(String enrollmentSetEid)
311: throws IdNotFoundException;
312:
313: /**
314: * Checks whether an EnrollmentSet exists.
315: *
316: * @param eid The enterprise id
317: * @return Whether the object exists
318: */
319: public boolean isEnrollmentSetDefined(String eid);
320:
321: /**
322: * Gets the EnrollmentSets associated with a CourseOffering
323: *
324: * @param courseOfferingEid
325: * @return The Set of EnrollmentSets
326: * @throws IdNotFoundException If the eid is not associated with any CourseOffering
327: */
328: public Set<EnrollmentSet> getEnrollmentSets(String courseOfferingEid)
329: throws IdNotFoundException;
330:
331: /**
332: * Gets the Enrollments in an EnrollmentSet (including dropped enrollments)
333: *
334: * @param enrollmentSetEid
335: * @return The Set of Enrollments
336: * @throws IdNotFoundException If the eid is not associated with any EnrollmentSet
337: */
338: public Set<Enrollment> getEnrollments(String enrollmentSetEid)
339: throws IdNotFoundException;
340:
341: /**
342: * Gets the known enrollment status codes and descriptions for Enrollments.
343: *
344: * @return
345: */
346: public Map<String, String> getEnrollmentStatusDescriptions(
347: Locale locale);
348:
349: /**
350: * Gets the known grading scheme codes and descriptions for Enrollments.
351: *
352: * @return
353: */
354: public Map<String, String> getGradingSchemeDescriptions(
355: Locale locale);
356:
357: /**
358: * Gets the known membership status codes and descriptions for Memberships.
359: *
360: * @return
361: */
362: public Map<String, String> getMembershipStatusDescriptions(
363: Locale locale);
364:
365: /**
366: * Gets the set of user ids that are, according to the enterprise, responsible for
367: * the EnrollmentSet. Responsibilities usually include submitting the final grades
368: * for students enrolled in the EnrollmentSet.
369: *
370: * @param enrollmentSetEid
371: * @return The set of ids for users who are responsible for this EnrollmentSet
372: * @throws IdNotFoundException If the eid is not associated with any EnrollmentSet
373: */
374: public Set<String> getInstructorsOfRecordIds(String enrollmentSetEid)
375: throws IdNotFoundException;
376:
377: /**
378: * Determines whether a user is enrolled (and not dropped) in an EnrollmentSet.
379: * This method is needed to implement Sakai's GroupProvider.
380: *
381: * @param userEid The student's userEid
382: * @param enrollmentSetEids The set of EnrollmentSetEids
383: * @return
384: */
385: public boolean isEnrolled(String userEid,
386: Set<String> enrollmentSetEids);
387:
388: /**
389: * Convenience method for checking whether a user is enrolled (and not dropped)
390: * in an EnrollmentSet.
391: *
392: * @param userEid
393: * @param enrollmentSetEid
394: * @return
395: */
396: public boolean isEnrolled(String userEid, String enrollmentSetEid);
397:
398: /**
399: * Finds the Enrollment for a user in an EnrollmentSet. If the user isn't in the
400: * EnrollmentSet, or the EnrollmentSet doesn't exist, this returns null. Note that
401: * this method will return enrollments flagged as "dropped".
402: *
403: * TODO Should this throw more descriptive exceptions e.g. when the EnrollmentSet doesn't exist?
404: *
405: * @param userEid
406: * @param enrollmentSetEid
407: * @return
408: */
409: public Enrollment findEnrollment(String userEid,
410: String enrollmentSetEid);
411:
412: /**
413: * Finds the set of current EnrollmentSets for which a user is enrolled but not dropped.
414: * An EnrollmentSet is considered current if its CourseOffering's start date
415: * (is null or prior to the current date/time) and its end date (is null or
416: * after the current date/time).
417: *
418: * @param userEid
419: * @return
420: */
421: public Set<EnrollmentSet> findCurrentlyEnrolledEnrollmentSets(
422: String userEid);
423:
424: /**
425: * Finds the set of current EnrollmentSets for which a user is an instructor of
426: * record. An EnrollmentSet is considered current if its CourseOffering's start
427: * date (is null or prior to the current date/time) and its end date (is null or
428: * after the current date/time).
429: *
430: * @param userEid
431: * @return
432: */
433: public Set<EnrollmentSet> findCurrentlyInstructingEnrollmentSets(
434: String userEid);
435:
436: /**
437: * Finds all Sections that are linked to an EnrollmentSet for
438: * which a user is an instructor of record.
439: *
440: * @param userEid
441: * @return
442: */
443: public Set<Section> findInstructingSections(String userEid);
444:
445: /**
446: * Finds all Sections that are linked to an EnrollmentSet for
447: * which a user is enrolled (but not dropped).
448: *
449: * @param userEid
450: * @return
451: */
452: public Set<Section> findEnrolledSections(String userEid);
453:
454: /**
455: * Finds all Sections that are linked to an EnrollmentSet for which a user is an
456: * instructor of record and which are part of a CourseOffering in a given
457: * AcademicSession.
458: *
459: * @param userEid
460: * @param academicSessionEid
461: * @return
462: */
463: public Set<Section> findInstructingSections(String userEid,
464: String academicSessionEid) throws IdNotFoundException;
465:
466: /**
467: * Finds the Sections (and roles) for which a user is a member.
468: *
469: * @param userEid
470: * @return A Map of Section EIDs to roles for the user
471: */
472: public Map<String, String> findSectionRoles(String userEid);
473:
474: /**
475: * Finds the CourseOfferings (and roles) for which a user is a member.
476: *
477: * @param userEid
478: * @return A Map of CourseOffering EIDs to roles for the user
479: */
480: public Map<String, String> findCourseOfferingRoles(String userEid);
481:
482: /**
483: * Finds the CourseSets (and roles) for which a user is a member.
484: *
485: * @param userEid
486: * @return A Map of CourseSet EIDs to roles for the user
487: */
488: public Map<String, String> findCourseSetRoles(String userEid);
489:
490: }
|