001/*
002 * (C) Copyright 2015 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl-2.1.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Florent Guillaume
016 */
017package org.nuxeo.ecm.core.io.download;
018
019import java.io.IOException;
020import java.io.Serializable;
021import java.util.Map;
022
023import javax.servlet.http.HttpServletRequest;
024import javax.servlet.http.HttpServletResponse;
025
026import org.nuxeo.ecm.core.api.Blob;
027import org.nuxeo.ecm.core.api.DocumentModel;
028
029/**
030 * This service allows the download of blobs to a HTTP response.
031 *
032 * @since 7.3
033 */
034public interface DownloadService {
035
036    String EVENT_NAME = "download";
037
038    String NXFILE = "nxfile";
039
040    String NXDOWNLOADINFO = "nxdownloadinfo";
041
042    String NXBIGBLOB = "nxbigblob";
043
044    String NXBIGZIPFILE = "nxbigzipfile";
045
046    String BLOBHOLDER_PREFIX = "blobholder:";
047
048    String BLOBHOLDER_0 = "blobholder:0";
049
050    public static class ByteRange {
051
052        private final long start;
053
054        private final long end;
055
056        public ByteRange(long start, long end) {
057            this.start = start;
058            this.end = end;
059        }
060
061        public long getStart() {
062            return start;
063        }
064
065        public long getEnd() {
066            return end;
067        }
068
069        public long getLength() {
070            return end - start + 1;
071        }
072    }
073
074    /**
075     * Gets the URL to use to download the blob at the given xpath in the given document.
076     * <p>
077     * The URL is relative to the Nuxeo Web Application context.
078     * <p>
079     * Returns something like {@code nxbigfile/reponame/docuuid/blobholder:0/foo.jpg}
080     *
081     * @param doc the document
082     * @param xpath the blob's xpath or blobholder index, or {@code null} for default
083     * @param filename the blob's filename, or {@code null} for default
084     * @return the download URL
085     */
086    String getDownloadUrl(DocumentModel doc, String xpath, String filename);
087
088    /**
089     * Gets the URL to use to download the blob at the given xpath in the given document.
090     * <p>
091     * The URL is relative to the Nuxeo Web Application context.
092     * <p>
093     * Returns something like {@code nxbigfile/reponame/docuuid/blobholder:0/foo.jpg}
094     *
095     * @param repositoryName the document repository
096     * @param docId the document id
097     * @param xpath the blob's xpath or blobholder index, or {@code null} for default
098     * @param filename the blob's filename, or {@code null} for default
099     * @return the download URL
100     */
101    String getDownloadUrl(String repositoryName, String docId, String xpath, String filename);
102
103    /**
104     * Triggers a blob download.
105     *
106     * @param doc the document, if available
107     * @param xpath the blob's xpath or blobholder index, if available
108     * @param blob the blob, if already fetched
109     * @param filename the filename to use
110     * @param reason the download reason
111     */
112    void downloadBlob(HttpServletRequest request, HttpServletResponse response, DocumentModel doc, String xpath,
113            Blob blob, String filename, String reason) throws IOException;
114
115    /**
116     * Triggers a blob download.
117     *
118     * @param doc the document, if available
119     * @param xpath the blob's xpath or blobholder index, if available
120     * @param blob the blob, if already fetched
121     * @param filename the filename to use
122     * @param reason the download reason
123     * @param extendedInfos an optional map of extended informations to log
124     */
125    void downloadBlob(HttpServletRequest request, HttpServletResponse response, DocumentModel doc, String xpath,
126            Blob blob, String filename, String reason, Map<String, Serializable> extendedInfos) throws IOException;
127
128    /**
129     * Logs a download.
130     *
131     * @param doc the doc for which this download occurs, if available
132     * @param blobXPath the blob's xpath or blobholder index, if available
133     * @param filename the filename
134     * @param reason the download reason
135     * @param extendedInfos an optional map of extended informations to log
136     */
137    void logDownload(DocumentModel doc, String blobXPath, String filename, String reason,
138            Map<String, Serializable> extendedInfos);
139
140    /**
141     * Finds a document's blob given an xpath or blobholder index
142     *
143     * @param doc the document
144     * @param xpath the xpath or blobholder index
145     * @return the blob, or {@code null} if not found
146     */
147    Blob resolveBlob(DocumentModel doc, String xpath);
148
149}