UnexpectedPage (default)

HtmlUnit handles all unknown content similar to known content - the content is wrapped in a page object and the page is placed inside the window. For all unknown content HtmlUnit uses the UnexpectedPage. In most cases the UnexpectedPage replaces the current (Html)page in the current window, but in some cases a new additional window gets opened (e.g. clicking an anchor with a download attribute defined).

You can then access the plain content stream from the enclosed UnexpectedPage.

try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
    HtmlPage page = webClient.getPage(uri);
    WebWindow window = page.getEnclosingWindow();

    .... // click some anchor/button that forces a file download

    UnexpectedPage downloadPage = (UnexpectedPage) window.getEnclosedPage();

    try (InputStream downloadedContent = downloadPage.getInputStream()) {

        // e.g. save the input to a local file
        .... 
}

In the case the download is placed inside a new window you can do something like this:

WebWindow newWindow = webClient().getWebWindows().get(webClient().getWebWindows().size() -1);

AttachmentHandler

If you don't like the default behavior, you can implement your own way of processing. This is done by registering your own implementation of the AttachmentHandler interface in the WebClient.

The AttachmentHandler based download support works in addition to the default UnexpectedPage based support. This means, if your AttachmentHandler does not handle the content, the webClient will fall back to the default solution and place an UnexpectedPage inside the window. You can overwrite the method isAttachment() in your AttachmentHandler to only handle dedicated responses - the default implementation only detects responses having a content-disposition header of type 'attachment' or having no content-disposition header at all and and content-type header of 'application/octet-stream'.

The method

boolean handleAttachment(final WebResponse response, final String attachmentFilename)

1. true signals the rest of the code the response is handled by your code; there is NO replacement of the current page with an UnexpectedPage and also the method

   void handleAttachment(Page page, final String attachmentFilename)

   from you AttachmentHandler is NOT called.
2. By returning false, the response will be processed further like this:
   • at first a new window will be created,
   • next the UnexpectedPage will be build,
   • then the method

     void handleAttachment(Page page, final String attachmentFilename)

     from you AttachmentHandler is called and
   • finally the UnexpectedPage will be placed inside the new window.

The following example code collects the attachment-response inside a list without replacing the content of the current window.

final List<WebResponse> attachments = new ArrayList<>();

try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {

        client.setAttachmentHandler(new AttachmentHandler() {
            @Override
            public boolean handleAttachment(final WebResponse response, final String attachmentFilename) {
                attachments.add(response);
                return true;
            }

            @Override
            public void handleAttachment(final Page page, final String attachmentFilename) {
                throw new IllegalAccessError("handleAttachment(Page, String) called");
            }
        });

    // start browsing
    HtmlPage page = webClient.getPage(uri);

    ....
}

For more details check the AttachmentHandler javadoc.

There is one special case - if you click an anchor with the download attribute set, the processing of the request is passed to the AttachmentHandler (if there is one) without calling the isAttachment() method. The response is always treated as attachment in this case.