譯文篇：Retrofit原始碼之Call介面

摘要： 該文章旨在翻譯註釋，理解每個方法主要做什麼，目的是練習自己的英文轉譯能力，為日後更順暢的閱讀原始碼作準備！ 該介面來源於Retrofit 原始碼，介面中定義了網路請求方法以及請求狀態。 原始碼 package retrofit2; import java.io.IO...

該文章旨在翻譯註釋，理解每個方法主要做什麼，目的是練習自己的英文轉譯能力，為日後更順暢的閱讀原始碼作準備！

該介面來源於Retrofit 原始碼，介面中定義了網路請求方法以及請求狀態。

原始碼

package retrofit2;

import java.io.IOException;
import okhttp3.Request;

/**
 * An invocation of a Retrofit method that sends a request to a webserver and returns a response.
 * Each call yields its own HTTP request and response pair. Use {@link #clone} to make multiple
 * calls with the same parameters to the same webserver; this may be used to implement polling or
 * to retry a failed call.
 *
 * <p>Calls may be executed synchronously with {@link #execute}, or asynchronously with {@link
 * #enqueue}. In either case the call can be canceled at any time with {@link #cancel}. A call that
 * is busy writing its request or reading its response may receive a {@link IOException}; this is
 * working as designed.
 *
 * @param <T> Successful response body type.
 */
public interface Call<T> extends Cloneable {
/**
* Synchronously send the request and return its response.
* @throws IOException if a problem occurred talking to the server.
* @throws RuntimeException (and subclasses) if an unexpected error occurs creating the request
* or decoding the response.
*/
Response<T> execute() throws IOException;

/**
* Asynchronously send the request and notify {@code callback} of its response or if an error
* occurred talking to the server, creating the request, or processing the response.
*/
void enqueue(Callback<T> callback);

/**
* Returns true if this call has been either {@linkplain #execute() executed} or {@linkplain
* #enqueue(Callback) enqueued}. It is an error to execute or enqueue a call more than once.
*/
boolean isExecuted();

/**
* Cancel this call. An attempt will be made to cancel in-flight calls, and if the call has not
* yet been executed it never will be.
*/

void cancel();

/** True if {@link #cancel()} was called. */
boolean isCanceled();

/**
* Create a new, identical call to this one which can be enqueued or executed even if this call
* has already been.
*/
Call<T> clone();

/** The original HTTP request. */
Request request();
}

複製程式碼

譯

• 一個retrofit方法的呼叫介面，通過這些方法可以向服務端發起請求並得到返回結果。 每一個回撥都會對應請求和返回結果。可通過execute 方法發起同步非同步請求，或者enqueue 發起非同步請求，當然請求也可通過cancel 方法隨時取消。當請求過於頻繁時可能報IO異常。

  <T> 表示 請求成功結果返回值型別

/**
 * An invocation of a Retrofit method that sends a request to a webserver and returns a response.
 * Each call yields its own HTTP request and response pair. Use {@link #clone} to make multiple
 * calls with the same parameters to the same webserver; this may be used to implement polling or
 * to retry a failed call.
 *
 * <p>Calls may be executed synchronously with {@link #execute}, or asynchronously with {@link
 * #enqueue}. In either case the call can be canceled at any time with {@link #cancel}. A call that
 * is busy writing its request or reading its response may receive a {@link IOException}; this is
 * working as designed.
 *
 * @param <T> Successful response body type.
 */
複製程式碼

• 同步請求方法

/**
* Synchronously send the request and return its response.
* 
* @throws IOException if a problem occurred talking to the server.
* @throws RuntimeException (and subclasses) if an unexpected error occurs creating the request
* or decoding the response.
*/

Response<T> execute() throws IOException;
複製程式碼

• 非同步請求方法

/**
* Asynchronously send the request and notify {@code callback} of its response or if an error
* occurred talking to the server, creating the request, or processing the response.
*/
void enqueue(Callback<T> callback);
複製程式碼

• 當呼叫同步或非同步請求時，該值返回true

/**
* Returns true if this call has been either {@linkplain #execute() executed} or {@linkplain
* #enqueue(Callback) enqueued}. It is an error to execute or enqueue a call more than once.
*/
boolean isExecuted();
複製程式碼

• 一個正在執行的請求可能被取消，但是如果請求沒有被執行的話將無法取消。

/**
* Cancel this call. An attempt will be made to cancel in-flight calls, and if the call has not
* yet been executed it never will be.
*/
void cancel();
複製程式碼

• 當cancel() 方法被回撥時，該值為true

/** True if {@link #cancel()} was called. */
boolean isCanceled();
複製程式碼

• 克隆一個回撥

/**
* Create a new, identical call to this one which can be enqueued or executed even if this call
* has already been.
*/
Call<T> clone();
複製程式碼

• 原始的Http請求

/** The original HTTP request. */
Request request();
複製程式碼