استخدام ميزات لغة Java 8 وواجهات برمجة التطبيقات

ويتوافق الإصدار 3.0.0 من مكوّن Gradle الإضافي لنظام التشغيل Android والإصدارات الأحدث مع جميع ميزات لغة Java 7 ومجموعة فرعية من ميزات لغة Java 8 التي تختلف حسب إصدار النظام الأساسي. عند إنشاء تطبيقك باستخدام الإصدار 4.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android أو الإصدارات الأحدث، يمكنك استخدام بعض واجهات برمجة التطبيقات للغة Java 8 بدون الحاجة إلى مستوى أدنى لواجهة برمجة التطبيقات في تطبيقك.

تصف هذه الصفحة ميزات لغة Java 8 التي يمكنك استخدامها، وكيفية تهيئة مشروعك بشكل صحيح لاستخدامها، وأي مشكلات معروفة قد تواجهها. يمكنك الاطّلاع على الفيديو التالي للحصول على نظرة عامة حول ميزات لغة Java 8.

يوفّر مكوّن Gradle الإضافي لنظام التشغيل Android دعمًا مضمّنًا في استخدام بعض ميزات لغة Java 8 ومكتبات الجهات الخارجية التي تستخدمها. تنفِّذ سلسلة الأدوات التلقائية ميزات اللغة الجديدة من خلال إجراء عمليات تحويل رموز بايت، تُسمى desugar، كجزء من تجميع ملفات الفئة D8/R8 إلى رمز DEX، كما هو موضّح في الشكل 1.

إتاحة ميزة لغات Java 8 باستخدام عمليات تحويل رمز البايت `desugar`
الشكل 1. إتاحة ميزة لغات Java 8 باستخدام عمليات تحويل رمز البايت desugar.

إتاحة ميزة لغات Java 8 (Android Gradle Plugin 3.0.0 والإصدارات الأحدث)

لبدء استخدام ميزات لغة Java 8 المتوافقة:

  1. تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android إلى الإصدار 3.0.0 أو إصدار أحدث
  2. لكل وحدة تستخدم ميزات لغة Java 8 (إما في رمز المصدر أو من خلال التبعيات)، عليك تعديل ملف build.gradle أو build.gradle.kts الخاص بالوحدة كما هو موضّح أدناه:

لغة Kotlin

android {
    ...
    // Configure only for each module that uses Java 8
    // language features (either in its source code or
    // through dependencies).
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

رائع

android {
    ...
    // Configure only for each module that uses Java 8
    // language features (either in its source code or
    // through dependencies).
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

عند إنشاء تطبيقك باستخدام الإصدار 3.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android والإصدارات الأحدث، لا يدعم هذا المكوّن الإضافي جميع ميزات لغات Java 8. تتوفر ميزات اللغة التالية على أي مستوى لواجهة برمجة التطبيقات:

ميزة لغة Java 8 ملاحظات
تعبيرات لامدا لا يتيح Android التسلسل لتعبيرات lambda.
مراجع الطرق  
كتابة التعليقات التوضيحية تتوفّر معلومات التعليقات التوضيحية للنوع في وقت التجميع فقط، وليس في وقت التشغيل. تتيح المنصة استخدام السمة TYPE في المستوى 24 من واجهة برمجة التطبيقات والمستويات الأدنى، ولكن لا تتوافق مع السمة ElementType.TYPE_USE أو ElementType.TYPE_PARAMETER.
طُرق الواجهة التلقائية والثابتة  
تكرار التعليقات التوضيحية  

بالإضافة إلى هذه الميزات المتعلّقة بلغة Java 8، يتيح الإصدار 3.0.0 من نظام التشغيل Android Gradle الأحدث والإصدارات الأحدث لمحتوى try الذي يتضمّن موارد لجميع مستويات واجهة برمجة تطبيقات Android.

لا يتوافق برنامج Desugar مع MethodHandle.invoke أو MethodHandle.invokeExact. إذا كان رمز المصدر أو إحدى تبعيات الوحدة يستخدم إحدى هذه الطرق، عليك تحديد minSdkVersion 26 أو إصدار أعلى. وإلا، ستتلقى الخطأ التالي:

Dex: Error converting bytecode to dex:
Cause: signature-polymorphic method called without --min-sdk-version >= 26

في بعض الحالات، قد لا تستخدم الوحدة الطريقة invoke أو invokeExact حتى إذا كانت مضمّنة في إحدى تبعيات المكتبة. لمواصلة استخدام تلك المكتبة مع minSdkVersion 25 أو إصدار أقدم، يمكنك تفعيل ميزة تقليص الرموز لإزالة الطرق غير المستخدَمة. إذا لم ينجح ذلك، جرّب استخدام مكتبة بديلة لا تستخدم الطرق غير المتوافقة.

تتم إزالة ميزات لغة Java 8 والإصدارات الأحدث على إصدار Gradle المتوافق مع الإصدار 3.0.0 من نظام التشغيل Android والإصدارات الأحدث، ولا توفّر أي فئات وواجهات برمجة تطبيقات إضافية (مثل java.util.stream.*) للاستخدام على إصدارات Android القديمة. يتوفّر الدعم بشأن الإزالة الجزئية لواجهة برمجة تطبيقات Java من خلال الإصدار 4.0.0 من مكوّن Gradle المتوافق مع Android أو الإصدارات الأحدث، كما هو موضَّح في القسم التالي.

توافق واجهة برمجة التطبيقات Java 8 والإصدارات الأحدث (الإصدار 4.0.0 من Android Gradle الإضافي)

إذا كنت تصمّم تطبيقك باستخدام الإصدار 4.0.0 من مكوّن Gradle الإضافي لنظام التشغيل Android أو إصدار أحدث، سيوسّع المكوّن الإضافي الدعم لاستخدام عدد من واجهات برمجة التطبيقات اللغوية في لغة Java 8 بدون المطالبة بمستوى أدنى من واجهة برمجة التطبيقات لتطبيقك. وباستخدام الإصدار 7.4.0 من مكوّن Gradle الإضافي أو الإصدارات الأحدث، يتوفّر عدد من واجهات برمجة التطبيقات للغة Java 11 أيضًا مع الإصدار 2.0.0 أو الإصدارات الأحدث من المكتبة المصممة.

ويمكن الحصول على هذا الدعم الإضافي لإصدارات النظام الأساسي القديمة لأن المكوّن الإضافي 4.0.0 والإصدارات الأحدث منه يوسّع المحرك من محرك البحث ليشمل واجهات برمجة التطبيقات للغة Java أيضًا. يمكنك تضمين واجهات برمجة التطبيقات القياسية للغة والتي كانت متوفرة فقط في إصدارات Android الحديثة (مثل java.util.streams) في التطبيقات التي تتوافق مع إصدارات Android القديمة.

تتوفر المجموعة التالية من واجهات برمجة التطبيقات عند إنشاء تطبيقك باستخدام الإصدار 4.0.0 من مكوّن Gradle الإضافي أو الإصدارات الأحدث من Android:

  • ساحات المشاركات المتسلسلة (java.util.stream)
  • مجموعة فرعية من java.time
  • java.util.function
  • آخر الإضافات إلى java.util.{Map,Collection,Comparator}
  • اختيارية (java.util.Optional وjava.util.OptionalInt و java.util.OptionalDouble) وبعض الصفوف الجديدة
  • بعض الإضافات إلى java.util.concurrent.atomic (طرق جديدة على AtomicInteger وAtomicLong وAtomicReference)
  • ConcurrentHashMap (مع إصلاحات الأخطاء لنظام التشغيل Android 5.0)

من خلال الإصدار 7.4.0 من مكوّن Gradle الإضافي لنظام التشغيل Android أو الإصدارات الأحدث، تتوافق واجهات برمجة التطبيقات الإضافية في Java 11 مثل مجموعة فرعية من حزمة java.nio.file.

للحصول على قائمة كاملة بواجهات برمجة التطبيقات المتوافقة، يمكنك الانتقال إلى واجهات برمجة التطبيقات Java 8+ والمتاحة من خلال إزالة الكم وواجهات برمجة تطبيقات Java 11 والإصدارات الأحدث المتوفرة من خلال إزالة الكميات.

ولدعم واجهات برمجة التطبيقات هذه للغات، يجمع المكوّن الإضافي ملف DEX منفصلاً يحتوي على تنفيذ لواجهات برمجة التطبيقات المفقودة ويضمِّنه في تطبيقك. تؤدي عملية الإزالة إلى إعادة كتابة رمز تطبيقك لاستخدام هذه المكتبة في وقت التشغيل بدلاً من ذلك.

لتفعيل التوافق مع واجهات برمجة التطبيقات هذه للّغة على أي إصدار من نظام Android الأساسي:

  1. تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android إلى الإصدار 4.0.0 (أو إصدار أحدث)
  2. أدرِج ما يلي في ملف build.gradle أو build.gradle.kts الخاص بوحدة التطبيق:

لغة Kotlin

android {
    defaultConfig {
        // Required when setting minSdkVersion to 20 or lower
        multiDexEnabled = true
    }

    compileOptions {
        // Flag to enable support for the new language APIs

        // For AGP 4.1+
        isCoreLibraryDesugaringEnabled = true
        // For AGP 4.0
        // coreLibraryDesugaringEnabled = true

        // Sets Java compatibility to Java 8
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.3")
    // For AGP 7.3
    // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.2.3")
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.9")
}

رائع

android {
    defaultConfig {
        // Required when setting minSdkVersion to 20 or lower
        multiDexEnabled true
    }

    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.3'
    // For AGP 7.3
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.2.3'
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.9'
}

تجدر الإشارة إلى أنّك قد تحتاج أيضًا إلى تضمين مقتطف الرمز السابق في ملف build.gradle أو build.gradle.kts الخاص بوحدة المكتبة في الحالات التالية:

  • تستخدم الاختبارات الآلية في وحدة المكتبة واجهات برمجة التطبيقات اللغوية هذه (إما بشكل مباشر أو من خلال وحدة المكتبة أو تبعياتها). وذلك حتى يتم توفير واجهات برمجة التطبيقات المفقودة لحزمة APK للاختبار الموزع.

  • تريد تشغيل أداة لينت على وحدة المكتبة بمعزل عن بعضها البعض. ويساعد هذا الإجراء في التعرّف على الاستخدامات الصالحة لواجهات برمجة التطبيقات الخاصة باللغة وتجنُّب الإبلاغ عن تحذيرات كاذبة.

يُرجى العلم أيضًا أنّه يمكن دمج عملية إزالة التكميل من واجهة برمجة التطبيقات مع ميزة تقليص، ولكن فقط عند استخدام تقليص R8.

الإصدارات

يعرض الجدول التالي إصدارات مكتبة واجهة برمجة التطبيقات Java 8+ والحدّ الأدنى من إصدار مكوّن Android Gradle الإضافي الذي يتوافق مع كل إصدار:

الإصدار الحد الأدنى لإصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android
1.1.9 4
1.2.3 7.3
2.0.3 7.4.0-alpha10

للحصول على تفاصيل حول إصدارات مكتبة واجهة برمجة التطبيقات Java 8+ ، يمكنك الاطّلاع على ملف CHANGELOG.md في مستودع GitHub desugar_jdk_libs.