001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/sections/tags/sakai_2-4-1/sections-api/src/java/org/sakaiproject/section/api/SectionAwareness.java $
003: * $Id: SectionAwareness.java 18134 2006-11-14 18:59:25Z 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.util.List;
023: import java.util.Locale;
024:
025: import org.sakaiproject.section.api.coursemanagement.CourseSection;
026: import org.sakaiproject.section.api.facade.Role;
027:
028: /**
029: * <p>
030: * Provides section awareness to tools needing read-only access to section
031: * information, such as section membership.
032: * </p>
033: *
034: * @author <a href="mailto:ray@media.berkeley.edu">Ray Davis</a>
035: * @author <a href="mailto:jholtzman@berkeley.edu">Josh Holtzman</a>
036: */
037: public interface SectionAwareness {
038:
039: /** The permission "marker" indicating that a role is the student role */
040: public static final String STUDENT_MARKER = "section.role.student";
041:
042: /** The permission "marker" indicating that a role is the ta role */
043: public static final String TA_MARKER = "section.role.ta";
044:
045: /** The permission "marker" indicating that a role is the instructor role */
046: public static final String INSTRUCTOR_MARKER = "section.role.instructor";
047:
048: /**
049: * Gets the sections associated with this site context.
050: *
051: * @param siteContext The site context
052: *
053: * @return The List of
054: * {@link org.sakaiproject.section.api.coursemanagement.CourseSection CourseSections}
055: * associated with this site context.
056: */
057: public List getSections(String siteContext);
058:
059: /**
060: * Gets the list of section categories. In sakai 2.1, there will be only a
061: * single set of categories. They will not be configurable on a per-course
062: * or per-context bases. In future versions, the list of categories will
063: * be configurable at the site level.
064: *
065: * @param siteContext The site context
066: *
067: * @return A List of unique Strings that identify the available section
068: * categories. These should be internationalized for display using
069: * {@link SectionAwareness#getCategoryName(String, Locale) getCategoryName}.
070: */
071: public List getSectionCategories(String siteContext);
072:
073: /**
074: * Gets a {@link org.sakaiproject.section.api.coursemanagement.CourseSection CourseSection}
075: * by its uuid.
076: *
077: * @param sectionUuid
078: *
079: * @return
080: */
081: public CourseSection getSection(String sectionUuid);
082:
083: /**
084: * Gets the site membership for a given context.
085: *
086: * @param siteContext The site context
087: *
088: * @return A {@link java.util.List List} of
089: * {@link org.sakaiproject.section.api.coursemanagement.ParticipationRecord
090: * ParticipationRecords} representing the users in the given site, playing
091: * the given {@link org.sakaiproject.section.api.facade.Role Role}.
092: *
093: */
094: public List getSiteMembersInRole(String siteContext, Role role);
095:
096: /**
097: * Finds site members in the given context and {@link org.sakaiproject.section.api.facade.Role Role}
098: * with a matching name or display id. Pattern matching is TBD, but will
099: * probably match in any of the following cases:
100: *
101: * <ul>
102: * <li>Display Name = pattern*</li>
103: * <li>Sort Name = pattern*</li>
104: * <li>Display Id (installation defined, either Email or enterprise id) = pattern*</li>
105: * </ul>
106: *
107: * @param siteContext The site context
108: * @param role The role the user must play in this context
109: * @param pattern The pattern the user's name or id must match
110: *
111: * @return A {@link java.util.List List} of
112: * {@link org.sakaiproject.section.api.coursemanagement.ParticipationRecord
113: * ParticipationRecords} representing the users in the given site, playing
114: * the given role, that match the string pattern.
115: */
116: public List findSiteMembersInRole(String siteContext, Role role,
117: String pattern);
118:
119: /**
120: * Checks whether a user plays a particular {@link org.sakaiproject.section.api.facade.Role Role}
121: * in a given site context.
122: *
123: * @param siteContext The site context
124: * @param userUid The user's unique id
125: * @param role The role we're checking
126: *
127: * @return Whether this user plays this role in this context.
128: */
129: public boolean isSiteMemberInRole(String siteContext,
130: String userUid, Role role);
131:
132: /**
133: * Gets the full membership of the given section.
134: *
135: * @param sectionId
136: *
137: * @return A {@link java.util.List List} of
138: * {@link org.sakaiproject.section.api.coursemanagement.ParticipationRecord
139: * ParticipationRecords} representing the users in a
140: * {@link org.sakaiproject.section.api.coursemanagement.CourseSection CourseSection}.
141: */
142: public List getSectionMembers(String sectionId);
143:
144: /**
145: * Gets the members of a given section that play a given role in the section.
146: *
147: * @param sectionUuid
148: * @param role
149: *
150: * @return A {@link java.util.List List} of
151: * {@link org.sakaiproject.section.api.coursemanagement.ParticipationRecord
152: * ParticipationRecords} representing the users in a
153: * {@link org.sakaiproject.section.api.coursemanagement.CourseSection CourseSection}
154: * that play a given {@link org.sakaiproject.section.api.facade.Role Role}.
155: */
156: public List getSectionMembersInRole(String sectionUuid, Role role);
157:
158: /**
159: * Checks whether a user plays a particular {@link org.sakaiproject.section.api.facade.Role Role}
160: * in a section.
161: *
162: * @param sectionId
163: * @param personId
164: * @param role
165: *
166: * @return Whether the user plays a particular role in a section.
167: */
168: public boolean isSectionMemberInRole(String sectionId,
169: String personId, Role role);
170:
171: /**
172: * Gets all users who are members of a site but are members of zero sections
173: * within the site.
174: *
175: * @param siteContext The site context
176: * @param role The role that the user must play in the given site
177: *
178: * @return A List of ParticipationRecords
179: */
180: public List getUnassignedMembersInRole(String siteContext, Role role);
181:
182: /**
183: * Lists the sections in this context that are a member of the given category.
184: *
185: * @param siteContext The site context
186: * @param categoryId
187: *
188: * @return A List of {@link org.sakaiproject.section.api.coursemanagement.CourseSection CourseSections}
189: */
190: public List getSectionsInCategory(String siteContext,
191: String categoryId);
192:
193: /**
194: * Gets the localized name of a given category.
195: *
196: * @param categoryId A string identifying the category
197: * @param locale The locale of the client
198: *
199: * @return An internationalized string to display for this category.
200: *
201: */
202: public String getCategoryName(String categoryId, Locale locale);
203:
204: }
|