Index: lams_learning/src/java/org/lamsfoundation/lams/learning/export/service/IExportPortfolioService.java =================================================================== diff -u -r4e143f1522cf63a2c32a7cb22a3c1ea57853284b -re73df80681bcff3273645d9de040e6d328240dae --- lams_learning/src/java/org/lamsfoundation/lams/learning/export/service/IExportPortfolioService.java (.../IExportPortfolioService.java) (revision 4e143f1522cf63a2c32a7cb22a3c1ea57853284b) +++ lams_learning/src/java/org/lamsfoundation/lams/learning/export/service/IExportPortfolioService.java (.../IExportPortfolioService.java) (revision e73df80681bcff3273645d9de040e6d328240dae) @@ -23,9 +23,6 @@ /* * Created on Aug 30, 2005 - * - * TODO To change the template for this generated file go to - * Window - Preferences - Java - Code Style - Code Templates */ package org.lamsfoundation.lams.learning.export.service; @@ -64,27 +61,78 @@ */ public interface IExportPortfolioService { + /** + * This is the main method that performs the export for the teacher. + * It will get the list of ordered activities from the learning design + * and will setup the portfolios for each activity. Returns an array of + * Portfolio objects, in which the web layer can iterate through the array + * of portfolios to display the links to each activity. + * @param lesson The specific instance of the LearningDesign and Class. + * @return Portfolio[] The array of portfolio objects. + */ public Portfolio[] exportPortfolioForTeacher(Lesson lesson); - - //public Portfolio[] exportPortfolioForStudent(LearnerProgress learnerProgress, User user, boolean anonymity); - - //public Portfolio[] exportPortfolioForStudent(Lesson lesson, User user, boolean anonymity); - + + /** + * The main method that performs the export for the student. + * It will get the list of activities that the user has completed + * and will setup the portfolios for each activity. + * @param learnerProgressId The learner progress id, which is used to determine the learner progress and the + * list of activities completed by the learner. + * @param user The learner. + * @param anonymity The anonymity flag, is true, then anonymity is on, otherwise username would be visible. + * @return Portfolio[] The array of portfolio objects. + */ public Portfolio[] exportPortfolioForStudent(Long learnerProgressId, User user, boolean anonymity); + /** + * A helper method that sets up the export url for the activity. Will go through all key-value pairs + * in this map, and append it to the url given. + * @param parametersToAppend Map containing parameter name-parameter value pairs, to be appended to the end of the url + * @param url The url in which the parameters should be appended. + * @return The url with all parameters appended. + */ public String setupExportUrl(Map parametersToAppend, String url); + /** + * Obtains the Tool from the ToolActivity and creates a portfolio object with properties activityId, activityName, + * activityDescription, exportURL set to the value of the ToolActivity's properties activityId, toolDisplayName + * (retrieved from Tool object) , title, exportPortfolioUrl respestively. + * + * @param activity The Tool Activity + * @return a Portfolio object + */ public Portfolio createPortfolio(ToolActivity activity); - public Portfolio[] setupPortfolios(Vector activitySet, ToolAccessMode accessMode, User user) throws LamsToolServiceException; + /** + * This method will iterate through the list of ordered activities and create a Portfolio + * object for each activity. It will set up most of the properies of the Portfolio object. + * This method is used regardless of whether the export is being done by the teacher or + * the student. However, if the export is being done be the teacher, the User object should + * be null. + * + * + * @param orderedActivityList The ordered activity list to iterate through + * @param accessMode The tool access mode, either Teacher or Learner. + * @param user The learner, or null if export is being done by the teacher. + * @return the array of Portfolio objects + * @throws LamsToolServiceException + */ + public Vector setupPortfolios(Vector orderedActivityList, ToolAccessMode accessMode, User user) throws LamsToolServiceException; + /** + * Returns the ordered activity list (ordered by the ActivityOrderComparator) + * containing all activities present in the learning design. The list will + * only contain Tool Activities. If it comes across a Complex Activity, it + * will only add its child activities in the ordered list. + * @param learningDesign The learning design in which the export is being done. + * @return Vector the ordered list of activities. + */ public Vector getOrderedActivityList(LearningDesign learningDesign); + - //public Vector getOrderedActivityList(LearnerProgress learnerProgress); - /** - * Returns the ordered activity list containing the list of activities - * completed by the leaner. + * Returns the ordered activity list (ordered by the ActivityOrderComparator) + * containing the list of activities completed by the learner. * The reason why the learnerProgressId is passed as a parameter (as opposed * to an actual LearnerProgress object, is so that in the same transaction, we * can obtain the LearnerProgress object (from the learnerProgressId) and then @@ -97,10 +145,50 @@ */ public Vector getOrderedActivityList(Long learnerProgressId); - public boolean createTempDirectory(String directoryName); + /** + * Creates a directory with the name directoryName. + * + * @param directoryName The name and location of the directory. + * @return true if the directory has been created, false otherwise + */ + // public boolean createTempDirectory(String directoryName); + + /** + * Zips up the directory specified by directoryToZip and + * saves it in the filename given by filename. + * + * @param filename + * @param directoryToZip + * @return + */ public String zipPortfolio(String filename, String directoryToZip); -//public boolean createDirectory( + /** + * Iterates through the list of portfolios, creates a subdirectory for each of the tools + * and appends the temporary export directory to the export url. It will then call each + * tool to write its files in the subdirectory. + * The tool returns the name of the main html file written, the portfolio property + * mainFileName is set to this value. + * + * @param portfolios + * @return An array of portfolios that can be used to generate the main export page. + */ + public Portfolio[] doExport(Vector portfolios, String tempDirectoryName); + /** + * This method is responsible for the call to the tool to export their portfolio via the export url. + * It uses a HttpURLConnection to connect to the export url of each tool and returns the filename + * of the main export page of the tool. + * + * @param tool The portfolio object, which contains the exportUrl in which to connect to. + * @return The main file name of the tool's page. + */ + public String exportToolPortfolio(Portfolio tool); + /* public Portfolio[] exportPortfolioForStudent(LearnerProgress learnerProgress, User user, boolean anonymity); + + public Portfolio[] exportPortfolioForStudent(Lesson lesson, User user, boolean anonymity); + + public Vector getOrderedActivityList(LearnerProgress learnerProgress); */ + }