1 /*
2  * Copyright (C) 2011 The Android Open Source Project
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  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.android.tradefed.build;
17 
18 import java.io.File;
19 import java.io.IOException;
20 import java.util.List;
21 
22 /**
23  * Interface for downloading a remote file.
24  */
25 public interface IFileDownloader {
26 
27     /**
28      * Downloads a remote file to a temporary file on local disk.
29      *
30      * @param remoteFilePath the remote path to the file to download, relative to a implementation
31      * specific root.
32      * @return the temporary local downloaded {@link File}.
33      * @throws BuildRetrievalError if file could not be downloaded
34      */
downloadFile(String remoteFilePath)35     public File downloadFile(String remoteFilePath) throws BuildRetrievalError;
36 
37     /**
38      * Alternate form of {@link #downloadFile(String)}, that allows caller to specify the
39      * destination file the remote contents should be placed in.
40      *
41      * @param relativeRemotePath the remote path to the file to download, relative to an
42      *        implementation-specific root.
43      * @param destFile the file to place the downloaded contents into. Should not exist.
44      * @throws BuildRetrievalError if file could not be downloaded
45      */
downloadFile(String relativeRemotePath, File destFile)46     public void downloadFile(String relativeRemotePath, File destFile) throws BuildRetrievalError;
47 
48     /**
49      * Alternate form of {@link #downloadFile(String, File)}, that allows caller to download a
50      * section of the file and save to a specific destination file.
51      *
52      * @param remoteFilePath the remote path to the file to download, relative to an
53      *     implementation-specific root.
54      * @param destFile the file to place the downloaded contents into. Should not exist.
55      * @param startOffset the start offset in the remote file.
56      * @param size the number of bytes to download from the remote file. Set it to a negative value
57      *     to download the whole file.
58      * @throws BuildRetrievalError if file could not be downloaded
59      */
downloadFile( String remoteFilePath, File destFile, long startOffset, long size)60     public default void downloadFile(
61             String remoteFilePath, File destFile, long startOffset, long size)
62             throws BuildRetrievalError {
63         throw new UnsupportedOperationException("Partial downloading is not implemented.");
64     }
65 
66     /**
67      * Check local file's freshness. If local file is the same as remote file, then it's fresh. If
68      * not, local file is stale. This is mainly used for cache. The default implementation will
69      * always return true, so if the file is immutable it will never need to check freshness.
70      *
71      * @param localFile local file.
72      * @param remoteFilePath remote file path.
73      * @return True if local file is fresh, otherwise false.
74      * @throws BuildRetrievalError
75      */
isFresh(File localFile, String remoteFilePath)76     public default boolean isFresh(File localFile, String remoteFilePath)
77             throws BuildRetrievalError {
78         return true;
79     }
80 
81     /**
82      * Download the files matching given filters in a remote zip file.
83      *
84      * <p>A file inside the remote zip file is only downloaded to its path matches any of the
85      * include filters but not the exclude filters.
86      *
87      * @param destDir the file to place the downloaded contents into.
88      * @param remoteFilePath the remote path to the file to download, relative to an implementation
89      *     specific root.
90      * @param includeFilters a list of filters to download matching files.
91      * @param excludeFilters a list of filters to skip downloading matching files.
92      * @throws BuildRetrievalError if files could not be downloaded.
93      * @throws IOException
94      */
downloadZippedFiles( File destDir, String remoteFilePath, List<String> includeFilters, List<String> excludeFilters)95     public default void downloadZippedFiles(
96             File destDir,
97             String remoteFilePath,
98             List<String> includeFilters,
99             List<String> excludeFilters)
100             throws BuildRetrievalError, IOException {
101         throw new UnsupportedOperationException();
102     }
103 }
104