/*
* Copyright (C) 2014 Neal
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package neal.http.base;
/**
* Created by Neal on 2014/10/25.
*/
import android.net.Uri;
import android.os.Handler;
import android.os.Looper;
import android.os.SystemClock;
import android.text.TextUtils;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.Collections;
import java.util.Map;
import neal.http.impl.DefaultRetryPolicy;
import neal.http.impl.HttpErrorCollection;
import neal.http.process.RequestQueue;
import neal.http.utils.HttpHeaderProvider.Charset;
import neal.http.utils.HttpHeaderProvider.ContentType;
import neal.http.utils.HttpLog;
import neal.http.utils.HttpLog.MarkerLog;
/**
* Base class for all network requests.
* 所有网络请求的基础类
*
* @param <T> The type of parsed response this request expects.
* 网络请求的响应类型
*/
public abstract class Request<T> implements Comparable<Request<T>> {
/**
* Threshold at which we should log the request (even when debug logging is not enabled).
*/
private static final long SLOW_REQUEST_THRESHOLD_MS = 3000;
/**
* Default encoding for POST or PUT parameters. See {@link #getParamsEncoding()}.
* 网络请求参数默认编码
*/
private static String DEFAULT_PARAMS_ENCODING =Charset.DEFAULT_REQUEST_CHARSET;
/**
* An event log tracing the lifetime of this request; for debugging.
*/
private final MarkerLog mEventLog = MarkerLog.ENABLED ? new MarkerLog() : null;
/**
* Request method of this request. Currently supports GET, POST, PUT, DELETE, HEAD, OPTIONS,
* TRACE, and PATCH.
*/
private final int mMethod;
/**
* URL of this request.
*/
private final String mUrl;
/**
* params of the request,used in two cases:
* 1. get method
* 2. post method and content-typr:application/x-www-form-urlencoded
* when the content-type of post method is the other one,set the params be null,and overwrite
* {@link #getBodyContentType()} and{@link #getBody()},
*/
private Map<String,String> mParams=null;
/**
* Default tag for {@link android.net.TrafficStats}.
*/
private final int mDefaultTrafficStatsTag;
/**
* Listener interface for errors.
*/
private final Response.ErrorListener mErrorListener;
/**
* Sequence number of this request, used to enforce FIFO ordering.
*/
private Integer mSequence;
/**
* The request queue this request is associated with.
*/
private RequestQueue mRequestQueue;
/**
* Whether or not responses to this request should be cached.
*/
private boolean mShouldCache = true;
/**
* Whether or not this request has been canceled.
*/
private boolean mCanceled = false;
/**
* Whether or not a response has been delivered for this request yet.
*/
private boolean mResponseDelivered = false;
/**
* A cheap variant of request tracing used to dump slow requests.
* 记录请求发生时间，用于丢弃缓慢的网络请求
*/
private long mRequestBirthTime = 0;
/**
* The retry policy for this request.
*/
private RetryPolicy mRetryPolicy;
/**
* When a request can be retrieved from cache but must be refreshed from
* the network, the cache entry will be stored here so that in the event of
* a "Not Modified" response, we can be sure it hasn't been evicted from cache.
*/
private Cache.Entry mCacheEntry = null;
/**
* An opaque token tagging this request; used for bulk cancellation.
*/
private Object mTag;
/**
* Creates a new request with the given URL and error listener. Note that
* the normal response listener is not provided here as delivery of responses
* is provided by subclasses, who have a better idea of how to deliver an
* already-parsed response.
*
* @deprecated Use {@link #Request(int, String, Map,neal.http.base.Response.ErrorListener)}.
*/
@Deprecated
public Request(String url,Map<String,String> params, Response.ErrorListener listener) {
this(Method.DEPRECATED_GET_OR_POST, url,params, listener);
}
/**
* Creates a new request with the given method (one of the values from {@link neal.http.base.Request.Method}),
* URL, and error listener. Note that the normal response listener is not provided here as
* delivery of responses is provided by subclasses, who have a better idea of how to deliver
* an already-parsed response.
*/
public Request(int method, String url,Map<String,String> params, Response.ErrorListener listener) {
mMethod = method;
if(Method.GET==method){
mUrl=formatGetUrl(url,params);
mParams=null;
}else if(Method.POST==method){
mUrl = url;
mParams=params;
}else{
//TODO deal with the other methods
mUrl = url;
mParams=params;
}
mErrorListener = listener;
setRetryPolicy(new DefaultRetryPolicy());
mDefaultTrafficStatsTag = findDefaultTrafficStatsTag(url);
}
/**
* @return The hashcode of the URL's host component, or 0 if there is none.
*/
private static int findDefaultTrafficStatsTag(String url) {
if (!TextUtils.isEmpty(url)) {
Uri uri = Uri.parse(url);
if (uri != null) {
String host = uri.getHost();
if (host != null) {
return host.hashCode();
}
}
}
return 0;
}
/**
* Return the method for this request. Can be one of the values in {@link neal.http.base.Request.Method}.
*/
public int getMethod() {
return mMethod;
}
/**
* Returns this request's tag.
*
* @see neal.http.base.Request#setTag(Object)
*/
public Object getTag() {
return mTag;
}
/**
* Set a tag on this request. Can be used to cancel all requests with this
* tag by {@link RequestQueue#cancelAll(Object)}.
*
* @return This Request object to allow for chaining.
*/
public Request<?> setTag(Object tag) {
mTag = tag;
return this;
}
/**
* @return this request's {@link neal.http.base.Response.ErrorListener}.
*/
public Response.ErrorListener getErrorListener() {
return mErrorListener;
}
/**
* @return A tag for use with {@link android.net.TrafficStats#setThreadStatsTag(int)}
*/
public int getTrafficStatsTag() {
return mDefaultTrafficStatsTag;
}
/**
* Adds an event to this request's event log; for debugging.
*/
public void addMarker(String tag) {
if (MarkerLog.ENABLED) {
mEventLog.add(tag, Thread.currentThread().getId());
} else if (mRequestBirthTime == 0) {
mRequestBirthTime = SystemClock.elapsedRealtime();
}
}
/**
* Notifies the request queue that this request has finished (successfully or with error).
* <p/>
* <p>Also dumps all events from this request's event log; for debugging.</p>
*/
public void finish(final String tag) {
if (mRequestQueue != null) {
mRequestQueue.finish(this);
}
if (MarkerLog.ENABLED) {
final long threadId = Thread.currentThread().getId();
if (Looper.myLooper() != Looper.getMainLooper()) {
// If we finish marking off of the main thread, we need to
// actually do it on the main thread to ensure correct ordering.
Handler mainThread = new Handler(Looper.getMainLooper());
mainThread.post(new Runnable() {
@Override
public void run() {
mEventLog.add(tag, threadId);
mEventLog.finish(Request.this.toString());
}
});
return;
}
mEventLog.add(tag, threadId);
mEventLog.finish(Request.this.toString());
} else {
long requestTime = SystemClock.elapsedRealtime() - mRequestBirthTime;
if (requestTime >= SLOW_REQUEST_THRESHOLD_MS) {
HttpLog.d("%d ms: %s", requestTime, this.toString());
}
}
}
/**
* Associates this request with the given queue. The request queue will be notified when this
* request has finished.
*
* @return This Request object to allow for chaining.
*/
public Request<?> setRequestQueue(RequestQueue requestQueue) {
mRequestQueue = requestQueue;
return this;
}
/**
* Returns the sequence number of this request.
*/
public final int getSequence() {
if (mSequence == null) {
throw new IllegalStateException("getSequence called before setSequence");
}
return mSequence;
}
/**
* Sets the sequence number of this request. Used by {@link RequestQueue}.
*
* @return This Request object to allow for chaining.
*/
public final Request<?> setSequence(int sequence) {
mSequence = sequence;
return this;
}
/**
* Returns the URL of this request.
*/
public String getUrl() {
return mUrl;
}
/**
* Returns the cache key for this request. By default, this is the URL.
*/
public String getCacheKey() {
return getUrl();
}
/**
* Returns the annotated cache entry, or null if there isn't one.
*/
public Cache.Entry getCacheEntry() {
return mCacheEntry;
}
/**
* Annotates this request with an entry retrieved for it from cache.
* Used for cache coherency support.
*
* @return This Request object to allow for chaining.
*/
public Request<?> setCacheEntry(Cache.Entry entry) {
mCacheEntry = entry;
return this;
}
/**
* Mark this request as canceled. No callback will be delivered.
*/
public void cancel() {
mCanceled = true;
}
/**
* Returns true if this request has been canceled.
*/
public boolean isCanceled() {
return mCanceled;
}
/**
* Returns a list of extra HTTP headers to go along with this request. Can
* throw {@link neal.http.impl.HttpErrorCollection.AuthFailureError} as authentication may be required to
* provide these values.
*
* @throws neal.http.impl.HttpErrorCollection.AuthFailureError In the event of auth failure
*/
public Map<String, String> getHeaders() throws HttpErrorCollection.AuthFailureError {
return Collections.emptyMap();
}
/**
* Returns a Map of POST parameters to be used for this request, or null if
* a simple GET should be used. Can throw {@link HttpErrorCollection.AuthFailureError} as
* authentication may be required to provide these values.
* <p/>
* <p>Note that only one of getPostParams() and getPostBody() can return a non-null
* value.</p>
*
* @throws HttpErrorCollection.AuthFailureError In the event of auth failure
* @deprecated Use {@link #getParams()} instead.
*/
@Deprecated
protected Map<String, String> getPostParams() throws HttpErrorCollection.AuthFailureError {
return getParams();
}
/**
* Returns which encoding should be used when converting POST parameters returned by
* {@link #getPostParams()} into a raw POST body.
* <p/>
* <p>This controls both encodings:
* <ol>
* <li>The string encoding used when converting parameter names and values into bytes prior
* to URL encoding them.</li>
* <li>The string encoding used when converting the URL encoded parameters into a raw
* byte array.</li>
* </ol>
*
* @deprecated Use {@link #getParamsEncoding()} instead.
*/
@Deprecated
protected String getPostParamsEncoding() {
return getParamsEncoding();
}
/**
* @deprecated Use {@link #getBodyContentType()} instead.
*/
@Deprecated
public String getPostBodyContentType() {
return getBodyContentType();
}
/**
* Returns the raw POST body to be sent.
*
* @throws HttpErrorCollection.AuthFailureError In the event of auth failure
* @deprecated Use {@link #getBody()} instead.
*/
@Deprecated
public byte[] getPostBody() throws HttpErrorCollection.AuthFailureError {
// Note: For compatibility with legacy clients of volley, this implementation must remain
// here instead of simply calling the getBody() function because this function must
// call getPostParams() and getPostParamsEncoding() since legacy clients would have
// overridden these two member functions for POST requests.
Map<String, String> postParams = getPostParams();
if (postParams != null && postParams.size() > 0) {
return encodeParameters(postParams, getPostParamsEncoding());
}
return null;
}
/**
* Returns a Map of parameters to be used for a POST or PUT request. Can throw
* {@link HttpErrorCollection.AuthFailureError} as authentication may be required to provide these values.
* <p/>
* <p>Note that you can directly override {@link #getBody()} for custom data.</p>
*
* @throws HttpErrorCollection.AuthFailureError in the event of auth failure
*/
protected Map<String, String> getParams() throws HttpErrorCollection.AuthFailureError {
return mParams;
}
/**
* Returns which encoding should be used when converting POST or PUT parameters returned by
* {@link #getParams()} into a raw POST or PUT body.
* <p/>
* <p>This controls both encodings:
* <ol>
* <li>The string encoding used when converting parameter names and values into bytes prior
* to URL encoding them.</li>
* <li>The string encoding used when converting the URL encoded parameters into a raw
* byte array.</li>
* </ol>
*/
protected String getParamsEncoding() {
return DEFAULT_PARAMS_ENCODING;
}
public String getBodyContentType() {
return new ContentType(ContentType.APPLICATION_FORM_URLENCODED,getParamsEncoding()).toString();
}
/**
* Returns the raw POST or PUT body to be sent.
*
* @throws HttpErrorCollection.AuthFailureError in the event of auth failure
*/
public byte[] getBody() throws HttpErrorCollection.AuthFailureError {
Map<String, String> params = getParams();
if (params != null && params.size() > 0) {
return encodeParameters(params, getParamsEncoding());
}
return null;
}
/**
* Converts <code>params</code> into an application/x-www-form-urlencoded encoded string.
*/
private byte[] encodeParameters(Map<String, String> params, String paramsEncoding) {
StringBuilder encodedParams = new StringBuilder();
try {
for (Map.Entry<String, String> entry : params.entrySet()) {
/**
* URLEncoder.This class is used to encode a string using the format required by
* {@code application/x-www-form-urlencoded} MIME content type.
*
* <p>All characters except letters ('a'..'z', 'A'..'Z') and numbers ('0'..'9')
* and characters '.', '-', '*', '_' are converted into their hexadecimal value
* prepended by '%'. For example: '#' -> %23. In addition, spaces are
* substituted by '+'.
*/
encodedParams.append(URLEncoder.encode(entry.getKey(), paramsEncoding));
encodedParams.append('=');
encodedParams.append(URLEncoder.encode(entry.getValue(), paramsEncoding));
encodedParams.append('&');
}
return encodedParams.toString().getBytes(paramsEncoding);
} catch (UnsupportedEncodingException uee) {
throw new RuntimeException("Encoding not supported: " + paramsEncoding, uee);
}
}
private String formatGetUrl(String url,Map<String,String> params){
if(params==null){
return url;
}
StringBuilder stringBuilder=new StringBuilder();
stringBuilder.append(url);
stringBuilder.append("?");
for (Map.Entry<String, String> entry : params.entrySet()) {
stringBuilder.append(entry.getKey());
stringBuilder.append('=');
stringBuilder.append(entry.getValue());
stringBuilder.append('&');
}
return stringBuilder.toString();
}
/**
* Set whether or not responses to this request should be cached.
*
* @return This Request object to allow for chaining.
*/
public final Request<?> setShouldCache(boolean shouldCache) {
mShouldCache = shouldCache;
return this;
}
/**
* Returns true if responses to this request should be cached.
*/
public final boolean shouldCache() {
return mShouldCache;
}
/**
* Returns the {@link neal.http.base.Request.Priority} of this request; {@link neal.http.base.Request.Priority#NORMAL} by default.
*/
public Priority getPriority() {
return Priority.NORMAL;
}
/**
* Returns the socket timeout in milliseconds per retry attempt. (This value can be changed
* per retry attempt if a backoff is specified via backoffTimeout()). If there are no retry
* attempts remaining, this will cause delivery of a {@link HttpErrorCollection.TimeoutError} error.
*/
public final int getTimeoutMs() {
return mRetryPolicy.getCurrentTimeout();
}
/**
* Returns the retry policy that should be used for this request.
*/
public RetryPolicy getRetryPolicy() {
return mRetryPolicy;
}
/**
* Sets the retry policy for this request.
*
* @return This Request object to allow for chaining.
*/
public Request<?> setRetryPolicy(RetryPolicy retryPolicy) {
mRetryPolicy = retryPolicy;
return this;
}
/**
* Mark this request as having a response delivered on it. This can be used
* later in the request's lifetime for suppressing identical responses.
*/
public void markDelivered() {
mResponseDelivered = true;
}
/**
* Returns true if this request has had a response delivered for it.
*/
public boolean hasHadResponseDelivered() {
return mResponseDelivered;
}
/**
* Subclasses must implement this to parse the raw network response
* and return an appropriate response type. This method will be
* called from a worker thread. The response will not be delivered
* if you return null.
*
* @param response Response from the network
* @return The parsed response, or null in the case of an error
*/
abstract public Response<T> parseNetworkResponse(NetworkResponse response);
/**
* Subclasses can override this method to parse 'networkError' and return a more specific error.
* <p/>
* <p>The default implementation just returns the passed 'networkError'.</p>
*
* @param httpError the error retrieved from the network
* @return an NetworkError augmented with additional information
*/
public HttpError parseNetworkError(HttpError httpError) {
return httpError;
}
/**
* Subclasses must implement this to perform delivery of the parsed
* response to their listeners. The given response is guaranteed to
* be non-null; responses that fail to parse are not delivered.
*
* @param response The parsed response returned by
* {@link #parseNetworkResponse(NetworkResponse)}
*/
abstract public void deliverResponse(T response);
/**
* Delivers error message to the ErrorListener that the Request was
* initialized with.
*
* @param error Error details
*/
public void deliverError(HttpError error) {
if (mErrorListener != null) {
mErrorListener.onErrorResponse(error);
}
}
/**
* Our comparator sorts from high to low priority, and secondarily by
* sequence number to provide FIFO ordering.
*/
@Override
public int compareTo(Request<T> other) {
Priority left = this.getPriority();
Priority right = other.getPriority();
// High-priority requests are "lesser" so they are sorted to the front.
// Equal priorities are sorted by sequence number to provide FIFO ordering.
return left == right ?
this.mSequence - other.mSequence :
right.ordinal() - left.ordinal();
}
@Override
public String toString() {
String trafficStatsTag = "0x" + Integer.toHexString(getTrafficStatsTag());
return (mCanceled ? "[X] " : "[ ] ") + getUrl() + " " + trafficStatsTag + " "
+ getPriority() + " " + mSequence;
}
/**
* Priority values. Requests will be processed from higher priorities to
* lower priorities, in FIFO order.
*/
public enum Priority {
LOW,
NORMAL,
HIGH,
IMMEDIATE
}
/**
* Supported request methods.
* 支持的网络请求方式
*/
public interface Method {
int DEPRECATED_GET_OR_POST = -1;
int GET = 0;
int POST = 1;
int PUT = 2;
int DELETE = 3;
int HEAD = 4;
int OPTIONS = 5;
int TRACE = 6;
int PATCH = 7;
}
}