001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/sections/tags/sakai_2-4-1/sections-api/src/java/org/sakaiproject/section/api/SectionManager.java $
003: * $Id: SectionManager.java 20882 2007-02-01 22:42:44Z jholtzman@berkeley.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2005, 2006 The Regents of the University of California and The Regents of the University of Michigan
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.section.api;
021:
022: import java.sql.Time;
023: import java.util.Collection;
024: import java.util.List;
025: import java.util.Locale;
026: import java.util.Set;
027:
028: import org.sakaiproject.section.api.coursemanagement.Course;
029: import org.sakaiproject.section.api.coursemanagement.CourseSection;
030: import org.sakaiproject.section.api.coursemanagement.EnrollmentRecord;
031: import org.sakaiproject.section.api.coursemanagement.Meeting;
032: import org.sakaiproject.section.api.coursemanagement.ParticipationRecord;
033: import org.sakaiproject.section.api.coursemanagement.SectionEnrollments;
034: import org.sakaiproject.section.api.coursemanagement.User;
035: import org.sakaiproject.section.api.exception.MembershipException;
036: import org.sakaiproject.section.api.exception.RoleConfigurationException;
037: import org.sakaiproject.section.api.facade.Role;
038:
039: /**
040: * An internal service interface for the Section Manager Tool (AKA "Section Info")
041: * to provide for the creation, modification, and removal of CourseSections, along
042: * with the membership of of these sections.
043: *
044: * This service is not to be used outside of the Section Manager Tool.
045: *
046: * @author <a href="mailto:jholtzman@berkeley.edu">Josh Holtzman</a>
047: *
048: */
049: public interface SectionManager {
050:
051: /**
052: * Gets the course (whatever that means) associated with this site context.
053: *
054: * @param siteContext The site context
055: * @return The course (whatever that means)
056: */
057: public Course getCourse(String siteContext);
058:
059: /**
060: * Gets the sections associated with this site context.
061: *
062: * @param siteContext The site context
063: *
064: * @return The List of
065: * {@link org.sakaiproject.section.api.coursemanagement.CourseSection CourseSections}
066: * associated with this site context.
067: */
068: public List<CourseSection> getSections(String siteContext);
069:
070: /**
071: * Lists the sections in this context that are a member of the given category.
072: *
073: * @param siteContext The site context
074: * @param categoryId
075: *
076: * @return A List of {@link org.sakaiproject.section.api.coursemanagement.CourseSection CourseSections}
077: */
078: public List<CourseSection> getSectionsInCategory(
079: String siteContext, String categoryId);
080:
081: /**
082: * Gets a {@link org.sakaiproject.section.api.coursemanagement.CourseSection CourseSection}
083: * by its uuid.
084: *
085: * @param sectionUuid The uuid of a section
086: *
087: * @return A section
088: */
089: public CourseSection getSection(String sectionUuid);
090:
091: /**
092: * Gets a list of {@link org.sakaiproject.section.api.coursemanagement.ParticipationRecord
093: * ParticipationRecord}s for all instructors in the current site.
094: *
095: * @param siteContext The current site context
096: * @return The instructors
097: */
098: public List<ParticipationRecord> getSiteInstructors(
099: String siteContext);
100:
101: /**
102: * Gets a list of {@link org.sakaiproject.section.api.coursemanagement.ParticipationRecord
103: * ParticipationRecord}s for all TAs in the current site.
104: *
105: * @param siteContext The current site context
106: * @return The TAs
107: */
108: public List<ParticipationRecord> getSiteTeachingAssistants(
109: String siteContext);
110:
111: /**
112: * Gets a list of {@link org.sakaiproject.section.api.coursemanagement.ParticipationRecord
113: * ParticipationRecord}s for all TAs in a section.
114: *
115: * @param sectionUuid The section uuid
116: * @return The TAs
117: */
118: public List<ParticipationRecord> getSectionTeachingAssistants(
119: String sectionUuid);
120:
121: /**
122: * Gets a list of {@link org.sakaiproject.section.api.coursemanagement.EnrollmentRecord
123: * EnrollmentRecord}s belonging to the current site.
124: *
125: * @param siteContext The current site context
126: * @return The enrollments
127: */
128: public List<EnrollmentRecord> getSiteEnrollments(String siteContext);
129:
130: /**
131: * Gets a list of {@link org.sakaiproject.section.api.coursemanagement.EnrollmentRecord
132: * EnrollmentRecord}s belonging to a section.
133: *
134: * @param sectionUuid The section uuid
135: * @return The enrollments
136: */
137: public List<EnrollmentRecord> getSectionEnrollments(
138: String sectionUuid);
139:
140: /**
141: * Finds a list of {@link org.sakaiproject.section.api.coursemanagement.EnrollmentRecord
142: * EnrollmentRecord}s belonging to the current site and whose sort name, display name,
143: * or display id start with the given string pattern.
144: *
145: * @param siteContext The current site context
146: * @param pattern The pattern to match students names or ids
147: *
148: * @return The enrollments
149: */
150: public List<EnrollmentRecord> findSiteEnrollments(
151: String siteContext, String pattern);
152:
153: /**
154: * Gets a SectionEnrollments data structure for the given students.
155: *
156: * @param siteContext The site context
157: * @param studentUids The Set of userUids to include in the SectionEnrollments
158: *
159: * @return
160: */
161: public SectionEnrollments getSectionEnrollmentsForStudents(
162: String siteContext, Set studentUids);
163:
164: /**
165: * Adds the current user to a section as a student. This is a convenience
166: * method for addSectionMembership(currentUserId, Role.STUDENT, sectionId).
167: * @param sectionUuid
168: * @throws RoleConfigurationException If there is no valid student role, or
169: * if there is more than one group-scoped role flagged as a student role.
170: */
171: public EnrollmentRecord joinSection(String sectionUuid)
172: throws RoleConfigurationException;
173:
174: /**
175: * Switches a student's currently assigned section. If the student is enrolled
176: * in another section of the same type, that enrollment will be dropped.
177: *
178: * This is a convenience method to allow a drop/add (a switch) in a single transaction.
179: *
180: * @param newSectionUuid The new section uuid to which the student should be assigned
181: * @throws RoleConfigurationException If there is no valid student role, or
182: * if there is more than one group-scoped role flagged as a student role.
183: */
184: public void switchSection(String newSectionUuid)
185: throws RoleConfigurationException;
186:
187: /**
188: * Returns the total number of students enrolled in a learning context. Useful for
189: * comparing to the max number of enrollments allowed in a section.
190: *
191: * @param sectionUuid
192: * @return
193: */
194: public int getTotalEnrollments(String learningContextUuid);
195:
196: /**
197: * Adds a user to a section under the specified role. If a student is added
198: * to a section, s/he will be automatically removed from any other section
199: * of the same category in this site. So adding 'student1' to 'Lab1', for
200: * example, will automatically remove 'student1' from 'Lab2'. TAs may be
201: * added to multiple sections in a site regardless of category.
202: *
203: * @param userUid
204: * @param role
205: * @param sectionUuid
206: * @throws MembershipException Only students and TAs can be members of a
207: * section. Instructor roles are assigned only at the course level.
208: * @throws RoleConfigurationException Thrown when no sakai role can be
209: * identified to represent the given role.
210: */
211: public ParticipationRecord addSectionMembership(String userUid,
212: Role role, String sectionUuid) throws MembershipException,
213: RoleConfigurationException;
214:
215: /**
216: * Defines the complete set of users that make up the members of a section in
217: * a given role. This is useful when doing bulk modifications of section
218: * membership.
219: *
220: * @param userUids The set of userUids as strings
221: * @param sectionId The sectionId
222: *
223: * @throws RoleConfigurationException If there is no properly configured role
224: * in the site matching the role specified.
225: */
226: public void setSectionMemberships(Set userUids, Role role,
227: String sectionId) throws RoleConfigurationException;
228:
229: /**
230: * Removes a user from a section.
231: *
232: * @param userUid
233: * @param sectionUuid
234: */
235: public void dropSectionMembership(String userUid, String sectionUuid);
236:
237: /**
238: * Removes the user from any enrollment to a section of the given category.
239: *
240: * @param studentUid
241: * @param siteContext
242: * @param category
243: */
244: public void dropEnrollmentFromCategory(String studentUid,
245: String siteContext, String category);
246:
247: /**
248: * Adds a CourseSection with a single meeting time to a parent CourseSection.
249: * This method is deprecated. Please use addSection(String courseUuid, String title,
250: * String category, Integer maxEnrollments, List meetings)
251: *
252: * @param courseUuid
253: * @param title
254: * @param category
255: * @param maxEnrollments
256: * @param location
257: * @param startTime
258: * @param startTimeAm
259: * @param endTime
260: * @param endTimeAm
261: * @param monday
262: * @param tuesday
263: * @param wednesday
264: * @param thursday
265: * @param friday
266: * @param saturday
267: * @param sunday
268: *
269: * @deprecated
270: *
271: * @return
272: */
273: public CourseSection addSection(String courseUuid, String title,
274: String category, Integer maxEnrollments, String location,
275: Time startTime, Time endTime, boolean monday,
276: boolean tuesday, boolean wednesday, boolean thursday,
277: boolean friday, boolean saturday, boolean sunday);
278:
279: /**
280: * Adds multiple sections at once. This should help address the inefficiencies
281: * described in http://bugs.sakaiproject.org/jira/browse/SAK-7503.
282: *
283: * Meeting times should be, but are not handled by an external calendar service.
284: * So, the added functionality of linking course sections to repeating events (meet
285: * every 2nd Tuesday of the month at 3pm) is currently out of scope. Instead,
286: * meetings are represented as a start time, end time, and seven booleans
287: * representing the days that the section meets.
288: *
289: * @param courseUuid
290: * @param sections
291: */
292: public Collection<CourseSection> addSections(String courseUuid,
293: Collection<CourseSection> sections);
294:
295: /**
296: * Updates the persistent representation of the given CourseSection. Once
297: * a section is created, its category is immutable. This method will remove all
298: * but one Meeting associated with this CourseSection. To update a CourseSection
299: * and all of its meetings, use updateSection(String sectionUuid, String title,
300: * Integer maxEnrollments, List meetings).
301: *
302: * @param sectionUuid
303: * @param title
304: * @param maxEnrollments
305: * @param location
306: * @param startTime
307: * @param startTimeAm
308: * @param endTime
309: * @param endTimeAm
310: * @param monday
311: * @param tuesday
312: * @param wednesday
313: * @param thursday
314: * @param friday
315: * @param saturday
316: * @param sunday
317: *
318: * @deprecated
319: */
320: public void updateSection(String sectionUuid, String title,
321: Integer maxEnrollments, String location, Time startTime,
322: Time endTime, boolean monday, boolean tuesday,
323: boolean wednesday, boolean thursday, boolean friday,
324: boolean saturday, boolean sunday);
325:
326: /**
327: * Updates a section and all of its meetings. Notice that you can not change a
328: * section's category once it's been created.
329: *
330: * @param sectionUuid
331: * @param title
332: * @param maxEnrollments
333: * @param meetings
334: */
335: public void updateSection(String sectionUuid, String title,
336: Integer maxEnrollments, List<Meeting> meetings);
337:
338: /**
339: * Disbands a course section. This does not affect enrollment records for
340: * the course.
341: *
342: * @param sectionUuid
343: */
344: public void disbandSection(String sectionUuid);
345:
346: /**
347: * Disbands course sections. This does not affect enrollment records for
348: * the course.
349: *
350: * @param sectionUuids
351: */
352: public void disbandSections(Set<String> sectionUuids);
353:
354: /**
355: * Determines whether students can enroll themselves in a section.
356: *
357: *
358: * @param courseUuid
359: * @return
360: */
361: public boolean isSelfRegistrationAllowed(String courseUuid);
362:
363: /**
364: * Determines whether students can switch sections once they are enrolled in
365: * a section of a given category (for instance, swapping one lab for another).
366: *
367: * @param courseUuid
368: * @return
369: */
370: public boolean isSelfSwitchingAllowed(String courseUuid);
371:
372: /**
373: * Sets the join/switch options for a course.
374: *
375: * @param courseUuid
376: * @param joinAllowed
377: * @param switchAllowed
378: */
379: public void setJoinOptions(String courseUuid, boolean joinAllowed,
380: boolean switchAllowed);
381:
382: /**
383: * Determines whether a course is externally managed.
384: *
385: * @param courseUuid
386: * @return
387: */
388: public boolean isExternallyManaged(String courseUuid);
389:
390: /**
391: * Sets a course as externally or internally managed.
392: *
393: * @param courseUuid
394: * @param externallyManaged
395: */
396: public void setExternallyManaged(String courseUuid,
397: boolean externallyManaged);
398:
399: /**
400: * The Section Manager tool could use more specific queries on membership,
401: * such as this: getting all students in a primary section that are not
402: * enrolled in any secondary sections of a given type. For instance, 'Who
403: * are the students who are not enrolled in any lab?'
404: *
405: * @return A List of {@link
406: * org.sakaiproject.section.api.coursemanagement.EnrollmentRecord
407: * EnrollmentRecords} of students who are enrolled in the course but are
408: * not enrolled in a section of the given section category.
409: */
410: public List<EnrollmentRecord> getUnsectionedEnrollments(
411: String courseUuid, String category);
412:
413: /**
414: * Gets all of the section enrollments for a user in a course. Useful for
415: * listing all of the sections in which a student is enrolled.
416: *
417: * @param userUid
418: * @param courseUuid
419: * @return A Set of EnrollmentRecords
420: */
421: public Set<EnrollmentRecord> getSectionEnrollments(String userUid,
422: String courseUuid);
423:
424: /**
425: * Gets the localized name of a given category.
426: *
427: * @param categoryId A string identifying the category
428: * @param locale The locale of the client
429: *
430: * @return An internationalized string to display for this category.
431: *
432: */
433: public String getCategoryName(String categoryId, Locale locale);
434:
435: /**
436: * Gets the list of section categories. These are not configurable on a per-course
437: * or per-context bases.
438: *
439: * @param siteContext The site context (which is not used in the
440: * current implementation)
441: *
442: * @return A List of unique Strings that identify the available section
443: * categories.
444: */
445: public List<String> getSectionCategories(String siteContext);
446:
447: /**
448: * Gets a single User object for a student in a site.
449: *
450: * @param siteContext Needed by the standalone implementation to find the user
451: * @param studentUid
452: * @return The User representing this student
453: */
454: public User getSiteEnrollment(String siteContext, String studentUid);
455:
456: //// Configuration
457:
458: /**
459: * Describes the configuraiton for the SectionManager service and the Section
460: * Info tool:
461: *
462: * <ul>
463: * <li><b>MANUAL_MANDATORY</b> - The section Info tool does not allow for
464: * externally managed sections, and sections will never be created automatically</li>
465: *
466: * <li><b>MANUAL_DEFAULT</b> - The section Info tool allows the user
467: * to choose whether sections should be internally or externally managed.
468: * Sections will not be generated for sites unless a site maintainer switches the
469: * default "manual" setting to automatic.</li>
470: *
471: * <li><b>AUTOMATIC_DEFAULT</b> - The section Info tool allows the user
472: * to choose whether sections should be internally or externally managed.
473: * Sections will be generated for sites associated with any number of rosters.
474: * The default setting for new sites will be automatic management of sections.</li>
475: *
476: * <li><b>AUTOMATIC_MANDATORY</b> - The section Info tool does not allow
477: * for internally managed sections. Add sections are created automatically, based
478: * on the rosters associated with the site.</li>
479: * </ul>
480: *
481: * @author <a href="mailto:jholtzman@berkeley.edu">jholtzman@berkeley.edu</a>
482: *
483: */
484: public enum ExternalIntegrationConfig {
485: MANUAL_MANDATORY, MANUAL_DEFAULT, AUTOMATIC_DEFAULT, AUTOMATIC_MANDATORY
486: };
487:
488: /**
489: * Gets the application-wide configuration setting.
490: *
491: * @param obj An object to pass any necessary context information.
492: * @return
493: */
494: public ExternalIntegrationConfig getConfiguration(Object obj);
495:
496: public static final String CONFIGURATION_KEY = "section.info.integration";
497:
498: }
|