1 /*
2 * Copyright (c) 2002-2025 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.util.MimeType;
23 import org.htmlunit.util.StringUtils;
24
25 /**
26 * <p>A handler for attachments, which represent pages received from the server which contain
27 * {@code Content-Disposition=attachment} headers. Normally pages are loaded inline: clicking on
28 * a link, for example, loads the linked page in the current window. Attached pages are different
29 * in that they are intended to be loaded outside of this flow: clicking on a link prompts the
30 * user to either save the linked page, or open it outside of the current window, but does not
31 * load the page in the current window.</p>
32 *
33 * <p>HtmlUnit complies with the semantics described above when an <code>AttachmentHandler</code> has
34 * been registered with the {@link org.htmlunit.WebClient} via
35 * {@link org.htmlunit.WebClient#setAttachmentHandler(AttachmentHandler)}. When
36 * no attachment handler has been registered with the <code>WebClient</code>, the semantics described
37 * above to not apply, and attachments are loaded inline. By default, <code>AttachmentHandler</code>s
38 * are not registered with new <code>WebClient</code> instances.</p>
39 *
40 * @author Bruce Chapman
41 * @author Sudhan Moghe
42 * @author Daniel Gredler
43 * @author Ronald Brill
44 * @author Alex Gorbatovsky
45 * @author Lai Quang Duong
46 * @see org.htmlunit.WebClient#setAttachmentHandler(AttachmentHandler)
47 * @see org.htmlunit.WebClient#getAttachmentHandler()
48 * @see <a href="http://www.ietf.org/rfc/rfc2183.txt">RFC 2183</a>
49 */
50 public interface AttachmentHandler extends Serializable {
51
52 /**
53 * Handles the specified attached page. This is some kind of information
54 * that the page was handled as attachment.
55 * This method will only be called if {@link #handleAttachment(WebResponse, String)}
56 * has returned false for the response.
57 * @param page an attached page, which doesn't get loaded inline
58 * @param attachmentFilename the filename to use for the attachment or {@code null} if unspecified
59 */
60 void handleAttachment(Page page, String attachmentFilename);
61
62 /**
63 * Process the specified attachment. If this method returns false,
64 * the client will open a new window with a page created from this
65 * response as content.
66 * Overwrite this method (and return true) if you do not need to create
67 * a new window for the response.
68 * @param response the response to process
69 * @param attachmentFilename the filename to use for the attachment or {@code null} if unspecified
70 * @return {@code true} if the specified response represents is handled by this method
71 * @see <a href="http://www.ietf.org/rfc/rfc2183.txt">RFC 2183</a>
72 */
73 default boolean handleAttachment(final WebResponse response, final String attachmentFilename) {
74 return false;
75 }
76
77 /**
78 * Returns {@code true} if the specified response represents an attachment.
79 * @param response the response to check
80 * @return {@code true} if the specified response represents an attachment, {@code false} otherwise
81 * @see <a href="http://www.ietf.org/rfc/rfc2183.txt">RFC 2183</a>
82 */
83 default boolean isAttachment(final WebResponse response) {
84 final String disp = response.getResponseHeaderValue(HttpHeader.CONTENT_DISPOSITION);
85 if (disp == null) {
86 // if there is no content disposition header and content type 'application/octet-stream'
87 // is handled like an attachment by the browsers
88 // https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#applicationoctet-stream
89 // They treat it as if the Content-Disposition header was set to attachment, and propose a "Save As" dialog.
90 final String contentType = response.getResponseHeaderValue(HttpHeader.CONTENT_TYPE);
91 return contentType != null
92 && MimeType.APPLICATION_OCTET_STREAM.equalsIgnoreCase(contentType);
93 }
94 return StringUtils.startsWithIgnoreCase(disp, "attachment");
95 }
96 }