/**********************************************************************************
*
* $Id$
*
***********************************************************************************
*
* Copyright (c) 2005 The Regents of the University of California, The MIT Corporation
*
* Licensed under the Educational Community License Version 1.0 (the "License");
* By obtaining, using and/or copying this Original Work, you agree that you have read,
* understand, and will comply with the terms and conditions of the Educational Community License.
* You may obtain a copy of the License at:
*
*      http://cvs.sakaiproject.org/licenses/license_1_0.html
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
* AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
**********************************************************************************/

package org.sakaiproject.tool.gradebook.facades;

import java.util.Collection;
import java.util.List;
import java.util.Set;

import org.sakaiproject.service.gradebook.shared.UnknownUserException;

/**
 * Facade to external course and group services.
 *
 * Baseline Sakai 2.0 gradebook requirements are minimal.
 *
 * For full LMS capabilities, much richer notions of course offerings, sections,
 * terms, roles, and enrollments will need to be supported.
 */
public interface CourseManagement {
	/**
	 * @param gradebookUid
	 *            the UID of the given gradebook instance; typically used to
	 *            reference the equivalent course offering
	 * @return the matching Enrollment records
	 */
	public Set getEnrollments(String gradebookUid);

	/**
	 * Obtain the number of students included in the specified gradebook.
	 * This is the only CourseManagement information needed to calculate
	 * the most frequently displayed gradebook statistics.
	 *
	 * Although not strictly needed to meet requirements, this gives implementors
	 * a way to optimize a frequent operation.
	 *
	 * @param gradebookUid
	 * @return the number of enrollments
	 */
	public int getEnrollmentsSize(String gradebookUid);

	/**
	 * Search for enrollments whose students have names or display uids that
     * match the specified criteria. For the V2.0 Baseline Gradebook, we've said
     * the input query will be split on space-or-comma and used for an implied
     * "and" match, initial substring wildcarding for the last field and exact
     * (but case-insensitive) match for other fields. "Hamilton, Josh" would
     * become the search "+Hamilton +Josh*" (matching "Joshua Hamilton"), and
     * "Josh Hamil" would become the search "+Josh +Hamil*" (matching "Josh
	 * Hamilton").  Similarly, if the beginning (or all) of a student's display uid matches the
     * query, the student's enrollment will be included in the returned set.
     * "joshh" would match both the UID "joshham@miskotonic.edu" and the UID
     * "joshhor@miskotonic.edu".
	 *
	 * @return a set of matching enrollments or the empty set
	 */
	public Set findEnrollmentsByStudentNameOrDisplayUid(String gradebookUid, String studentNameQuery);

    /**
     * Looks up a user based on their uid.
     *
     * TODO Eliminate this unnecessarily broad method. This is used only to obtain a grader's name based on their user UID.
     * It should be restricted to people who have access to the gradebook.
     * One potential issue: Administrators may have grading rights without an explicit participation record.
     * The safest way to handle this is likely an Authn method like "getUser(Object whatToAuthn)" which returns
     * the User object for the current user.
     *
     * @param userUid
     * @return
     */
    public User getUser(String userUid) throws UnknownUserException;
}




@@ -3472,68 +3472,158 @@
 ODO 
-Eliminate this unnecessarily broad method. This is used only
+Decide what to do with this dangerously broad method. This is used only in two places:%0A     *%0A     * 1) When displaying a grade history log, it's used
  to 
@@ -3681,378 +3681,594 @@
   * 
-It sh
+   In this case, it c
 ould
+n't
  be re
-stricted to people who have access to the gradebook.%0A     * One potential issue: Administrators may have grading rights without an explicit participation record.%0A     * The safest way to h
+placed by checking just people who play an explict part in the%0A     *    gradebook, since Authz may have let administrators change scores, or the grader may no longer play%0A     *    an active part. The only workaround is to pick up the currently authorized user's name 
 and
-le
  th
-is is likely an Authn method like %22getUser(Object whatToAuthn)%22 which returns%0A     * the User object for the current us
+en%0A     *    store it as an additional field in the grade history log.%0A     * 2) It's used to display the student's name in the student view. This case could be taken care of eith
 er
-.
 %0A     *
-%0A
     
- * @param userUid
+by supporting a CourseManagement getEnrollmentForUserUid() method or an Authn
 %0A     * 
 @ret
@@ -4263,23 +4263,54 @@
 %0A     * 
-@r
+   g
 et
+C
 ur
-n
+rentUserDisplayName() method.
 %0A     */

Comment on the problematic getUser method