Project maintainers and contributors:

Lukasz Kucharski - lkc@touk.pl
Rafa? Pietrasik - rpt@touk.pl
Micha? Soko?owski - msk@touk.pl

Mailing list

upload-library@touk.pl

Compilation and building

You can check out project from https://top.touk.pl/svn/file-upload-library/trunk
to compile it:

mvn clean install

in upload-usage-example module, you're gonna get *.war web application which you can deploy to j2ee container to see what's what (So far tested with Jboss adn Tomcat).

Downloading

Current development version is 0.0.1-SNAPSHOT and you can download it from here: http://top.touk.pl/maven2/snapshot/

"Useful info"
If you're TouK employee and you're using nexus you don't have to do anything. Just include it in your pom.xml file.

If you're using maven add dependency:

<dependency>
            <groupId>pl.touk.top</groupId>
            <artifactId>file-upload-server-lib</artifactId>
            <version>${project.version}</version>
        </dependency>
        <dependency>
            <groupId>pl.touk.top</groupId>
            <artifactId>file-upload-gwtclient-lib</artifactId>
            <version>${project.version}</version>
        </dependency>

to your pom.xml file

System and library requirements.

JAVA >=1.5
Spring >= 2.0
GWT >= 1.5.3 - if you're using GWT widgets on client side (may work on previous version but I did not test it this way)
GXT >= 1.2 - if you're using GWT widgets on client side
Linux OS - if your're building from source (project should build on Windows machines but I didn't try it)

Usage guide

Overview

This section describe usage scenarios for two most popular cases:

first, when you need to upload and then download single file and associate it with some entity within your bussiness model.
second, when you need to upload multiple files, see list of uploaded files (in grid) and then associate all those files with bussiness object in your domain.

How this works

File upload/download is fairly straightforward and common task, you don't have to do much to use this library unless you want to have some custom functions in your project.
Main components of this library are:

server side Spring controller which will be bound to some url in you application. This controller will take care of handling download and upload requests that come from browser.
client side widgets that know how to talk to server side controller (UploadForm and DownloadLink). Currently the only widget implementation is based on GWT and commercial GXT library
Warning
You need commercial GXT licence to use widgets written in GXT

Common tasks for all scenarios

In your spring configuratino context file define controller that will service upload/download request and bind it do default url that is expected by frontend widgets using eg. SimpleUrlHandlerMapping facility.

<!-- File Upload and Download controller -->
    <!-- Standard configuration assumes, that it is deployed under this url: yourappcontext/fileUploadDownload.do -->
    <bean id="fileUploadController" class="pl.touk.top.fileupload.server.spring.UploadDownloadController">
        <property name="fileStore" ref="uploadDownloadTestProcessor"/>
    </bean>

<!--Bind your controller to default url expected by fronted widgets-->
     <bean class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
        <property name="mappings">
            <map>
                 <entry key="/fileUploadDownload.do" value-ref="fileUploadController" />
            </map>
        </property>
    </bean>

After you define upload/download controller you need to define FileStore abstraction so that UploadDownloadController knows how to persist your binary data. For now there is stubbed implementation of this service bundled with distribution that basically does nothing useful with your files. You have to implement your own IBaseFileStore for now. Implement this service and define it in your spring context file like this:

<bean id="fileStore" class="pl.touk.top.fileupload.server.BaseFileStoreStubImpl">
    </bean>

You do not have to inject this into controller manually, upload/download controller will try to look this service up automatically and use it if it finds only one service of this type in your spring application context.

Simple scenario upload/download single file and associate it with your domain object

Make sure you followed prerequisite directions in common-tasks section. After that you can use widget to upload files to your IBaseFileStore implementation like this:

public class ExampleEntryPoint implements EntryPoint {
// ------------------------ INTERFACE METHODS ------------------------


// --------------------- Interface EntryPoint ---------------------

    public void onModuleLoad() {
        Viewport vp = new Viewport();
        vp.setLayout(new FitLayout());
        RootPanel.get().add(vp);

        SingleFileUploadPanel panel = new SingleFileUploadPanel();
        vp.add(panel);
    }

// -------------------------- INNER CLASSES --------------------------

    class SingleFileUploadPanel extends LayoutContainer {
        public SingleFileUploadPanel() {
            FileUploadForm fuf = new FileUploadForm() {
                @Override
                protected void onSuccess(String message, FileDescriptorGxt fdg) {
                    GWT.log("Saved file " + fdg.getFileName() + " assigned FileStoreId is: " + fdg.getFileId(), null);
                }
            };

            this.add(fuf);
        }
    }
}

Main library abstractions

To support simple download/upload of single file you need to implement IBaseFileStore interface. This is most primitive interface that you'll ever need to implement for library to be able to store and retrieve your binary content. Read javadoc to see implementation details. Library contains few predefined implementations of this interface (you can see them in the diagram below). Those implementations are:

BaseFileStoreStubImpl - stubbed implementation for testing purposes
TODO - someone make this list complete

Then you use UploadDownloadController which looks up you IFileStore implementation to service upload/download request which come from browser

Home of file upload library