שליחת בקשה פשוטה

כאן מוסבר איך להשתמש בספריית Cronet כדי לבצע פעולות ברשת באפליקציה ל-Android. Cronet הוא מקבץ הרשת (network stack) של Chromium, שזמין כספרייה לשימוש באפליקציות. מידע נוסף על התכונות של הספרייה זמין במאמר ביצוע פעולות ברשת באמצעות Cronet.

הגדרת הספרייה בפרויקט

כדי להוסיף תלות לספריית Cronet בפרויקט:

  1. מוודאים ש-Android Studio כללה הפניה למאגר Maven של Google בקובץ settings.gradle של הפרויקט, כמו בדוגמה הבאה:

    מגניב

    dependencyResolutionManagement {
       ...
       repositories {
           ...
           google()
       }
    }

    Kotlin

    dependencyResolutionManagement {
       ...
       repositories {
           ...
           google()
       }
    }
  2. מוסיפים הפניה לספריית הלקוח של Google Play Services בשביל Cronet בקטע dependencies של קובץ build.gradle של מודול האפליקציה, כמו בדוגמה הבאה:

    מגניב

    dependencies {
       implementation 'com.google.android.gms:play-services-cronet:18.0.1'
    }

    Kotlin

    dependencies {
       implementation("com.google.android.gms:play-services-cronet:18.0.1")
    }

אובייקטים מסוג CronetEngine שנוצרו אחרי שהוספתם את יחסי התלות האלה משתמשים ב-Cronet שנטען מ-Google Play Services. כדי למנוע חריגות לא צפויות במהלך היצירה של CronetEngine (למשל במכשירים שנדרשת בהם גרסה עדכנית של Google Play Services), צריך להפעיל את CronetProviderInstaller.installProvider(Context) לפני שיוצרים אובייקטים של CronetEngine.

במקרים שבהם לא ניתן לטעון את Cronet מ-Google Play Services, יש הטמעה פחות יעילה של ה-API של Cronet שאפשר להשתמש בה. כדי להשתמש בהטמעה החלופית הזו, צריך להסתמך על org.chromium.net:cronet-fallback ולקרוא ל-new JavaCronetProvider(context).createBuilder().

יצירת בקשה לאחזור מהרשת

בקטע הזה מוסבר איך ליצור ולשלוח בקשה לאחזור מהרשת באמצעות ספריית Cronet. אחרי שליחת הבקשה לאחזור מהרשת, האפליקציה צריכה לעבד את התגובה מהרשת.

יצירה והגדרה של מכונה של CronetEngine

הספרייה מספקת מחלקת CronetEngine.Builder שבה אפשר להשתמש כדי ליצור מופע של CronetEngine. בדוגמה הבאה אפשר לראות איך יוצרים אובייקט CronetEngine:

Kotlin

val myBuilder = CronetEngine.Builder(context)
val cronetEngine: CronetEngine = myBuilder.build()

Java

CronetEngine.Builder myBuilder = new CronetEngine.Builder(context);
CronetEngine cronetEngine = myBuilder.build();

אפשר להשתמש במחלקה Builder כדי להגדיר אובייקט CronetEngine. לדוגמה, אתם יכולים לספק אפשרויות כמו שמירה במטמון ודחיסת נתונים. מידע נוסף זמין במאמר CronetEngine.Builder.

מטמיעים את הקריאה החוזרת (callback) של הבקשה

כדי לספק הטמעה של הקריאה החוזרת (callback), יוצרים מחלקת משנה של UrlRequest.Callback ומטמיעים את השיטות המופשטות הנדרשות, כמו בדוגמה הבאה:

Kotlin

private const val TAG = "MyUrlRequestCallback"

class MyUrlRequestCallback : UrlRequest.Callback() {
    override fun onRedirectReceived(request: UrlRequest?, info: UrlResponseInfo?, newLocationUrl: String?) {
        Log.i(TAG, "onRedirectReceived method called.")
        // You should call the request.followRedirect() method to continue
        // processing the request.
        request?.followRedirect()
    }

    override fun onResponseStarted(request: UrlRequest?, info: UrlResponseInfo?) {
        Log.i(TAG, "onResponseStarted method called.")
        // You should call the request.read() method before the request can be
        // further processed. The following instruction provides a ByteBuffer object
        // with a capacity of 102400 bytes for the read() method. The same buffer
        // with data is passed to the onReadCompleted() method.
        request?.read(ByteBuffer.allocateDirect(102400))
    }

    override fun onReadCompleted(request: UrlRequest?, info: UrlResponseInfo?, byteBuffer: ByteBuffer?) {
        Log.i(TAG, "onReadCompleted method called.")
        // You should keep reading the request until there's no more data.
        byteBuffer?.clear()
        request?.read(byteBuffer)
    }

    override fun onSucceeded(request: UrlRequest?, info: UrlResponseInfo?) {
        Log.i(TAG, "onSucceeded method called.")
    }
}

Java

class MyUrlRequestCallback extends UrlRequest.Callback {
  private static final String TAG = "MyUrlRequestCallback";

  @Override
  public void onRedirectReceived(UrlRequest request, UrlResponseInfo info, String newLocationUrl) {
    Log.i(TAG, "onRedirectReceived method called.");
    // You should call the request.followRedirect() method to continue
    // processing the request.
    request.followRedirect();
  }

  @Override
  public void onResponseStarted(UrlRequest request, UrlResponseInfo info) {
    Log.i(TAG, "onResponseStarted method called.");
    // You should call the request.read() method before the request can be
    // further processed. The following instruction provides a ByteBuffer object
    // with a capacity of 102400 bytes for the read() method. The same buffer
    // with data is passed to the onReadCompleted() method.
    request.read(ByteBuffer.allocateDirect(102400));
  }

  @Override
  public void onReadCompleted(UrlRequest request, UrlResponseInfo info, ByteBuffer byteBuffer) {
    Log.i(TAG, "onReadCompleted method called.");
    // You should keep reading the request until there's no more data.
    byteBuffer.clear();
    request.read(byteBuffer);
  }

  @Override
  public void onSucceeded(UrlRequest request, UrlResponseInfo info) {
    Log.i(TAG, "onSucceeded method called.");
  }
}

יצירת אובייקט Executor לניהול משימות ברשת

אפשר להשתמש במחלקה Executor כדי להריץ משימות ברשת. כדי לקבל מופע של Executor, משתמשים באחת מהשיטות הסטטיות של המחלקה Executors שמחזירות אובייקט Executor. בדוגמה הבאה מוסבר איך ליצור אובייקט Executor באמצעות ה-method‏ newSingleThreadExecutor():

Kotlin

val executor: Executor = Executors.newSingleThreadExecutor()

Java

Executor executor = Executors.newSingleThreadExecutor();

יצירה והגדרה של אובייקט UrlRequest

כדי ליצור את הבקשה לאחזור מהרשת, מפעילים את ה-method‏ newUrlRequestBuilder() של CronetEngine ומעבירים את כתובת היעד, מופע של מחלקת הקריאה החוזרת (callback) ואת האובייקט של ה-executor. ה-method‏ newUrlRequestBuilder() מחזירה אובייקט UrlRequest.Builder שאפשר להשתמש בו כדי ליצור את האובייקט UrlRequest, כמו בדוגמה הבאה:

Kotlin

val requestBuilder = cronetEngine.newUrlRequestBuilder(
        "https://www.example.com",
        MyUrlRequestCallback(),
        executor
)

val request: UrlRequest = requestBuilder.build()

Java

UrlRequest.Builder requestBuilder = cronetEngine.newUrlRequestBuilder(
        "https://www.example.com", new MyUrlRequestCallback(), executor);

UrlRequest request = requestBuilder.build();

אפשר להשתמש במחלקה Builder כדי להגדיר את המופע של UrlRequest. לדוגמה, אפשר לציין עדיפות או פועל HTTP. מידע נוסף זמין במאמר UrlRequest.Builder.

כדי להתחיל את משימת הרשת, מפעילים את השיטה start() של הבקשה:

Kotlin

request.start()

Java

request.start();

כדי ליצור ולשלוח בקשה לאחזור מהרשת באמצעות Cronet, פועלים לפי ההוראות בקטע הזה. עם זאת, כדי לפשט את הדברים, ההטמעה לדוגמה של UrlRequest.Callback רק מדפיסה הודעה ביומן. בקטע הבא מוסבר איך לספק הטמעה של קריאה חוזרת (callback) שתומכת בתרחישים שימושיים יותר, כמו חילוץ נתונים מהתגובה וזיהוי כשל בבקשה.

עיבוד התגובה מהרשת

אחרי שקוראים ל-method‏ start(),‏ Cronet מתחיל את מחזור החיים של הבקשה. לנהל את הבקשה במהלך מחזור החיים על ידי ציון קריאה חוזרת (callback). למידע נוסף על מחזור החיים, קראו את המאמר מחזור החיים של בקשות Cronet. כדי לציין קריאה חוזרת, יוצרים מחלקת משנה של UrlRequest.Callback ומטמיעים את השיטות הבאות:

onRedirectReceived()

‫Cronet מפעיל את ה-method הזו כשהשרת מנפיק קוד הפניה אוטומטית של HTTP בתגובה לבקשה המקורית. כדי לעקוב אחרי ההפניה האוטומטית ליעד החדש, משתמשים ב-method‏ followRedirect(). אחרת, משתמשים ב-cancel(). בדוגמה הבאה אפשר לראות איך מטמיעים את השיטה:

Kotlin

override fun onRedirectReceived(request: UrlRequest?, info: UrlResponseInfo?, newLocationUrl: String?) {
  // Determine whether you want to follow the redirect.
  ...

  if (shouldFollow) {
      request?.followRedirect()
  } else {
      request?.cancel()
  }
}

Java

@Override
public void onRedirectReceived(UrlRequest request, UrlResponseInfo info, String newLocationUrl) {
  // Determine whether you want to follow the redirect.
  ...

  if (shouldFollow) {
    request.followRedirect();
  } else {
    request.cancel();
  }
}
onResponseStarted()

‫Cronet מפעיל את השיטה הזו כשמתקבלת קבוצת הכותרות הסופית. ‫Cronet מפעיל את onResponseStarted() רק אחרי שכל ההפניות האוטומטיות בוצעו. הקוד הבא מראה דוגמה להטמעה של השיטה:

Kotlin

override fun onResponseStarted(request: UrlRequest?, info: UrlResponseInfo?) {
  val httpStatusCode = info?.httpStatusCode
  if (httpStatusCode == 200) {
    // The request was fulfilled. Start reading the response.
    request?.read(myBuffer)
  } else if (httpStatusCode == 503) {
    // The service is unavailable. You should still check if the request
    // contains some data.
    request?.read(myBuffer)
  }
  responseHeaders = info?.allHeaders
}

Java

@Override
public void onResponseStarted(UrlRequest request, UrlResponseInfo info) {
  int httpStatusCode = info.getHttpStatusCode();
  if (httpStatusCode == 200) {
    // The request was fulfilled. Start reading the response.
    request.read(myBuffer);
  } else if (httpStatusCode == 503) {
    // The service is unavailable. You should still check if the request
    // contains some data.
    request.read(myBuffer);
  }
  responseHeaders = info.getAllHeaders();
}
onReadCompleted()

‫Cronet מפעיל את השיטה הזו בכל פעם שחלק מגוף התגובה נקרא. בדוגמת הקוד הבאה אפשר לראות איך להטמיע את השיטה ולחלץ את גוף התגובה:

Kotlin

override fun onReadCompleted(request: UrlRequest?, info: UrlResponseInfo?, byteBuffer: ByteBuffer?) {
  // The response body is available, process byteBuffer.
  ...

  // Continue reading the response body by reusing the same buffer
  // until the response has been completed.
  byteBuffer?.clear()
  request?.read(myBuffer)
}

Java

@Override
public void onReadCompleted(UrlRequest request, UrlResponseInfo info, ByteBuffer byteBuffer) {
  // The response body is available, process byteBuffer.
  ...

  // Continue reading the response body by reusing the same buffer
  // until the response has been completed.
  byteBuffer.clear();
  request.read(myBuffer);
}
onSucceeded()

‫Cronet מפעיל את השיטה הזו כשהבקשה לאחזור מהרשת מסתיימת בהצלחה. בדוגמה הבאה אפשר לראות איך מטמיעים את השיטה:

Kotlin

override fun onSucceeded(request: UrlRequest?, info: UrlResponseInfo?) {
    // The request has completed successfully.
}

Java

@Override
public void onSucceeded(UrlRequest request, UrlResponseInfo info) {
  // The request has completed successfully.
}
onFailed()

‫Cronet מפעיל את השיטה הזו אם הבקשה נכשלת מסיבה כלשהי אחרי שהאפליקציה קוראת לשיטה start(). בדוגמה הבאה אפשר לראות איך להטמיע את השיטה ולקבל מידע על השגיאה:

Kotlin

override fun onFailed(request: UrlRequest?, info: UrlResponseInfo?, error: CronetException?) {
    // The request has failed. If possible, handle the error.
    Log.e(TAG, "The request failed.", error)
}

Java

@Override
public void onFailed(UrlRequest request, UrlResponseInfo info, CronetException error) {
  // The request has failed. If possible, handle the error.
  Log.e(TAG, "The request failed.", error);
}
onCanceled()

‫Cronet מפעיל את השיטה הזו אם הבקשה בוטלה באמצעות השיטה cancel(). אחרי ש-Cronet מפעיל את onCanceled(), הוא לא מפעיל שיטות אחרות של המחלקה UrlRequest.Callback. אפשר להשתמש בשיטה הזו כדי לפנות משאבים שהוקצו לעיבוד בקשה. בדוגמה הבאה אפשר לראות איך מטמיעים את השיטה:

Kotlin

override fun onCanceled(request: UrlRequest?, info: UrlResponseInfo?) {
    // Free resources allocated to process this request.
    ...
}

Java

@Override
public void onCanceled(UrlRequest request, UrlResponseInfo info) {
  // Free resources allocated to process this request.
  ...
}