5.20. ファイルダウンロード

Caution

本バージョンの内容は既に古くなっています。最新のガイドラインはこちらからご参照ください。

5.20.1. Overview

本節では、Springでクライアントにサーバからファイルをダウンロードする機能について説明する。
Spring MVCのViewで、ファイルのレンダリングを行うことを推奨する。

Note

コントローラクラスで、ファイルレンダリングのロジックを持たせることは推奨しない。

理由としては、コントローラの役割から逸脱するためである。 また、コントローラから分離することで、Viewの入れ替えが、容易にできる。

ファイルのダウンロード処理の概要を、以下に示す。

  1. DispatchServletは、コントローラへファイルダウンロードのリクエストを送信する。
  2. コントローラは、ファイル表示の情報を取得する。
  3. コントローラは、Viewを選択する。
  4. ファイルレンダリングは、Viewで行われる。
SpringベースのWebアプリケーションで、ファイルをレンダリングするため、
本ガイドラインでは、カスタムビューを実装することを推奨する。
Spring フレームワークでは、カスタムビューの実装に
org.springframework.web.servlet.View インタフェースを提供している。

PDFファイルの場合
Springから提供されているorg.springframework.web.servlet.view.document.AbstractPdfView
クラスは、modelの情報を用いてPDFファイルをレンダリングするときに、サブクラスとして利用するクラスである。

Excelファイルの場合
Springから提供されているorg.springframework.web.servlet.view.document.AbstractXlsxView
クラスは、modelの情報を用いてExcelファイルをレンダリングするときに、サブクラスとして利用するクラスである。

Spring では上記以外にも、いろいろなViewの実装を提供している。
Viewの技術詳細は、Spring Reference View technologiesを参照されたい。
共通ライブラリから提供している、org.terasoluna.gfw.web.download.AbstractFileDownloadViewは、
任意のファイルをダウンロードするために使用する抽象クラスである。
PDFやExcel形式以外のファイルをレンダリングする際に、本クラスをサブクラスに定義する。

5.20.2. How to use

5.20.2.1. PDFファイルのダウンロード

PDFファイルのレンダリングには、Springから提供されている、
org.springframework.web.servlet.view.document.AbstractPdfViewを継承したクラスを作成する必要がある。
コントローラでPDFダウンロードを実装するための手順は、以下で説明する。

5.20.2.1.1. カスタムViewの実装

AbstractPdfViewを継承したクラスの実装例

@Component  // (1)
public class SamplePdfView extends AbstractPdfView {  // (2)

  @Override
  protected void buildPdfDocument(Map<String, Object> model,
          Document document, PdfWriter writer, HttpServletRequest request,
          HttpServletResponse response) throws Exception {  // (3)

      document.add(new Paragraph((Date) model.get("serverTime")).toString());
  }
}
項番 説明
(1)
本例では、@Componentアノテーションを使用して、component-scanの対象としている。
後述する、org.springframework.web.servlet.view.BeanNameViewResolverの対象とすることができる。
(2)
AbstractPdfViewを継承する。
(3)
buildPdfDocumentメソッドを実装する。
AbstractPdfViewは、PDFのレンダリングに、iTextを利用している。
そのため、Mavenのpom.xmlに itextの定義を追加する必要がある。
<dependencies>
    <!-- omitted -->
    <dependency>
        <groupId>com.lowagie</groupId>
        <artifactId>itext</artifactId>
        <exclusions>
            <exclusion>
                <artifactId>xml-apis</artifactId>
                <groupId>xml-apis</groupId>
            </exclusion>
            <exclusion>
                <artifactId>bctsp-jdk14</artifactId>
                <groupId>org.bouncycastle</groupId>
            </exclusion>
            <exclusion>
                <artifactId>jfreechart</artifactId>
                <groupId>jfree</groupId>
            </exclusion>
            <exclusion>
                <artifactId>dom4j</artifactId>
                <groupId>dom4j</groupId>
            </exclusion>
            <exclusion>
                <groupId>org.swinglabs</groupId>
                <artifactId>pdf-renderer</artifactId>
            </exclusion>
            <exclusion>
                  <groupId>org.bouncycastle</groupId>
                  <artifactId>bcprov-jdk14</artifactId>
              </exclusion>
          </exclusions>
      </dependency>
      <dependency>
          <groupId>org.bouncycastle</groupId>
          <artifactId>bcprov-jdk14</artifactId>
          <version>1.38</version>
      </dependency>
</dependencies>

Note

itextのバージョンはSpring IO Platformにて定義されている。

5.20.2.1.2. ViewResolverの定義

org.springframework.web.servlet.view.BeanNameViewResolverとは、 Springのコンテキストで管理されたbean名を用いて実行するViewを選択するクラスである。

BeanNameViewResolverを使用する際は、通常使用する、

  • JSP用のViewResolver(InternalResourceViewResolver)
  • Tiles用のViewResolver(TilesViewResolver)

より先にBeanNameViewResolverが実行されるように定義する事を推奨する。

Note

Spring FrameworkはさまざまなViewResolverを提供しており、複数のViewResolverをチェーンすることができる。 そのため、特定の状況では、意図しないViewが選択されてしまうことがある。

この動作は、ViewResolverに適切な優先順位を設定する事で防ぐことができる。 優先順位の設定方法は、ViewResolverの定義方法によって異なる。

  • Spring Framework 4.1から追加された<mvc:view-resolvers>要素を使用してViewResolverを定義する場合は、子要素に指定するViewResolverの定義順が優先順位となる。(上から順に実行される)
  • 従来通り<bean>要素を使用してViewResolverを指定する場合は、orderプロパティに優先順位を設定する。(設定値が小さいものから実行される)

bean定義ファイル

 <mvc:view-resolvers>
     <mvc:bean-name /> <!-- (1) (2) -->
     <mvc:jsp prefix="/WEB-INF/views/" />
 </mvc:view-resolvers>
項番 説明
(1)
Spring Framework 4.1から追加された<mvc:bean-name>要素を使用して、BeanNameViewResolverを定義する。
(2)
<mvc:bean-name>要素を先頭に定義し、通常使用するViewResolver(JSP用のViewResolver)より優先度を高くする。

Tip

<mvc:view-resolvers>要素はSpring Framework 4.1から追加されたXML要素である。 <mvc:view-resolvers>要素を使用すると、ViewResolverをシンプルに定義することが出来る。

従来通り<bean>要素を使用した場合の定義例を以下に示す。

<bean class="org.springframework.web.servlet.view.BeanNameViewResolver">
    <property name="order" value="0"/>
</bean>

<bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="prefix" value="/WEB-INF/views/" />
    <property name="suffix" value=".jsp" />
    <property name="order" value="1" />
</bean>

orderプロパティに、InternalResourceViewResolverより小さい値を指定し、優先度を高くする。


5.20.2.1.3. コントローラでのViewの指定

BeanNameViewResolverにより、コントローラで”samplePdfView”を返却することで、
Springのコンテキストで管理されたBeanIDにより、”samplePdfView”であるViewが使用される。

Javaソースコード

@RequestMapping(value = "home", params= "pdf", method = RequestMethod.GET)
public String homePdf(Model model) {
        model.addAttribute("serverTime", new Date());
        return "samplePdfView";   // (1)
}
項番 説明
(1)
“samplePdfView” をメソッドの戻り値として返却することで、
Springのコンテキストで管理された、SamplePdfViewクラスが実行される。
上記の手順を実行した後、以下に示すようなPDFを開くことができる。
FILEDOWNLOAD PDF

Picture - FileDownload PDF


5.20.2.2. Excelファイルのダウンロード

EXCELファイルのレンダリングには、Springから提供されている、
org.springframework.web.servlet.view.document.AbstractXlsxViewを継承したクラスを作成する必要がある。
コントローラでEXCELファイルをダウンロードを実装するための手順は、以下で説明する。

5.20.2.2.1. カスタムViewの実装

AbstractXlsxViewを継承したクラスの実装例

@Component  // (1)
public class SampleExcelView extends AbstractXlsxView {  // (2)

    @Override
    protected void buildExcelDocument(Map<String, Object> model,
            Workbook workbook, HttpServletRequest request,
            HttpServletResponse response) throws Exception {  // (3)
        Sheet sheet;
        Cell cell;

        sheet = workbook.createSheet("Spring");
        sheet.setDefaultColumnWidth(12);

        // write a text at A1
        cell = getCell(sheet, 0, 0);
        setText(cell, "Spring-Excel test");

        cell = getCell(sheet, 2, 0);
        setText(cell, (Date) model.get("serverTime")).toString());
    }
}
項番 説明
(1)
本例では、@Componentアノテーションを使用して、component-scanの対象としている。
前述した、org.springframework.web.servlet.view.BeanNameViewResolverの対象とすることができる。
(2)
AbstractXlsxViewを継承する。
(3)
buildExcelDocumentメソッドを実装する。
AbstractXlsxViewは、EXCELのレンダリングに、Apache POIを利用している。
そのため、Mavenのpom.xmlに POIの定義を追加する必要がある。
<dependencies>
    <!-- omitted -->
    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi-ooxml</artifactId>
    </dependency>
    <exclusions>
        <exclusion>
            <groupId>stax</groupId>
            <artifactId>stax-api</artifactId>
        </exclusion>
    </exclusions>
</dependencies>

Note

poi-ooxmlが依存しているstax-apiはJava SEより標準で提供されるようになったため、不要なライブラリである。また、ライブラリの競合が発生する可能性があることから、 <exclusions>要素を追加し、当該ライブラリがアプリケーションに含まれないよう考慮する必要がある。

Note

poi-ooxmlのバージョンはSpring IO Platformにて定義されているものを利用するため、設定例では <version> を省略している。

また、AbstractExcelViewはSpring Framework 4.2から@Deprecatedとなった。そのため、xlsファイルを使用したい場合も同様にAbstractXlsxViewの使用を推奨する。 詳細は、AbstractExcelViewのJavaDocを参照されたい。

5.20.2.2.2. ViewResolverの定義

設定は、PDFファイルをレンダリングする場合と同様である。詳しくは、ViewResolverの定義を参照されたい。

5.20.2.2.3. コントローラでのViewの指定

BeanNameViewResolverにより、コントローラで”sampleExcelView”を返却することで、
Springのコンテキストで管理されたBeanIDにより、”sampleExcelView”であるViewが使用される。

Javaソース

@RequestMapping(value = "home", params= "excel", method = RequestMethod.GET)
public String homeExcel(Model model) {
        model.addAttribute("serverTime", new Date());
        return "sampleExcelView";  // (1)
}
項番 説明
(1)
“sampleExcelView” をメソッドの戻り値として返却することで、
Springのコンテキストで管理された、SampleExcelViewクラスが実行される。
上記の手順を実行した後、以下に示すようなEXCELを開くことができる。
FILEDOWNLOAD EXCEL

Picture - FileDownload EXCEL

5.20.2.3. 任意のファイルのダウンロード

前述した、PDFやEXCELファイル以外のファイルのダウンロードを行う場合、
共通ライブラリが提供している、org.terasoluna.gfw.web.download.AbstractFileDownloadViewを継承したクラスを実装すればよい。
他の形式にファイルレンダリングするために、AbstractFileDownloadViewでは、以下を実装する必要がある。
  1. レスポンスボディへの書き込むためのInputStreamを取得する。
  2. HTTPヘッダに情報を設定する。
コントローラでファイルダウンロードを実装するための手順は、以下で説明する。

5.20.2.3.1. カスタムViewの実装

テキストファイルをダウンロードする例を用いて、説明を行う。

AbstractFileDownloadViewを継承したクラスの実装例

@Component  // (1)
public class TextFileDownloadView extends AbstractFileDownloadView {  // (2)

   @Override
   protected InputStream getInputStream(Map<String, Object> model,
           HttpServletRequest request) throws IOException {  // (3)
       Resource resource = new ClassPathResource("abc.txt");
       return resource.getInputStream();
   }

   @Override
   protected void addResponseHeader(Map<String, Object> model,
           HttpServletRequest request, HttpServletResponse response) {  // (4)
       response.setHeader("Content-Disposition",
               "attachment; filename=abc.txt");
       response.setContentType("text/plain");

   }
}
項番 説明
(1)
本例では、@Componentアノテーションを使用して、component-scanの対象としている。
前述した、org.springframework.web.servlet.view.BeanNameViewResolverの対象とすることができる。
(2)
AbstractFileDownloadViewを継承する。
(3)
getInputStreamメソッドを実装する。
ダウンロード対象の、InputStreamを返却すること。
(4)
addResponseHeaderメソッドを実装する。
ダウンロードするファイルに合わせた、 Content-Dispositionや、ContentTypeを設定する。

5.20.2.3.2. ViewResolverの定義

設定は、PDFファイルをレンダリングする場合と同様である。詳しくは、ViewResolverの定義を参照されたい。

5.20.2.3.3. コントローラでのViewの指定

BeanNameViewResolverにより、コントローラで”textFileDownloadView”を返却することで、
Springのコンテキストで管理されたBeanIDにより、”textFileDownloadView”であるViewが使用される。

Javaソース

@RequestMapping(value = "download", method = RequestMethod.GET)
public String download() {
    return "textFileDownloadView"; // (1)
}
項番 説明
(1)
“textFileDownloadView” をメソッドの戻り値として返却することで、
Springのコンテキストで管理された、TextFileDownloadViewクラスが実行される。

Tip

前述してきたように、SpringはModelの情報をいろいろなViewにレンダリングすることができる。 Springでは、Jasper Reportsのようなレンダリングエンジンをサポートし、さまざまなViewを返却することも可能である。 詳細は、Spring の公式ドキュメントSpring referenceを参照されたい。