CSV Import Wizard

The CSV Import Wizard is a generic GWT widget for the import of a CSV file in a destination system. The widget has been developed using the GXT 2.2.x framework.

Introduction

The CSV Import Wizard aims to help all the components that needs to integrate a CSV import procedure in their system.

The CSV import is made of those main steps:

• the CSV file retrieving from a source like a local file system, a user workspace or an FTP site.
• the definition of CSV parsing information like the presence of a header, the file encoding, the separator.
• the final import in a target system like a service in the infrastructure or an FTP site.

The widget is pluggable to support different CSV sources and different import target.

CSV Source

The goal of a CSV Source is to transfer locally to the widget (in a tmp folder in the portal) the CSV file to import. The transfer operation can be a long one therefore a progress bar can be visualized.

A default local file system source is distributed with the widget. The local source lets the user to upload the file from his computer to the system. The local source accept flat text file or zipped file with the CSV file as unique entry.

A Workspace source can be added through the CSV Import Wizard Workspace component. The Workspace Source uses the Workspace Light Tree to let the user select the item to import. Accepted item are External File both text or zipped as for the local source.

CSV Target

The goal of a CSV Target is to import the CSV file in the destination system. In other words is the bridge between the widget and the destination system.

The hosting application have to define his target in order to manage the import finalization. The CSVTarget interface is composed by two methods:

	/**
	 * Returns the target id.
	 * @return
	 */
	public String getId();
 
	/**
	 * Start the CSV import.
	 * @param csvFile the csv file.
	 * @param parserConfiguration the parser configuration.
	 * @param columnToImportMask a mask for column to import selection
	 * @param operationProgress
	 */
	public void importCSV(File csvFile, CSVParserConfiguration parserConfiguration, boolean[] columnToImportMask, OperationProgress operationProgress);

The getId method returns the id that we need to pass to the ImportWizard constructor.

The importCSV method is called when the final step is reached. The interface implementation is in charge of updating the import progress state using the OperationProgress object.

Installation

In order to use the widget you need to perform those steps:

1. add the widget library as project dependency
2. add this entry to your <project>.gwt.xml file:

   <inherits name='org.gcube.portlets.user.csvimportwizard.CSVImportWizard'/>

3. add those entries to your web.xml files:

    <servlet> 
     	<servlet-name>CSVImportService</servlet-name>
		<servlet-class>org.gcube.portlets.user.csvimportwizard.server.CSVImportServiceImpl</servlet-class>
    </servlet>
 
    <servlet-mapping>
       <servlet-name>CSVImportService</servlet-name>
       <url-pattern>/[[APPLICATION NAME]]/CSVImportService</url-pattern>
    </servlet-mapping>
 
    <servlet> 
     	<servlet-name>CSVServlet</servlet-name>
		<servlet-class>org.gcube.portlets.user.csvimportwizard.server.CSVServlet</servlet-class>
    </servlet>
 
    <servlet-mapping>
       <servlet-name>CSVServlet</servlet-name>
       <url-pattern>/[[APPLICATION NAME]]/CSVServlet</url-pattern>
    </servlet-mapping>

where [APPLICATION NAME] is your gwt application name.

If you want to use the local file system source you need to add also those lines:

 
    <servlet> 
     	<servlet-name>LocalUploadServlet</servlet-name>
	<servlet-class>org.gcube.portlets.user.csvimportwizard.server.local.LocalUploadServlet</servlet-class>
    </servlet>
 
    <servlet-mapping>
       <servlet-name>LocalUploadServlet</servlet-name>
       <url-pattern>/[[APPLICATION NAME]]/LocalUploadServlet</url-pattern>
    </servlet-mapping>

Installation of the Workspace Source

To use the Wokspace Source you need to add this line to your gwt.xml file:

<inherits name="org.gcube.portlets.user.csvimportwizard.ws.CSVImportWizardWorkspace" />

Then you have to add those lines to the web.xml file:

 
	<!-- Servlets for CSV Import Wizard Workspace-->
	<servlet>
		<servlet-name>CSVImportServiceWorkspace</servlet-name>
		<servlet-class>org.gcube.portlets.user.csvimportwizard.ws.server.ImportWizardWSServiceImpl</servlet-class>
	</servlet>
 
	<servlet-mapping>
		<servlet-name>CSVImportServiceWorkspace</servlet-name>
		<url-pattern>/[APPLICATION NAME]/CSVImportServiceWorkspace</url-pattern>
	</servlet-mapping>

where [APPLICATION NAME] is your gwt application name.

Finally you have to modify the web.xml file in order to support the Workspace Light Tree as explained here.

Example of use

Here an example of use. You first have to register your CSV target. I suggest to call it on the init method of your servlet:

	CSVTargetRegistry.getInstance().add(new DemoCSVTarget());

In our example we are registering the DemoCSVTarget target.

Then on the UI side:

	ImportWizard importWizard = new ImportWizard("DemoCSVTarget");
	importWizard.show();

We have created the ImportWizard using the target id as parameter.

If you want to listen the main events on the wizard you can add a WizardListener:

	importWizard.addListener(new WizardListener() {
 
		@Override
		public void failed(Throwable throwable, String reason, String details) {
			System.out.println("FAILED reason: "+reason+" details: "+details+" throwable: "+throwable);
		}
 
		@Override
		public void completed() {
			System.out.println("COMPLETED");
		}
 
		@Override
		public void aborted() {
			System.out.println("ABORT");
		}
	});

If you have installed the Workspace Source and you want to use it you can construct the ImportWizard like this:

	ImportWizard importWizard = new ImportWizard("DemoCSVTarget", LocalSource.INSTANCE, WorkspaceSource.INSTANCE);
	importWizard.show();