1 /*
2 * Copyright (c) 2002-2026 Gargoyle Software Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 * https://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15 package org.htmlunit.attachment;
16
17 import java.io.Serializable;
18
19 import org.htmlunit.HttpHeader;
20 import org.htmlunit.Page;
21 import org.htmlunit.WebResponse;
22 import org.htmlunit.http.ContentDisposition;
23 import org.htmlunit.http.ContentDispositionParser;
24 import org.htmlunit.util.MimeType;
25
26 /**
27 * <p>A handler for attachments, which represent pages received from the server which contain
28 * {@code Content-Disposition=attachment} headers. Normally pages are loaded inline: clicking on
29 * a link, for example, loads the linked page in the current window. Attached pages are different
30 * in that they are intended to be loaded outside of this flow: clicking on a link prompts the
31 * user to either save the linked page, or open it outside the current window, but does not
32 * load the page in the current window.</p>
33 *
34 * <p>HtmlUnit complies with the semantics described above when an <code>AttachmentHandler</code> has
35 * been registered with the {@link org.htmlunit.WebClient} via
36 * {@link org.htmlunit.WebClient#setAttachmentHandler(AttachmentHandler)}. When
37 * no attachment handler has been registered with the <code>WebClient</code>, the semantics described
38 * above to not apply, and attachments are loaded inline. By default, <code>AttachmentHandler</code>s
39 * are not registered with new <code>WebClient</code> instances.</p>
40 *
41 * @author Bruce Chapman
42 * @author Sudhan Moghe
43 * @author Daniel Gredler
44 * @author Ronald Brill
45 * @author Alex Gorbatovsky
46 * @author Lai Quang Duong
47 * @see org.htmlunit.WebClient#setAttachmentHandler(AttachmentHandler)
48 * @see org.htmlunit.WebClient#getAttachmentHandler()
49 * @see <a href="http://www.ietf.org/rfc/rfc2183.txt">RFC 2183</a>
50 */
51 @FunctionalInterface
52 public interface AttachmentHandler extends Serializable {
53
54 /**
55 * Handles the specified attached page. This is some kind of information
56 * that the page was handled as attachment.
57 * This method will only be called if {@link #handleAttachment(WebResponse, String)}
58 * has returned false for the response.
59 * @param page an attached page, which doesn't get loaded inline
60 * @param attachmentFilename the filename to use for the attachment or {@code null} if unspecified
61 */
62 void handleAttachment(Page page, String attachmentFilename);
63
64 /**
65 * Process the specified attachment. If this method returns false,
66 * the client will open a new window with a page created from this
67 * response as content.
68 * Overwrite this method (and return true) if you do not need to create
69 * a new window for the response.
70 * @param response the response to process
71 * @param attachmentFilename the filename to use for the attachment or {@code null} if unspecified
72 * @return {@code true} if the specified response represents is handled by this method
73 * @see <a href="http://www.ietf.org/rfc/rfc2183.txt">RFC 2183</a>
74 */
75 default boolean handleAttachment(final WebResponse response, final String attachmentFilename) {
76 return false;
77 }
78
79 /**
80 * Returns {@code true} if the specified response represents an attachment.
81 *
82 * <p>The browsers handle a response as attachment (download), if</p>
83 * <ul>
84 * <li>the disposition type of the {@code Content-Disposition} header is {@code attachment}
85 * (case-insensitive, white space around the type is ignored; see {@link ContentDispositionParser}),</li>
86 * <li>or the disposition type is unknown, e.g. {@code foo} or {@code attachmentfoo}; RFC 6266 says
87 * that unknown types have to be handled like {@code attachment},</li>
88 * <li>or the content type is {@code application/octet-stream}. The browsers can not display this content
89 * type, so they offer it for download whatever the {@code Content-Disposition} header is.</li>
90 * </ul>
91 * <p>A response is displayed in the window, if the disposition type is {@code inline} or if the header
92 * has no type at all (e.g. {@code ; filename=foo.txt}), and the content type is not octet-stream.</p>
93 *
94 * @param response the response to check
95 * @return {@code true} if the specified response represents an attachment, {@code false} otherwise
96 * @see <a href="http://www.ietf.org/rfc/rfc2183.txt">RFC 2183</a>
97 */
98 default boolean isAttachment(final WebResponse response) {
99 final String disp = response.getResponseHeaderValue(HttpHeader.CONTENT_DISPOSITION);
100 if (disp != null) {
101 final ContentDisposition contentDisposition = ContentDispositionParser.parse(disp);
102 // unknown types are handled like 'attachment', 'inline' and an empty type are not
103 if (!contentDisposition.getType().isEmpty() && !contentDisposition.isInline()) {
104 return true;
105 }
106 }
107
108 // content type 'application/octet-stream' is handled like an attachment by the browsers; this is
109 // also true if the content disposition is 'inline' or has no type
110 // https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#applicationoctet-stream
111 // They treat it as if the Content-Disposition header was set to attachment, and propose a "Save As" dialog.
112 final String contentType = response.getResponseHeaderValue(HttpHeader.CONTENT_TYPE);
113 return MimeType.APPLICATION_OCTET_STREAM.equalsIgnoreCase(contentType);
114 }
115 }