تنفيذ مكتبة Java SDK

يحتوي نظام Android الأساسي على عدد كبير من مكتبات Java المشتركة التي يمكن تضمينها اختياريًا في مسار فئة التطبيقات باستخدام علامة <uses-library> في بيان التطبيق. رابط التطبيقات مقابل هذه المكتبات، لذا تعامل معها كباقي واجهة برمجة تطبيقات Android من حيث التوافق ومراجعة واجهة برمجة التطبيقات ودعم الأدوات. ومع ذلك، لاحظ أنه أن معظم المكتبات لا تتضمن هذه الميزات.

يساعد نوع الوحدة java_sdk_library في إدارة المكتبات. من هذا النوع. يمكن للشركات المصنّعة للأجهزة استخدام هذه الآلية بأنفسهم مكتبات Java المشتركة، للحفاظ على التوافق مع الأنظمة القديمة لواجهات برمجة التطبيقات الخاصة بها. إذا كانت الشركات المصنّعة للأجهزة تستخدم مكتبات Java المشتركة الخاصة بها من خلال <uses-library> بدلاً من مسار فئة التشغيل، بإمكان java_sdk_library التحقق من أن مكتبات Java هذه واجهة برمجة تطبيقات ثابتة.

تنفِّذ java_sdk_library واجهات برمجة تطبيقات اختيارية لحزمة تطوير البرامج (SDK) لاستخدامها من خلال التطبيقات. المكتبات التي تم تنفيذها من خلال java_sdk_library في ملف الإصدار (Android.bp) بتنفيذ العمليات التالية:

• يتم إنشاء مكتبات الرموز الموجزة لتضمين stubs، stubs.system وstubs.test هذه عن طريق التعرّف على @hide، تعليقات @SystemApi و@TestApi التوضيحية
• يدير java_sdk_library ملفات مواصفات واجهة برمجة التطبيقات (مثل current.txt) في دليل فرعي لواجهة برمجة التطبيقات. هذه الملفات يتم التحقق منها مقابل أحدث رمز للتأكد من أنها الأكثر والإصدارات الحالية. إذا لم تكن كذلك، ستتلقّى رسالة خطأ تفيد ويشرح كيفية تحديثها. مراجعة جميع تغييرات التحديث يدويًا والتأكد من أنها تتوافق مع توقعاتك.
  
  لتحديث جميع واجهات برمجة التطبيقات، استخدِم m update-api. للتأكّد من أنّ واجهة برمجة التطبيقات محدَّثة، استخدام m checkapi.
• يتم التحقّق من ملفات مواصفات واجهة برمجة التطبيقات بأحدث بيانات إصدارات Android المنشورة لضمان توافق واجهة برمجة التطبيقات مع الأنظمة القديمة مع الإصدارات السابقة. تم توفير java_sdk_library وحدة. كجزء من AOSP وضع إصداراتهم التي تم إصدارها سابقًا في prebuilts/sdk/<latest number>
• وفي ما يتعلق بعمليات التحقق من ملفات مواصفات واجهة برمجة التطبيقات، يمكنك إجراء أحد العناصر الثلاثة التالية:
• اسمح بمواصلة عمليات التحقّق. (لا تفعل أي شيء).
• يمكنك إيقاف عمليات التحقق من خلال إضافة ما يلي إلى java_sdk_library:
  unsafe_ignore_missing_latest_api: true,
• توفير واجهات برمجة تطبيقات فارغة لوحدات java_sdk_library الجديدة عن طريق إنشاء ملفات نصية فارغة باسم module_name.txt في دليل version/scope/api.
• إذا تم تثبيت مكتبة التنفيذ الخاصة ببيئة التشغيل، يتم استخدام ملف XML يتم إنشاؤه وتثبيته.

طريقة عمل java_sdk_library

عنصر java_sdk_library يسمى X ينشئ ما يلي:

1. نسختان من مكتبة التنفيذ: مكتبة باسم X والآخر يسمى X.impl. تم تثبيت المكتبة X على الجهاز فقط. تتوفر المكتبة X.impl فقط في حالة الوصول الصريح إلى مكتبة التنفيذ مطلوبة من قِبل وحدات أخرى، مثل استخدامها في اختبار الفرضية. يُرجى العِلم أنّه نادرًا ما تكون هناك حاجة إلى إذن الوصول الصريح.
2. يمكن تفعيل النطاقات وإيقافها لتخصيص الوصول. (مماثل لـ Java معدِّلات الوصول إلى الكلمات الرئيسية، فإن النطاق العام يوفر نطاقًا كبيرًا من الوصول؛ CANNOT TRANSLATE يحتوي نطاق الاختبار على واجهات برمجة تطبيقات لا تُستخدم إلا في الاختبار). لكل نطاق مفعَّل ما يلي:
• تستهلك وحدة مصدر التشعّبات (من نوع وحدة droidstubs) مصدر التنفيذ، وتُخرج مجموعة من المصادر البديلة إلى جانب ملف مواصفات واجهة برمجة التطبيقات.
• مكتبة الأكواد (من نوع وحدة java_library) - هي نسخة مجمعة من التنويهات. المكتبات المستخدمة لتجميع هذه ليست هي البيانات نفسها المقدّمة إلى java_sdk_library، ما يضمن عدم تسرب تفاصيل التنفيذ إلى حقول واجهة برمجة التطبيقات.
• إذا كنت بحاجة إلى مكتبات إضافية لتجميع التنويهات الموجزة، فاستخدم stub_only_libs وstub_only_static_libs الخصائص لعرضها.

إذا كان اسم java_sdk_library يسمّى "X" مجمعة مقابل "X"، فاشير إليها دائمًا بهذه الطريقة ولا تعدل بها. سيختار الإصدار مكتبة مناسبة. للتأكد من حصولك على المكتبة الأنسب لك، وافحص بذور النصوص البرمجية لمعرفة ما إذا كان الإصدار قد تم الأخطاء. عليك إجراء أي تصحيحات ضرورية باستخدام هذه الإرشادات:

• تحقق من وجود مكتبة مناسبة من خلال البحث في سطر الأوامر وفحص البذور المدرجة هناك لتحديد نطاقك:
• النطاق واسع جدًا: تحتاج المكتبة المستندة إلى نطاق معيّن من واجهات برمجة التطبيقات. لَكِنْ ترى واجهات برمجة التطبيقات المضمنة في المكتبة التي تقع خارج هذا النطاق، مثل واجهات برمجة تطبيقات النظام المضمّنة في واجهات برمجة التطبيقات العامة.
• النطاق ضيّق جدًا: لا يمكن للمكتبة التي تعتمد على هذا الوصول إلى جميع المكتبات المطلوبة. على سبيل المثال، تحتاج المكتبة بناءً على ذلك إلى استخدام ولكن تحصل على واجهة برمجة التطبيقات العامة بدلاً من ذلك. يؤدي هذا عادةً إلى حدث خطأ في التحويل البرمجي بسبب عدم توفر واجهات برمجة التطبيقات المطلوبة.
• لإصلاح المكتبة، نفِّذ واحدًا فقط من الإجراءات التالية:
• ويجب تغيير "sdk_version" لاختيار الإصدار المطلوب. أو
• تحديد المكتبة المناسبة بوضوح، مثل <X>.stubs أو <X>.stubs.system.

استخدام java_sdk_library X

يتم استخدام مكتبة التنفيذ X عند الإشارة إليها من apex.java_libs ومع ذلك، ونظرًا لقيود "سونغ"، عندما تكون المكتبة تتم الإشارة إلى X من وحدة java_sdk_library أخرى. ضمن مكتبة APEX نفسها، X.impl بشكل صريح يجب استخدامه، وليس المكتبة X.

عند الإشارة إلى java_sdk_library من مكان آخر، يتم استخدام رمز بديل استخدام المكتبة. يتم اختيار مكتبة التنويهات الموجزة وفقًا إعداد خاصية sdk_version للوحدة. على سبيل المثال، الوحدة التي يحدد sdk_version: "current" يستخدم الروابط العامة، في حين أن التي تحدد sdk_version: "system_current" تستخدم الأجزاء الناقصة للنظام. إذا تعذر العثور على تطابق تام، يتم الحصول على أقرب مكتبة بدائل استخدام البيانات المختلفة. إنّ java_sdk_library الذي لا يوفّر سوى واجهة برمجة تطبيقات عامة وتوفير التصاريح العامة للجميع.

الأمثلة والمصادر

يجب السمتَين srcs وapi_packages. المشاركة في "java_sdk_library"

java_sdk_library {
        name: "com.android.future.usb.accessory",
        srcs: ["src/**/*.java"],
        api_packages: ["com.android.future.usb"],
    }

تقترح "الشريك المعتمد من Google للناشرين" (AOSP) استخدام "java_sdk_library" الجديد، بدون الحاجة إلى ذلك على تفعيل نطاقات واجهة برمجة التطبيقات التي يريدون استخدامها. يمكنك أيضًا (اختياريًا) نقل مثيلات java_sdk_library الحالية إلى تفعيل نطاقات واجهة برمجة التطبيقات التي سيستخدمونها بشكل صريح:

java_sdk_library {
         name: "lib",
         public: {
           enabled: true,
         },
         system: {
           enabled: true,
         },
         …
    }

لضبط مكتبة impl المُستخدَمة لبيئة التشغيل، استخدِم الكل سمات java_library العادية، مثل hostdex، compile_dex، وerrorprone.

java_sdk_library {
        name: "android.test.base",

        srcs: ["src/**/*.java"],

        errorprone: {
          javacflags: ["-Xep:DepAnn:ERROR"],
        },

        hostdex: true,

        api_packages: [
            "android.test",
            "android.test.suitebuilder.annotation",
            "com.android.internal.util",
            "junit.framework",
        ],

        compile_dex: true,
    }

لإعداد مكتبات التنويهات الموجزة، استخدِم السمات التالية:

• merge_annotations_dirs وmerge_inclusion_annotations_dirs
• api_srcs: قائمة بملفات المصدر الاختيارية التي تكون جزءًا من واجهة برمجة التطبيقات ولكن ليس جزءًا من مكتبة بيئة التشغيل.
• stubs_only_libs: قائمة مكتبات Java الموجودة في مسار الفئات عند إنشاء البُنى الأساسية.
• hidden_api_packages: قائمة بأسماء الحِزم التي يجب أن تكون مخفي من واجهة برمجة التطبيقات.
• droiddoc_options: وسيطة إضافية لـ ميتلافا
• droiddoc_option_files: يسرد الملفات التي يمكن الإشارة إليها من داخل droiddoc_options باستخدام $(location <label>)، حيث <file> هو إدخال في القائمة.
• annotations_enabled.

java_sdk_library هو java_library، ولكنه ليس وحدة droidstubs وبالتالي لا تتوافق مع جميع وحدات droidstubs المواقع. المثال التالي مأخوذ من إصدار مكتبة android.test.mock الملف.

java_sdk_library {
        name: "android.test.mock",

        srcs: [":android-test-mock-sources"],
        api_srcs: [
            // Note: The following aren’t APIs of this library. Only APIs under the
            // android.test.mock package are taken. These do provide private APIs
            // to which android.test.mock APIs reference. These classes are present
            // in source code form to access necessary comments that disappear when
            // the classes are compiled into a Jar library.
            ":framework-core-sources-for-test-mock",
            ":framework_native_aidl",
        ],

        libs: [
            "framework",
            "framework-annotations-lib",
            "app-compat-annotations",
            "Unsupportedappusage",
        ],

        api_packages: [
            "android.test.mock",
        ],
        permitted_packages: [
            "android.test.mock",
        ],
        compile_dex: true,
        default_to_stubs: true,
    }

الحفاظ على التوافق مع الأنظمة القديمة

يتحقّق نظام الإصدار مما إذا كانت واجهات برمجة التطبيقات قد حافظت على الإصدارات القديمة. من خلال مقارنة أحدث ملفات واجهة برمجة التطبيقات مع الملفات التي تم إنشاؤها، ملفات واجهة برمجة التطبيقات في وقت الإصدار. ينفذ java_sdk_library التحقّق من التوافق باستخدام المعلومات المقدَّمة من prebuilt_apis. يجب أن تحتوي جميع المكتبات التي تم إنشاؤها باستخدام java_sdk_library على ملفات واجهة برمجة التطبيقات. في أحدث إصدار من api_dirs في prebuilt_apis. عند طرح الإصدار، تُدرج واجهة برمجة التطبيقات الملفات والرموز البديلة. يمكن الحصول على المكتبات باستخدام إصدار Dist باستخدام PRODUCT=sdk_phone_armv7-sdk.

السمة api_dirs هي قائمة بأدلة إصدارات واجهة برمجة التطبيقات. في prebuilt_apis. يجب أن تكون أدلة إصدار واجهة برمجة التطبيقات على مستوى دليل Android.bp.

prebuilt_apis {
       name: "foo",
       api_dirs: [
           "1",
           "2",
             ....
           "30",
           "current",
       ],
    }

إعداد الأدلة باستخدام version/scope/api/ ضمن الدليل المُنشأ مسبقًا. version مع مستوى واجهة برمجة التطبيقات ويحدد scope سواء كان الدليل عامًا أو نظامًا أو اختبارًا.

• version/scope يحتوي على مكتبات Java.
• يحتوي version/scope/api على واجهة برمجة تطبيقات .txt ملفًا. إنشاء ملفات نصية فارغة باسم module_name.txt وmodule_name-removed.txt هنا.

   ├── 30
        │   ├── public
        │   │   ├── api
        │   │   │   ├── android.test.mock-removed.txt
        │   │   │   └── android.test.mock.txt
        │   │   └── android.test.mock.jar
        │   ├── system
        │   │   ├── api
        │   │   │   ├── android.test.mock-removed.txt
        │   │   │   └── android.test.mock.txt
        │   │   └── android.test.mock.jar
        │   └── test
        │       ├── api
        │       │   ├── android.test.mock-removed.txt
        │       │   └── android.test.mock.txt
        │       └── android.test.mock.jar
        └── Android.bp