1 /*
2  * Copyright (C) 2010 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 
17 package com.android.tradefed.util.net;
18 
19 import com.android.tradefed.util.IRunUtil;
20 import com.android.tradefed.util.MultiMap;
21 
22 import java.io.IOException;
23 import java.io.OutputStream;
24 import java.net.HttpURLConnection;
25 import java.net.URL;
26 
27 /**
28  * Helper methods for performing http requests.
29  */
30 public interface IHttpHelper {
31 
32     @SuppressWarnings("serial")
33     /**
34      * Thrown if server response is much larger than expected.
35      */
36     static class DataSizeException extends Exception {
37     }
38 
39     public static final int MAX_DATA_SIZE = 64 * 1024;
40 
41     /**
42      * Build the full encoded URL request string.
43      *
44      * @param url the base URL
45      * @param paramMap the URL parameters
46      * @return the constructed URL
47      * @throws IllegalArgumentException if an exception occurs encoding the parameters.
48      */
buildUrl(String url, MultiMap<String, String> paramMap)49     public String buildUrl(String url, MultiMap<String, String> paramMap);
50 
51     /**
52      * Build the encoded parameter string.
53      *
54      * @param paramMap the URL parameters
55      * @return the encoded parameter string
56      * @throws IllegalArgumentException if an exception occurs encoding the parameters.
57      */
buildParameters(MultiMap<String, String> paramMap)58     public String buildParameters(MultiMap<String, String> paramMap);
59 
60     /**
61      * Performs a GET HTTP request method for a given URL and returns it as a {@link String}.
62      * <p>
63      * Because remote contents are loaded into memory, this method should only be used for
64      * relatively small data sizes.
65      * </p><p>
66      * References:
67      * </p><ul>
68      * <li>Java URL Connection:
69      * <a href="http://java.sun.com/docs/books/tutorial/networking/urls/readingWriting.html">
70      * http://java.sun.com/docs/books/tutorial/networking/urls/readingWriting.html</a></li>
71      * <li>Java URL Reader:
72      * <a href="http://java.sun.com/docs/books/tutorial/networking/urls/readingURL.html">
73      * http://java.sun.com/docs/books/tutorial/networking/urls/readingURL.html</a></li>
74      * <li>Java set Proxy:
75      * <a href="http://java.sun.com/docs/books/tutorial/networking/urls/_setProxy.html">
76      * http://java.sun.com/docs/books/tutorial/networking/urls/_setProxy.html</a></li>
77      * </ul>
78      *
79      * @param url the URL
80      * @return the {@link String} remote contents
81      * @throws IOException if failed to retrieve data
82      * @throws DataSizeException if retrieved data is > {@link #MAX_DATA_SIZE}
83      */
doGet(String url)84     public String doGet(String url) throws IOException, DataSizeException;
85 
86     /**
87      * Performs a GET HTTP request method for a given URL and streams result to a
88      * {@link OutputStream}.
89      *
90      * @see #doGet(String)
91      * @param url the URL
92      * @param outputStream stream of the response data
93      * @throws IOException if failed to retrieve data
94      */
doGet(String url, OutputStream outputStream)95     public void doGet(String url, OutputStream outputStream) throws IOException;
96 
97     /**
98      * Performs {{@link #doGet(String)} retrying upon failure.
99      *
100      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
101      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
102      *
103      * @param url the URL
104      * @return the {@link String} remote contents
105      * @throws IOException if failed to retrieve data
106      * @throws DataSizeException if retrieved data is > {@link #MAX_DATA_SIZE}
107      */
doGetWithRetry(String url)108     public String doGetWithRetry(String url) throws IOException, DataSizeException;
109 
110     /**
111      * Performs a GET for a given URL, with the given URL parameters ignoring the result.
112      *
113      * @see #doGet(String)
114      * @param url the URL
115      * @throws IOException if failed to retrieve data
116      */
doGetIgnore(String url)117     public void doGetIgnore(String url) throws IOException;
118 
119     /**
120      * Performs {{@link #doGetIgnore(String)} retrying upon failure.
121      *
122      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
123      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
124      *
125      * @param url the URL
126      * @throws IOException if failed to retrieve data
127      */
doGetIgnoreWithRetry(String url)128     public void doGetIgnoreWithRetry(String url) throws IOException;
129 
130     /**
131      * Performs a POST HTTP request method for a given URL and returns it as a {@link String},
132      * retrying upon failure.
133      * <p>
134      * Because remote contents are loaded into memory, this method should only be used for
135      * relatively small data sizes.
136      * </p>
137      * @param url the URL
138      * @param postData the data to be posted once the connection is open
139      * @return the {@link String} remote contents
140      * @throws IOException if failed to retrieve data
141      * @throws DataSizeException if retrieved data is > {@link #MAX_DATA_SIZE}
142      */
doPostWithRetry(String url, String postData)143     public String doPostWithRetry(String url, String postData) throws IOException,
144             DataSizeException;
145 
146     /**
147      * Performs a POST HTTP request method for a given URL and returns it as a {@link String},
148      * retrying upon failure.
149      * <p>
150      * Because remote contents are loaded into memory, this method should only be used for
151      * relatively small data sizes.
152      * </p>
153      * @param url the URL
154      * @param postData the data to be posted once the connection is open
155      * @param contentType the content type. For example, "text/html".
156      * @return the {@link String} remote contents
157      * @throws IOException if failed to retrieve data
158      * @throws DataSizeException if retrieved data is > {@link #MAX_DATA_SIZE}
159      */
doPostWithRetry(String url, String postData, String contentType)160     public String doPostWithRetry(String url, String postData, String contentType)
161             throws IOException, DataSizeException;
162 
163     /**
164      * Create a to given url.
165      *
166      * @param url the {@link URL} to connect to.
167      * @param method the HTTP request method. For example, GET or POST.
168      * @param contentType the content type. For example, "text/html".
169      * @return The HttpURLConnection
170      * @throws IOException if an IOException occurs.
171      */
createConnection(URL url, String method, String contentType)172     public HttpURLConnection createConnection(URL url, String method, String contentType)
173             throws IOException;
174 
175     /**
176      * Creates a connection to given URL for passing xml data.
177      *
178      * @param url the {@link URL} to connect to.
179      * @param method the HTTP request method. For example, GET or POST.
180      * @return the {@link HttpURLConnection}
181      * @throws IOException if failed to make connection
182      */
createXmlConnection(URL url, String method)183     public HttpURLConnection createXmlConnection(URL url, String method) throws IOException;
184 
185     /**
186      * Creates a connection to given URL for passing json data.
187      *
188      * @param url the {@link URL} to connect to.
189      * @param method the HTTP request method. For example, GET or POST.
190      * @return the {@link HttpURLConnection}
191      * @throws IOException if failed to make connection
192      */
createJsonConnection(URL url, String method)193     public HttpURLConnection createJsonConnection(URL url, String method) throws IOException;
194 
195     /**
196      * Get the operation timeout in ms.
197      *
198      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
199      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
200      */
getOpTimeout()201     int getOpTimeout();
202 
203     /**
204      * Set the operation timeout in ms.
205      *
206      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
207      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
208      */
setOpTimeout(int time)209     void setOpTimeout(int time);
210 
211     /**
212      * Get the initial poll interval in ms.
213      *
214      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
215      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
216      */
getInitialPollInterval()217     int getInitialPollInterval();
218 
219     /**
220      * Set the initial poll interval in ms.
221      *
222      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
223      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
224      */
setInitialPollInterval(int time)225     void setInitialPollInterval(int time);
226 
227     /**
228      * Get the max poll interval in ms.
229      *
230      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
231      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
232      */
getMaxPollInterval()233     int getMaxPollInterval();
234 
235     /**
236      * Set the initial poll interval in ms.
237      *
238      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
239      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
240      */
setMaxPollInterval(int time)241     void setMaxPollInterval(int time);
242 
243     /**
244      * Get the maximum time to keep trying the request in ms.
245      *
246      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
247      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
248      */
getMaxTime()249     int getMaxTime();
250 
251     /**
252      * Set the maximum time to keep trying the request in ms.
253      *
254      * @see IRunUtil#runEscalatingTimedRetry(long, long, long, long,
255      *     com.android.tradefed.util.IRunUtil.IRunnableResult)
256      */
setMaxTime(int time)257     void setMaxTime(int time);
258 }
259