از ویژگی ها و API های زبان جاوا 8 استفاده کنید

پلاگین Android Gradle نسخه 3.0.0 و جدیدتر از همه ویژگی های زبان جاوا 7 و زیرمجموعه ای از ویژگی های زبان جاوا 8 که بسته به نسخه پلتفرم متفاوت است، پشتیبانی می کند. هنگام ساخت برنامه خود با استفاده از افزونه Android Gradle نسخه 4.0.0 و بالاتر، می توانید از برخی از APIهای زبان جاوا 8 بدون نیاز به حداقل سطح API برای برنامه خود استفاده کنید.

این صفحه ویژگی های زبان جاوا 8 را که می توانید استفاده کنید، نحوه پیکربندی صحیح پروژه خود برای استفاده از آنها و هر مشکل شناخته شده ای که ممکن است با آن مواجه شوید را توضیح می دهد. ویدیوی زیر را برای مروری بر ویژگی های زبان جاوا 8 ببینید.

افزونه Android Gradle پشتیبانی داخلی را برای استفاده از برخی ویژگی‌های زبان جاوا 8 و کتابخانه‌های شخص ثالثی که از آنها استفاده می‌کنند، ارائه می‌کند. زنجیره ابزار پیش فرض ویژگی های زبان جدید را با انجام تبدیل بایت کد به نام desugar به عنوان بخشی از کامپایل D8/R8 از فایل های کلاس در کد DEX، همانطور که در شکل 1 نشان داده شده است، پیاده سازی می کند.

پشتیبانی از ویژگی زبان جاوا 8 (افزونه اندروید Gradle نسخه 3.0.0+)

برای شروع استفاده از ویژگی های زبان جاوا 8 پشتیبانی شده:

1. افزونه Android Gradle را به 3.0.0 یا بالاتر به روز کنید .
2. برای هر ماژول که از ویژگی های زبان جاوا 8 استفاده می کند (چه در کد منبع خود یا از طریق وابستگی ها)، فایل build.gradle یا build.gradle.kts ماژول را مطابق شکل زیر به روز کنید:

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"
    }
}

هنگام ساخت برنامه خود با استفاده از افزونه Android Gradle نسخه 3.0.0 و بالاتر، این افزونه از همه ویژگی های زبان جاوا 8 پشتیبانی نمی کند. ویژگی های زبان زیر در هر سطح API موجود است:

علاوه بر این ویژگی‌های زبان جاوا 8، افزونه Android Gradle نسخه 3.0.0 و بالاتر، پشتیبانی از try -with-resources را به تمام سطوح API 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+ در افزونه Android Gradle نسخه 3.0.0 و بالاتر از قندزدایی برخوردار است و هیچ کلاس و API اضافی (مانند java.util.stream.* ) را برای استفاده در نسخه‌های قدیمی‌تر Android در دسترس قرار نمی‌دهد. همانطور که در بخش زیر توضیح داده شده است، پشتیبانی از شکرزدایی جزئی Java API از پلاگین Android Gradle نسخه 4.0.0 یا بالاتر در دسترس است.

پشتیبانی از شکرزدایی API 8+ (Android Gradle Plugin 4.0.0+)

اگر برنامه خود را با استفاده از افزونه Android Gradle نسخه 4.0.0 یا بالاتر می‌سازید، این افزونه برای استفاده از تعدادی API زبان جاوا 8 بدون نیاز به حداقل سطح API برای برنامه شما پشتیبانی می‌کند. با افزونه Android Gradle نسخه 7.4.0 یا بالاتر، تعدادی از APIهای زبان جاوا 11 نیز با کتابخانه desugared نسخه 2.0.0 یا بالاتر در دسترس هستند.

این پشتیبانی اضافی برای نسخه‌های پلتفرم قدیمی‌تر امکان‌پذیر است، زیرا افزونه 4.0.0 و بالاتر موتور شیرین‌زدایی را به API‌های زبان جاوا نیز کاهش می‌دهد. می‌توانید APIهای زبان استانداردی را که فقط در نسخه‌های اخیر Android (مانند java.util.streams ) موجود بودند، در برنامه‌هایی که از نسخه‌های قدیمی‌تر Android پشتیبانی می‌کنند، اضافه کنید.

مجموعه APIهای زیر هنگام ساخت برنامه شما با استفاده از افزونه Android Gradle نسخه 4.0.0 یا بالاتر پشتیبانی می شوند:

• جریان های متوالی ( 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)

با افزونه Android Gradle نسخه 7.4.0 یا بالاتر، APIهای جاوا 11 اضافی مانند زیرمجموعه ای از بسته java.nio.file پشتیبانی می شوند.

برای فهرست کاملی از APIهای پشتیبانی شده، از Java 8+ APIهای موجود از طریق desugaring و Java 11+ APIهای موجود از طریق desugaring دیدن کنید.

برای پشتیبانی از این APIهای زبانی، این افزونه یک فایل DEX جداگانه که شامل پیاده سازی APIهای گمشده است را گردآوری می کند و آن را در برنامه شما قرار می دهد. فرآیند شیرین سازی کد برنامه شما را بازنویسی می کند تا در عوض از این کتابخانه در زمان اجرا استفاده کند.

برای فعال کردن پشتیبانی از این APIهای زبان در هر نسخه از پلتفرم Android:

1. افزونه Android Gradle را به 4.0.0 (یا بالاتر) به روز کنید .
2. موارد زیر را در فایل build.gradle یا build.gradle.kts ماژول برنامه خود قرار دهید:

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 یک ماژول کتابخانه قرار دهید اگر:

• آزمون‌های ابزاری ماژول کتابخانه از این APIهای زبان (به طور مستقیم یا از طریق ماژول کتابخانه یا وابستگی‌های آن) استفاده می‌کنند. این به این دلیل است که API های از دست رفته برای APK آزمایشی شما ارائه می شود.

• شما می خواهید lint را به صورت مجزا روی ماژول کتابخانه اجرا کنید. این برای کمک به لینت است که کاربردهای معتبر APIهای زبان را تشخیص دهد و از گزارش هشدارهای نادرست جلوگیری کند.

همچنین توجه داشته باشید که قندزدایی API را می توان با کوچک کردن ترکیب کرد، اما فقط در صورت استفاده از شرینکر R8.

نسخه ها

جدول زیر نسخه های کتابخانه Java 8+ API و حداقل نسخه پلاگین Android Gradle را نشان می دهد که از هر نسخه پشتیبانی می کند:

برای جزئیات بیشتر در مورد نسخه های کتابخانه Java 8+ API، به فایل CHANGELOG.md در مخزن desugar_jdk_libs GitHub مراجعه کنید.