Skip to content

Latest commit

 

History

History
107 lines (64 loc) · 3.2 KB

README.md

File metadata and controls

107 lines (64 loc) · 3.2 KB
Raw

http-content-disposition

Implements generating a HTTP Content-Disposition header conforming to RFC 6266 for the Java language.

Other Java libraries do not adhere to the RFC 6266 standard (JavaMail MimeUtility#encodeWord looks fine on first glance but breaks for more esoteric UTF characters) or come with huge dependency baggage (Spring ContentDisposition comes to mind).

Background

The Content-Disposition header was originally specified to only support a subset of characters of the ISO-8859-1 character set.

Since most systems support more characters, RFC 6266 came into life to adapt some existing old RFC used by emails to the world of HTTP and UTF-8.

Deviance from the RFC

A minor difference is: the RFC requires

  • either the old ISO-8859-1 attribute

  • or the encoded extended attribute.

This library provides both for a much improved compatibility with broken/old clients.

Maven/Gradle dependency

This library is released as a maven artifact on jitpack.io.

<repositories>
    <repository>
        <id>jitpack.io</id>
        <name>jitpack.io-releases</name>
        <url>https://jitpack.io</url>
    </repository>
</repositories>
<dependency>
	<groupId>com.github.HonoluluHenk</groupId>
	<artifactId>http-content-disposition</artifactId>
	<version>see-github-releases</version>
</dependency>

Available versions: see Github releases.

Usage

Basic usage

void addHeader(HttpServletResponse response) {
    HttpContentDisposition header = HttpContentDisposition.builder()
        //.disposition(Disposition.INLINE)
        .disposition(Disposition.ATTACHMENT)
        .filename("I ❤ special characters")
        .build();

    response.addHeader(header.headerName(), header.headerValue());
}

This will generate the HTTP header:

Content-Disposition: attachment; filename="I ? special characters"; filename*=UTF-8''I%20%E2%9D%A4%20special%20characters

The ISO-8859-1 filename is automatically generated by doing simple Charset conversion

Customizations

Conversion to ISO-8859-1

In case you do not want the default character set conversion or want to supply a completely different text, you may supply your implementation of IsoFallback to HttpContentDisposition/the builder.

You may pass a string to the existing OverrideIsoFallback to override the ISO filename completely.

HttpContentDisposition header = HttpContentDisposition.builder()
    .disposition(Disposition.ATTACHMENT)
    .filename("I ❤ special characters")
    .isoFallback(new OverrideIsoFallback("I (heart) special characters"))
    // convenience:
    //.isoFallbackValue("I (heart) special characters")
    .build();

License

GNU Lesser General Public License 3.0 (LGPL-3.0) or later.

See also: LICENSE.txt