Skip to content

MIGRATION_GUIDE.md

Latest commit

 

History

History
190 lines (139 loc) · 5.54 KB

MIGRATION_GUIDE.md

File metadata and controls

190 lines (139 loc) · 5.54 KB
Raw

Migration Guide: StreamResource to DownloadHandler

Overview

Starting with version 3.1.0, Grid Exporter Add-on introduces new DownloadHandler-based methods to replace the deprecated StreamResource methods. This migration is necessary for forward compatibility: as of Vaadin 25, StreamResource is deprecated and marked for removal, and it will be removed in a future Vaadin release.

What's Changing?

The Grid Exporter Add-on now provides two sets of methods:

  • Old API (Deprecated): Methods returning StreamResource or GridExporterStreamResource
  • New API (Recommended): Methods returning DownloadHandler

Backward Compatibility

✅ Your existing code will continue to work! The old methods are deprecated but still functional. You can migrate at your own pace.

Migration Steps

1. Update Vaadin Version

The new DownloadHandler API requires Vaadin 24.8.0 or later.

pom.xml:

<properties>
    <vaadin.version>24.8.0</vaadin.version>
</properties>

2. Update Method Calls

Replace the deprecated get*StreamResource() methods with the new get*DownloadHandler() methods.

Excel Export

Before:

Anchor excelLink = new Anchor("", FontAwesome.Regular.FILE_EXCEL.create());
excelLink.setHref(exporter.getExcelStreamResource());
excelLink.getElement().setAttribute("download", true);

After:

Anchor excelLink = new Anchor("", FontAwesome.Regular.FILE_EXCEL.create());
excelLink.setHref(exporter.getExcelDownloadHandler());
excelLink.getElement().setAttribute("download", true);

DOCX Export

Before:

exporter.getDocxStreamResource()
exporter.getDocxStreamResource(customTemplate)

After:

exporter.getDocxDownloadHandler()
exporter.getDocxDownloadHandler(customTemplate)

PDF Export

Before:

exporter.getPdfStreamResource()
exporter.getPdfStreamResource(customTemplate)

After:

exporter.getPdfDownloadHandler()
exporter.getPdfDownloadHandler(customTemplate)

CSV Export

Before:

exporter.getCsvStreamResource()

After:

exporter.getCsvDownloadHandler()

3. Update Custom Export Links (if applicable)

If you're creating custom export links instead of using auto-attached buttons:

Before:

GridExporter<Person> exporter = GridExporter.createFor(grid);
exporter.setAutoAttachExportButtons(false);

Anchor customLink = new Anchor("", "Download Excel");
customLink.setHref(exporter.getExcelStreamResource().forComponent(customLink));

After:

GridExporter<Person> exporter = GridExporter.createFor(grid);
exporter.setAutoAttachExportButtons(false);

Anchor customLink = new Anchor("", "Download Excel");
customLink.setHref(exporter.getExcelDownloadHandler().forComponent(customLink));

Note: forComponent(...) is optional. It binds the download to a component so that the component is automatically disabled while the export runs (when setDisableOnClick(true) is enabled). If you don't need that behavior, you can omit it: customLink.setHref(exporter.getExcelDownloadHandler());

API Comparison

Old Method (Deprecated) New Method Notes
getExcelStreamResource() getExcelDownloadHandler() Excel export
getExcelStreamResource(String) getExcelDownloadHandler(String) Excel with template
getDocxStreamResource() getDocxDownloadHandler() DOCX export
getDocxStreamResource(String) getDocxDownloadHandler(String) DOCX with template
getPdfStreamResource() getPdfDownloadHandler() PDF export
getPdfStreamResource(String) getPdfDownloadHandler(String) PDF with template
getCsvStreamResource() getCsvDownloadHandler() CSV export

Features Preserved

All existing features continue to work with the new API:

  • ✅ Concurrent download control
  • ✅ Download timeouts
  • ✅ Button disable/enable during download
  • ✅ Custom templates
  • ✅ All export formats (Excel, DOCX, PDF, CSV)
  • ✅ Custom columns and headers
  • ✅ Hierarchical data support

Timeline

  • Version 3.1.0: New DownloadHandler methods introduced, old methods deprecated
  • A future release: Old StreamResource methods will be removed

Need Help?

If you encounter any issues during migration, please:

  1. Check that you're using Vaadin 24.8.0 or later
  2. Review the deprecation warnings in your IDE
  3. Open an issue on GitHub

Example: Complete Migration

Before (Version 3.0.x):

Grid<Person> grid = new Grid<>(Person.class);
grid.setItems(people);

GridExporter<Person> exporter = GridExporter.createFor(grid);
// Auto-attached buttons use StreamResource internally

After (Version 3.1.0+):

Grid<Person> grid = new Grid<>(Person.class);
grid.setItems(people);

GridExporter<Person> exporter = GridExporter.createFor(grid);
// Auto-attached buttons now use DownloadHandler internally
// No code changes needed if using auto-attached buttons!

Custom Implementation:

Grid<Person> grid = new Grid<>(Person.class);
grid.setItems(people);

GridExporter<Person> exporter = GridExporter.createFor(grid);
exporter.setAutoAttachExportButtons(false);

// Create custom export buttons
Anchor excelBtn = new Anchor("", "Excel");
excelBtn.setHref(exporter.getExcelDownloadHandler());
excelBtn.getElement().setAttribute("download", true);

Anchor pdfBtn = new Anchor("", "PDF");
pdfBtn.setHref(exporter.getPdfDownloadHandler());
pdfBtn.getElement().setAttribute("download", true);

add(excelBtn, pdfBtn);