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

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

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

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

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

إتاحة ميزات لغة Java 8 (الإصدار 3.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android والإصدارات الأحدث)

لبدء استخدام ميزات لغة 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 ملاحظات
تعبيرات Lambda لا يتيح Android تسلسل تعبيرات lambda.
مراجع الطرق  
كتابة تعليقات توضيحية لا تتوفّر معلومات التعليقات التوضيحية للنوع إلا في وقت التجميع، وليس في وقت التشغيل. يتيح النظام الأساسي استخدام TYPE في المستوى 24 من واجهة برمجة التطبيقات والمستويات الأقدم، ولكن لا يتيح استخدام ElementType.TYPE_USE أو ElementType.TYPE_PARAMETER.
طرق الواجهة التلقائية والثابتة  
التعليقات التوضيحية المتكرّرة  

بالإضافة إلى ميزات لغة Java 8 هذه، يوفّر الإصدار 3.0.0 والإصدارات الأحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android إمكانية استخدام try-with-resources في جميع مستويات واجهة برمجة التطبيقات في 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 والإصدارات الأحدث التي تزيل التجميل اللغوي في الإصدار 3.0.0 والإصدارات الأحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android، ولا تتيح استخدام أي فئات وواجهات برمجة تطبيقات إضافية (مثل java.util.stream.*) في إصدارات Android القديمة. تتوفّر ميزة إزالة التجميل اللغوي الجزئي لواجهة برمجة التطبيقات Java API من الإصدار 4.0.0 أو الإصدارات الأحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android، كما هو موضّح في القسم التالي.

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

إذا كنت تنشئ تطبيقك باستخدام الإصدار 4.0.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android، يتيح المكوّن الإضافي استخدام عدد من واجهات برمجة التطبيقات للغة Java 8 بدون الحاجة إلى حدّ أدنى لمستوى واجهة برمجة التطبيقات في تطبيقك. ومع الإصدار 7.4.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android، يتوفّر أيضًا عدد من واجهات برمجة التطبيقات للغة 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 منفصلاً يحتوي على تنفيذ لواجهات برمجة التطبيقات غير المتوفّرة ويضمّنه في تطبيقك. تعيد عملية إزالة التجميل اللغوي كتابة رمز تطبيقك لاستخدام هذه المكتبة بدلاً من ذلك في وقت التشغيل. يتوفّر الرمز المصدر الذي تم تجميعه في ملف DEX المنفصل في مستودع desugar_jdk_libs على GitHub.

لتفعيل إتاحة واجهات برمجة التطبيقات الخاصة باللغة هذه على أي إصدار من نظام 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 الخاصة بالاختبار لقياس حالة التطبيق.

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

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

الإصدارات

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

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

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