Author: fdesbois Date: 2010-06-18 14:46:07 +0000 (Fri, 18 Jun 2010) New Revision: 552 Log: Evo #2018 : Add javadoc for CsvImport component and ImportEngine Modified: trunk/wao-ui/src/main/java/fr/ifremer/wao/ui/components/CsvImport.java trunk/wao-ui/src/main/java/fr/ifremer/wao/ui/data/ImportEngine.java Modified: trunk/wao-ui/src/main/java/fr/ifremer/wao/ui/components/CsvImport.java =================================================================== --- trunk/wao-ui/src/main/java/fr/ifremer/wao/ui/components/CsvImport.java 2010-06-18 14:35:41 UTC (rev 551) +++ trunk/wao-ui/src/main/java/fr/ifremer/wao/ui/components/CsvImport.java 2010-06-18 14:46:07 UTC (rev 552) @@ -19,6 +19,12 @@ import java.util.List; /** + * This component is used to import a {@code csvFile} using a form. The page + * using this component must provide a {@link ImportEngine} to execute the + * import when csv file is uploaded. An event "imported" will be triggered + * after success. The page can use an "onImported(ErrorReport report)" method + * to display errors and informations from import. + * * Created: 18 juin 2010 * * @author fdesbois <fdesbois at codelutin.com> @@ -26,12 +32,15 @@ */ public class CsvImport { + /** Event triggered after form submission success */ static final String EVENT_IMPORTED = "imported"; + /** Label to display on fieldset and in submit button title */ @Parameter(required = true, defaultPrefix = BindingConstants.LITERAL) @Property private String label; + /** engine to execute the import */ @Parameter(required = true) private ImportEngine engine; @@ -50,24 +59,42 @@ @Property private UploadedFile csvFile; + /** + * ON_SUCCESS :: Callback method called when success event was triggered from + * importCsv form submission. The import will be executed using the engine + * in parameter. Errors will be reported in a {@link ErrorReport} object + * to be managed after import success. An event "imported" will be triggered" + * to manage those errors. + */ @Log void onSuccessFromImportCsv() { final ErrorReport errorReport = new ErrorReport(); try { + // Execute import using the engine ImportResults result = engine.execute(csvFile.getStream()); + + // Add info on nbRows imported and refused errorReport.addInfo(result.getNbRowsImported() + " lignes importées, " + result.getNbRowsRefused() + " refusées."); + + // Add import errors List<String> errors = result.getErrors(); errorReport.addError(errors.toArray(new String[errors.size()])); + } catch (WaoBusinessException eee) { + + // Add fatal errors errorReport.addError(eee.getMessage()); } catch (WaoException eee) { + + // Add unpredictable errors String[] errors = manager.getErrorMessages(eee, messages, logger); errorReport.addError(errors); } + // Trigger event "imported" with ErroReport in argument resources.triggerEvent(EVENT_IMPORTED, new Object[] {errorReport}, null); } } Modified: trunk/wao-ui/src/main/java/fr/ifremer/wao/ui/data/ImportEngine.java =================================================================== --- trunk/wao-ui/src/main/java/fr/ifremer/wao/ui/data/ImportEngine.java 2010-06-18 14:35:41 UTC (rev 551) +++ trunk/wao-ui/src/main/java/fr/ifremer/wao/ui/data/ImportEngine.java 2010-06-18 14:46:07 UTC (rev 552) @@ -3,6 +3,7 @@ import fr.ifremer.wao.WaoBusinessException; import fr.ifremer.wao.WaoException; import fr.ifremer.wao.bean.ImportResults; +import fr.ifremer.wao.ui.components.CsvImport; import fr.ifremer.wao.ui.components.Layout; import java.io.InputStream; @@ -10,6 +11,10 @@ import java.util.List; /** + * This interface is used for {@link CsvImport} component to execute an import. + * The page need to implement the {@link #execute(InputStream)} method to use + * the component. + * * Created: 18 juin 2010 * * @author fdesbois <fdesbois at codelutin.com> @@ -17,5 +22,16 @@ */ public interface ImportEngine { + /** + * Excute an import from an {@code input} stream. This method was called + * in {@link CsvImport} when file are successfully uploaded. This method + * to to return an {@link ImportResults} that contains stats and errors + * from import. + * + * @param input InputStream of the file to import + * @return an ImportResults that contains statistics and errors from import + * @throws WaoException for unknown errors + * @throws WaoBusinessException for known errors + */ ImportResults execute(InputStream input) throws WaoException, WaoBusinessException; }