Module org.htmlunit
Package org.htmlunit.attachment

Class Attachment

java.lang.Object
org.htmlunit.attachment.Attachment
public class Attachment extends Object
An attachment represents a page received from the server which contains a Content-Disposition=attachment header.
Author:
Bruce Chapman, Sudhan Moghe, Daniel Gredler, Ronald Brill, Lai Quang Duong, Vidya m

  • Constructor Summary

    Constructors
    Constructor
    Description
    Attachment(Page page)
    Creates a new attachment for the specified page.
    Attachment(Page page, String attachmentFilename)
    Creates a new attachment for the specified page.

  • Method Summary

    Modifier and Type
    Method
    Description
    Page
    getPage()
    Returns the attached page.
    String
    getSuggestedFilename()
    Returns the file name for this attachment, the way a real browser would suggest it in its file save dialog (or use it for an automatic download).
    static String
    getSuggestedFilename(String contentDispositionHeader)
    Returns the file name suggested by the given Content-Disposition header, or null if the header does not contain a usable file name.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Attachment

      public Attachment(Page page)
      Creates a new attachment for the specified page.
      Parameters:
      page - the attached page

    • Attachment

      public Attachment(Page page, String attachmentFilename)
      Creates a new attachment for the specified page.
      Parameters:
      page - the attached page
      attachmentFilename - the file name of this attachment

  • Method Details

    • getPage

      public Page getPage()
      Returns the attached page.
      Returns:
      the attached page

    • getSuggestedFilename

      public String getSuggestedFilename()
      Returns the file name for this attachment, the way a real browser would suggest it in its file save dialog (or use it for an automatic download).

      If a file name was given explicitly when this attachment was created (for example because the download was triggered by an anchor with a download attribute, or the name was already derived from the response by the WebClient), this name is returned as it is. Otherwise the name is taken from the Content-Disposition header of the response of the attached page; see getSuggestedFilename(String) for the details.

      Like a browser, this method does not use the URL of the request as fallback. If you need a name in this case, you have to build one on your own (for example from the URL, as the DownloadingAttachmentHandler does).

      Returns:
      the attachment's suggested filename, or null if none was suggested

    • getSuggestedFilename

      public static String getSuggestedFilename(String contentDispositionHeader)
      Returns the file name suggested by the given Content-Disposition header, or null if the header does not contain a usable file name.

      This method does what the real browsers do when they choose the name of a downloaded file, so the result is a name that is safe to use for saving the file, and not the plain value sent by the server:

      • The header is parsed by the ContentDispositionParser (RFC 6266, RFC 2183). Parameter names are case-insensitive, the value can be a token or a quoted string (with escapes), and a ; inside a quoted string does not end the value.
      • The extended parameter filename* (RFC 8187, e.g. filename*=UTF-8''gr%C3%B6%C3%9Fe.txt) wins over filename, whatever the order in the header is. Supported charsets are UTF-8 and ISO-8859-1; if the extended value is not usable, the plain filename is used.
      • Characters that are not allowed in file names on at least one platform (\ / : * ? " < > | and control characters) are replaced by an underscore (see FileUtils.sanitizeFilename(String)). This also makes sure a path in the header can never be used to leave the download directory: ../../evil.txt becomes _.._evil.txt.
      • Leading dots and white space (no hidden files) and trailing dots and white space are removed.
      • If nothing is left, for example because the header has no file name or an empty one, the result is null. A browser would use the last part of the URL in this case, this has to be done by the caller.

      Not all browsers behave exactly the same in some corner cases. If the extended value uses an unknown charset, this method behaves like Chrome and Edge and ignores the extended value; Firefox decodes the value anyway. For an invalid percent encoding, Chrome and Edge keep the broken value as it is, while Firefox ignores the extended value; this method behaves like Firefox and falls back to the plain filename.

      Parameters:
      contentDispositionHeader - the value of the Content-Disposition header, can be null
      Returns:
      the sanitized file name, or null if none was suggested