One minute example: download

The example below explains how to send a download to the browser. Again, see how simple this code is:

@Controller
public class ProfileController {
    
    public File picture(Profile profile) {
        return new File("/path/to/userpic." + profile.getId()+ ".jpg");
    }
}

Adding more download info

If you want to add more information about download, you can return a FileDownload:

@Controller
public class ProfileController {
    public Download picture(Profile profile) {
        File file = new File("/path/to/userpic." + profile.getId()+ ".jpg");
        String contentType = "image/jpg";
        String filename = profile.getName() + ".jpg";

        return new FileDownload(file, contentType, filename);
    }
}

For situations where you have a InputStream, you can use InputStreamDownload, as you can see below:

public Download picture(Profile profile) {
    InputStream stream = [...];
    String contentType = "image/jpg";

    return new InputStreamDownload(stream, contentType, filename);
}

You can also use a ByteArrayDownload, if you have a byte array as described below:

public Download picture(Profile profile) {
    byte[] pictureContent = [...];
    String contentType = "image/jpg";

    return new ByteArrayDownload(pictureContent, contentType, filename);
}

You can also put a list of files to download, so will sent to the browser compressed as Zip archive.

public Download pictures() {
    Path pic01 = new File("/path/to/the/pic01.jpg").toPath();
    Path pic02 = new File("/path/to/the/pic02.jpg").toPath();
    return new ZipDownload("pics.zip", pic01, pic02);
}

Using DownloadBuilder

DownloadBuilder is a class to help you to create instances for Download, using a fluent interface. To create a FileDownload you can write this code:

FileDownload download = DownloadBuilder.of(myFile)
    .withFileName("resume.txt") // optional, default is File.getName()
    .withContentType("text/plain") // optional, null will not sent
    .downloadable() // optional, default is inline content
    .build();

Upload

To activate upload support it’s necessary to add commons-upload and commons-io artifacts in your classpath. You can see more info here.

**Note: ** Upload only works with methods annotated with @Post. @Get, @Put and others are not supported.

One minute example: upload

To receive an uploaded file in your controller, you need to use a parameter as UploadedFile. The UploadedFile class contains the file content as an InputStream. So you can copy to disk (or another location) too easily as you can see in the example below:

public void updatePhoto(Profile profile, UploadedFile photo) {
    File savedPhoto = new File("/path/to/photo/repository", photo.getFileName());
    photo.writeTo(savedPhoto);
    dao.assign(savedPhoto, profile);
}

Overriding upload settings

If you want to change default upload settings, you can do using two ways.

The first way is extending DefaultMultipartConfig class. This is useful if you want to change default temporary directory or max upload size.

The default value for an uploaded file is 2MB, and the same value for sum of all uploaded files. But you can easily change this settings as you can see below.

@Specializes
@ApplicationScoped
public class CustomMultipartConfig extends DefaultMultipartConfig {

    // validates sum of all files up to 50MB
    public long getSizeLimit() {
        return 50 * 1024 * 1024;
    }

    // validates each file up to 20MB
    public long getFileSizeLimit() {
        return 20 * 1024 * 1024;
    }

}

The second way is using UploadSizeLimit annotation. This way allow you to change settings for only one method. In the example below we are configuring upload to allow only files less than 10MB and the total upload should less than 40MB:

@UploadSizeLimit(sizeLimit=40 * 1024 * 1024, fileSizeLimit=10 * 1024 * 1024)
public void updatePhoto(Profile profile, UploadedFile photo) {
    [...]
}

The UploadSizeLimit have more priority than global configuration. You can use both, but if a method is annotated with this annotation, global values will ignored.

Changes in form

You need to add the parameter enctype with multipart/form-data value. Without this attribute, the browser cannot upload files:

<form action="myaction" method="post" enctype="multipart/form-data">

Validating upload

When the maximum size for uploaded file exceeds the configured value, VRaptor add a message on the Validator object.